Skip to content
This repository was archived by the owner on Aug 5, 2022. It is now read-only.

Commit 703b877

Browse files
zolkiszolkis
committed
Board: split into smaller modules, support pin namespaces for OS and board
Signed-off-by: Zoltan Kis <[email protected]>
1 parent 89db4e8 commit 703b877

File tree

10 files changed

+187
-182
lines changed

10 files changed

+187
-182
lines changed

‎board/README.md

+22-84
Original file line numberDiff line numberDiff line change
@@ -9,119 +9,57 @@ The [Board](#board) API provides low level interfaces for I/O operations:
99
- [SPI - Serial Peripheral Interface](./spi.md)
1010
- [UART - Universal Asynchronous Receiver/Transmitter](./uart.md).
1111

12-
This API uses board pin names as defined in the corresponding board documentation.
13-
The names, values and semantics related to hardware pins are owned and encapsulated by the implementation. This API uses opaque values (strings and numbers) for [`Pin`](#pin) names.
12+
Hardware pin names are usually marked on the circuit boards. However, operating systems, such as [Zephyr](https://www.zephyrproject.org/doc/) define a pin name mapping that is consistent across the boards supported by the OS. This API supports both board and OS defined namespaces. In this API, [`Pin`](#pin) names are opaque to the application. Applications can open a given pin with a pin name that is either a string or a number, in either board or OS namespace. Implementations encapsulate the pin mapping. Also, the API exposes board name, OS name (including OS version) and API version for all board APIs.
1413

15-
The supported board documentations are listed in [this directory](./):
14+
The supported board namespaces are listed in [this directory](./):
1615
- [arduino101.md](./arduino101.md)
1716
- [frdm_k64f.md](./frdm_k64f.md).
1817

19-
The full Web IDL definition for Board and IO APIs can be found [here](./webidl.md).
18+
For the supported OS pin namespace, consult the documentation of the implementation and its underlying OS documentation.
19+
20+
The full Web IDL definition for Board and IO APIs can be found in [webidl.md](./webidl.md).
2021

2122
The `Board` API object
2223
----------------------
23-
The API entry point is a [`Board`](./#board) object that is exposed in a platform-specific manner. As an example, on Node.js it can be obtained by requiring the package that implements this API.
24+
The API entry point is a [`Board`](#board) object provided by an implementation (module).
25+
When requiring `"board"`, the following steps are run:
26+
- If there is no permission for using the functionality, throw `SecurityError`.
27+
- If the [Board](#board) functionality is not supported on the board, throw `"NotSupportedError"`.
28+
- Let `board` be the Board API object, and initialize it by fetching board name and OS name. Return `board`.
2429

25-
In the following example, the application requires an implementation that exposed Arduino 101 values and semantics for pins.
2630
```javascript
2731
var board = require("board");
2832

29-
console.log("Connected to board: " + board.name);
33+
console.log("Connected to board: " + board.name + " running " + board.os);
3034
```
3135

32-
On other platforms, e.g. in browsers, the API entry point can be exposed on another object, or constructed.
33-
```javascript
34-
var board = new Board(); // provides an instance of the default board
35-
```
36-
37-
If the functionality is not supported by the platform, `require` should throw `NotSupportedError`. If there is no permission for using the functionality, `require` should throw `SecurityError`.
38-
39-
<a name="pin"></a>
40-
### The `Pin` interface
41-
Represents a hardware pin on the board.
42-
43-
| Property | Type | Optional | Default value | Represents |
44-
| --- | --- | --- | --- | --- |
45-
| `pin` | String or Number | no | `undefined` | board name for the pin |
46-
47-
The read-only `pin` property is the board-specific name or numeric value of a pin, as defined in the board documentation.
48-
49-
In future versions of the API the `Pin` object may be extended.
36+
If the functionality is not supported by the platform, `require` should throw `NotSupportedError`.
5037

5138
<a name="board"></a>
5239
### The `Board` interface
53-
Represents a hardware board.
40+
Represents a hardware circuit board such as Arduino 101.
5441

5542
| Property | Type | Optional | Default value | Represents |
5643
| --- | --- | --- | --- | --- |
57-
| [`name`](#name) | String | no | `undefined` | board name |
58-
| [`version`](#version) | String | no | `versions.board` in [`package.json`](../package.json) | API version |
59-
60-
| Method | Description |
61-
| --- | --- |
62-
| [`aio()`](#aio) | request an AIO object |
63-
| [`gpio()`](#gpio) | request a GPIO object |
64-
| [`pwm()`](#pwm) | request a PWM object |
65-
| [`i2c()`](#i2c) | request an I2C object |
66-
| [`spi()`](#spi) | request an SPI object |
67-
| [`uart()`](#uart) | request an UART object |
44+
| [`name`](#boardname) | String | no | `undefined` | board name |
45+
| [`os`](#osname) | String | no | `undefined` | OS name |
46+
| [`apiVersion`](#apiversion) | String | no | `versions.board` in [`package.json`](../package.json) | API version |
6847

6948
| Event name | Event callback argument |
7049
| -------------- | ----------------------- |
7150
| `error` | [`Error`](#error) object |
7251

73-
<a name="name"></a>
52+
<a name="boardname"></a>
7453
The `name` property is read-only, and provides the board name.
7554

76-
<a name="version"></a>
77-
The `version` property is read-only, and provides the provides the Board API version, as specified in the `versions.board` property of [`package.json`](../package.json).
55+
<a name="osname"></a>
56+
The `os` property is read-only, and provides the underlying operating system name.
57+
58+
<a name="apiversion"></a>
59+
The `apiVersion` property is read-only, and provides the provides the Board API version, as specified in the `versions.board` property of [`package.json`](../package.json).
7860

7961
<a name="error"></a>
8062
Board errors are represented as augmented [`Error`](https://nodejs.org/api/errors.html#errors_class_error) objects. The following [`Error` names](https://nodejs.org/api/errors.html) are used for signaling issues:
8163
- `BoardDisconnectError`
8264
- `BoardTimeoutError`
8365
- `BoardIOError`.
84-
85-
#### `Board` methods
86-
87-
<a name="aio"></a>
88-
##### The `aio()` method
89-
Provides the AIO API object. The method runs the following steps:
90-
- If the AIO functionality is not supported on the board, throw `"NotSupportedError"`.
91-
- Initialize AIO functionality on the board. If it fails, throw `"SystemError"`.
92-
- Let `aio` be the [AIO API object](./aio.md/#apiobject). Return `aio`.
93-
94-
<a name="gpio"></a>
95-
##### The `gpio()` method
96-
Provides the GPIO API object. The method runs the following steps:
97-
- If the GPIO functionality is not supported on the board, throw `"NotSupportedError"`.
98-
- Initialize GPIO functionality on the board. If it fails, throw `"SystemError"`.
99-
- Let `gpio` be the [GPIO API object](./gpio.md/#apiobject). Return `gpio`.
100-
101-
<a name="pwm"></a>
102-
##### The `pwm()` method
103-
Provides the PWM API object. The method runs the following steps:
104-
- If the PWM functionality is not supported on the board, throw `"NotSupportedError"`.
105-
- Initialize PWM functionality on the board. If it fails, throw `"SystemError"`.
106-
- Let `pwm` be the [PWM API object`](./pwm.md/#apiobject). Return `pwm`.
107-
108-
<a name="i2c"></a>
109-
##### The `i2c()` method
110-
Provides the I2C API object. The method runs the following steps:
111-
- If the I2C functionality is not supported on the board, throw `"NotSupportedError"`.
112-
- Initialize I2C functionality on the board. If it fails, throw `"SystemError"`.
113-
- Let `i2c` be the [I2C API Object](./i2c.md/#apiobject). Return `pwm`.
114-
115-
<a name="spi"></a>
116-
##### The `spi()` method
117-
Provides the SPI API object. The method runs the following steps:
118-
- If the SPI functionality is not supported on the board, throw `"NotSupportedError"`.
119-
- Initialize SPI functionality on the board. If it fails, throw `"SystemError"`.
120-
- Let `spi` be the [SPI API object](./spi.md/#apiobject). Return `spi`.
121-
122-
<a name="uart"></a>
123-
##### The `uart()` method
124-
Provides the UART API object. The method runs the following steps:
125-
- If the UART functionality is not supported on the board, throw `"NotSupportedError"`.
126-
- Initialize UART functionality on the board. If it fails, throw `"SystemError"`.
127-
- Let `uart` be the [UART API object](./uart.md/#apiobject) object. Return `uart`.

‎board/aio.md

+22-16
Original file line numberDiff line numberDiff line change
@@ -3,39 +3,44 @@ AIO API
33

44
The AIO API supports reading analog input pins that measure the analog voltage signal between 0 and a maximum voltage (usually 3.3 or 5 Volts), then do Analog-to-Digital Conversion (ADC) with a resolution of 10 or 12 bits on most boards, so that the result (pin value) is 0 to 1023 or 0 to 4095, inclusively.
55

6-
On some boards access to AIO may be asynchronous. This API uses synchronous methods.
6+
On some boards access to AIO may be asynchronous. This API uses synchronous methods for allowing lean implementations.
77

88
<a name="apiobject"></a>
99
### The AIO API object
10-
AIO functionality is exposed by an object that can be obtained by using the [`aio()`](./README.md/#aio) method of the [`Board` API](./README.md/#board). See also the [Web IDL](./webidl.md). The API object exposes the following method:
10+
When requiring `"aio"`, the following steps are run:
11+
- If there is no permission for using the functionality, throw `SecurityError`.
12+
- If the AIO functionality is not supported on the board, throw `"NotSupportedError"`.
13+
- Return an object that implements the following method.
1114

1215
| Method | Description |
1316
| --- | --- |
14-
| [`open()`](#open) | synchronous open |
17+
| [`open()`](#open) | open an AIO pin |
18+
19+
See also the [Web IDL](./webidl.md) definition.
1520

1621
<a name="open"></a>
1722
#### The `AIO open(options)` method
1823
Configures an AIO pin using data provided by the `options` argument. It involves the following steps:
1924
- If `options` is a string, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
20-
- Otherwise if `options` is a number, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
21-
- Otherwise if `options` is a dictionary, let `init` be `options`. It may contain the following [`AIO`](#aio) properties, where at least `pin` MUST be specified:
22-
* `pin` for board pin name with the valid values defined by the board, or for the numeric index of the analog pin;
25+
- Otherwise if `options` is a number, create a dictionary 'init' and let `init.name` be `options`.
26+
- Otherwise if `options` is a dictionary, let `init` be `options`. It may contain the following [`AIO`](#aio) properties, where at least `name` MUST be specified:
27+
* `name` for board pin name with the valid values defined by the board, or for the numeric index of the analog pin;
28+
* `mapping` to specify if OS or board namespace is to be used with the pin (by default `"os"`).
2329
* `precision` for the bit width of a sample (if the board supports setting the sampling rate).
24-
- If any property of `init` is specified and has an invalid value on the given board, as defined by the board documentation, throw `TypeError`.
25-
- Request the underlying platform to initialize AIO on `init.pin` (if defined) or otherwise `init.channel`.
26-
- In case of failure, throw `InvalidAccessError`.
27-
- Let `aio` be the `AIOPin`](#aiopin) object that represents the hardware pin identified by `init.pin`, as defined by the board documentation.
28-
- If `init.precision` is defined, request the board to set the precision and initialize the `aio.precision` property with the value supported by the board. If there is an error, throw `InvalidAccessError`.
30+
- If any property of `init` is specified and has an invalid value, throw `TypeError`.
31+
- Request the underlying platform to initialize AIO on the pin identified by `init.name` in the namespace specified by `init.mapping`, or if not found, then in the other namespace. In case of failure, throw `InvalidAccessError`.
32+
- Let `aio` be the `AIOPin`](#aiopin) object that represents the hardware pin identified by `init.name`.
33+
- If `init.precision` is defined, request the board to set the precision and initialize the `aio.precision` property with the value supported by the underlying platform. If there is an error, throw `InvalidAccessError`.
2934
- Initialize the `aio.value` property with `undefined`.
3035
- Return the `aio` object.
3136

3237
<a name="aio"></a>
3338
### The `AIO` interface
34-
The `AIO` object extends the [`Pin`](./README.md/#pin) object.
3539

3640
| Property | Type | Optional | Default value | Represents |
3741
| --- | --- | --- | --- | --- |
38-
| `pin` | String or Number | no | `undefined` | board name for the pin |
42+
| `name` | String or Number | no | `undefined` | pin name |
43+
| `mapping` | enum | no | `"os"` | pin mapping, `"os"` or `"board"` |
3944
| `precision` | unsigned long | yes | `undefined` | bit length of digital sample |
4045

4146
| Method | Description |
@@ -58,13 +63,14 @@ Called when the application is no longer interested in the pin. Until the next [
5863
### Examples
5964
```javascript
6065
try {
61-
var aio = require("board").aio(); // initialize AIO on the board
66+
var aio = require("aio"); // initialize AIO on the board
6267

63-
var a1 = aio.open("A1");
68+
var a1 = aio.open(1); // pin 1 in OS namespace
6469
console.log(board.name + " AIO pin 1 value: " + a1.read());
6570
a1.close();
6671

67-
var a4 = aio.open({pin: "A4", precision: 12 });
72+
// Open pin A4 in board namespace, i.e. the value printed on the board
73+
var a4 = aio.open({pin: "A4", mapping: "board", precision: 12 });
6874

6975
setTimeout(function() {
7076
a4.close();

‎board/arduino101.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Board Support for Arduino 101
22
=============================
33

4-
This document defines the pin values that are accepted by implementations.
4+
This document defines the pin values that are accepted by implementations on board namespace.
55

66
The board labels are described in the [Arduino 101](https://www.arduino.cc/en/Main/ArduinoBoard101) board documentation. Also, for each board pin, the supported modes of each pin is described.
77

‎board/frdm_k64f.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Board Support for FRDM-K64F
22
===========================
33

4+
This document defines the pin values that are accepted by implementations on board namespace.
5+
46
The FRDM-K64F board pin names and locations are shown [here](https://developer.mbed.org/platforms/FRDM-K64F/).
57

68
There are 16 general purpose I/O pins, `D0` - `D15`. `D14` and `D15` can currently be used as GPIO_INs but not as outputs.

0 commit comments

Comments
 (0)