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

Commit 1526512

Browse files
zolkiszolkis
committed
Board: update pins vs channel, editorials
Signed-off-by: Zoltan Kis <[email protected]>
1 parent 728790a commit 1526512

File tree

11 files changed

+333
-374
lines changed

11 files changed

+333
-374
lines changed

‎api/board/README.md

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -43,27 +43,10 @@ Represents a hardware pin on the board.
4343
| Property | Type | Optional | Default value | Represents |
4444
| --- | --- | --- | --- | --- |
4545
| `pin` | String or Number | no | `undefined` | board name for the pin |
46-
| `mode` | String | no | `undefined` | I/O mode |
47-
48-
All properties are read-only.
49-
50-
The `pin` property is the board-specific name of a pin defined in the pin mapping of the board.
51-
52-
<a name="pinmode">
53-
The `mode` property can take the following values:
54-
- `"input"` for digital input (GPIO). The pin value can be 0 or 1.
55-
- `"output"` for digital output (GPIO). The pin value can be 0 or 1.
56-
- `"analog-in"` for analog input (AIO) that is converted to digital value.
57-
- `"analog-out"` for analog output (AIO) that is converted from digital value.
58-
- `"pwm"` for PWM analog output.
59-
- `"uart-rx"` for serial receive pin.
60-
- `"uart-tx"` for serial transmit pin.
61-
- `"i2c-scl"` for I2C clock.
62-
- `"i2c-sda"` for I2C data.
63-
- `"spi-sclk"` for SPI clock.
64-
- `"spi-ss"` for SPI Slave Select.
65-
- `"spi-mosi"` for SPI Master Out Slave In.
66-
- `"spi-miso"` for SPI Master In Slave Out.
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.
6750

6851
<a name="board"></a>
6952
### The `Board` interface

‎api/board/aio.md

Lines changed: 41 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -7,83 +7,72 @@ On some boards access to AIO may be asynchronous. This API uses synchronous read
77

88
The API object
99
--------------
10-
AIO functionality is exposed by the [`AIO`](#aio) object that can be obtained by using the [aio() method of the `Board` API](./README.md/#aio). See also the [Web IDL](./webidl.md).
10+
AIO functionality is exposed by the [`AIO`](#aio) 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).
1111

12-
Implementations MAY also support an explicit constructor that runs the [`AIO initialization`](#init) algorithm.
13-
14-
### Examples
15-
```javascript
16-
var board = require("board");
17-
18-
// Configure AIO using the board
19-
board.aio("A1").then(function(aio){
20-
// Read pin values.
21-
console.log(board.name + " AIO pin 1 value: " + aio.read());
22-
23-
// Release the pin.
24-
aio.close();
25-
});
26-
27-
board.aio({pin: "A4", precision: 12 })
28-
.then(function(aio){ // read 10 samples, one every second
29-
setTimeout(function() {
30-
aio.close();
31-
}, 10500);
32-
setInterval(function() {
33-
console.log("AIO pin 4 value: " + aio.read());
34-
}, 1000);
35-
}).catch(function(err) {
36-
console.log("AIO error.");
37-
});
38-
```
39-
40-
<a name="aio">
12+
<a name="aio"></a>
4113
### The `AIO` interface
42-
Represents the properties and methods that expose AIO functionality. The `AIO` object implements the [`EventEmitter`](../README.md/#events) interface, and extends the [`Pin`](./README.md/#pin) object, so it has all properties of [`Pin`](./README.md/#pin). In addition, it has the following properties:
14+
Represents the properties and methods that expose AIO functionality. The `AIO` object implements the [`EventEmitter`](../README.md/#events) interface, and extends the [`Pin`](./README.md/#pin) object. It has the following properties and methods:
4315

4416
| Property | Type | Optional | Default value | Represents |
4517
| --- | --- | --- | --- | --- |
4618
| `pin` | String or Number | no | `undefined` | board name for the pin |
47-
| `mode` | String | no | `undefined` | I/O mode |
48-
| `channel` | unsigned long | yes | `undefined` | numeric index of the analog pin |
4919
| `precision` | unsigned long | yes | `undefined` | bit length of digital sample |
5020

5121
| Method signature | Description |
5222
| --- | --- |
5323
| [`read()`](#read) | synchronous read |
5424
| [`close()`](#close) | close the pin |
5525

56-
#### `AIO` properties
57-
The `pin` property inherited from [`Pin`](./README.md/#pin) can take values defined by the board mapping, usually strings prefixed by `"A"`.
58-
59-
The `mode` property inherited from [`Pin`](./README.md/#pin) takes the value `"analog-input"`.
60-
61-
The `channel` property is initialized by implementation and provides the numeric index of the analog pin, e.g. it is 0 for pin `"A0"` and 5 for pin `"A5"`.
26+
The `pin` property inherited from [`Pin`](./README.md/#pin) can take values defined by the board documentation, usually strings prefixed by `"A"`, but it can also be specified as the numeric index of the analog pin, where pin 0 corresponding to the first analog pin and so forth.
6227

6328
The `precision` property represents the bit length of the digital sample. It is usually 10 or 12 bits, depending on board.
6429

65-
#### `AIO` methods
66-
<a name="init">
67-
##### AIO initialization
30+
<a name="init"></a>
31+
#### AIO initialization
6832
This internal algorithm is used by the [`Board.aio()`](./README.md/#aio) method. Configures the AIO pin provided by the `options` argument. It involves the following steps:
6933
- If `options` is a string, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
70-
- Otherwise if `options` is a dictionary, let `init` be `options`. It may contain the following [`AIO`](#aio) properties:
71-
* `pin` for board pin name with the valid values defined by the board
34+
- Otherwise if `options` is a number, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
35+
- 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:
36+
* `pin` for board pin name with the valid values defined by the board, or for the numeric index of the analog pin;
7237
* `precision` for the bit width of a sample (if the board supports setting the sampling rate).
73-
- If any of the `init` properties has an invalid value on the given board, as defined by the board documentation, throw `InvalidAccessError`.
74-
- Request the underlying platform to initialize AIO on the given board for the given pin `init.pin`.
38+
- If any property of `init` is specified and has an invalid value on the given board, as defined by the board documentation, throw `TypeError`.
39+
- Request the underlying platform to initialize AIO on `init.pin` (if defined) or otherwise `init.channel`.
7540
- In case of failure, throw `InvalidAccessError`.
7641
- Let `aio` be the `AIO`](#aio) object that represents the hardware pin identified by `init.pin`, as defined by the board documentation.
77-
- Initialize the `aio.channel` property with the numeric index of the analog pin, as defined by the board documentation.
78-
- Initialize the `aio.mode` property with `"analog-input"`.
7942
- 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`.
8043
- Initialize the `aio.value` property with `undefined`.
8144
- Return the `aio` object.
8245

83-
<a name="read">
84-
##### The `unsigned long read()` method
46+
<a name="read"></a>
47+
#### The `unsigned long read()` method
8548
Performs a synchronous read operation for the pin value. It returns the pin value representing the last sampling.
8649

87-
<a name="close">
88-
##### The `close()` method
50+
<a name="close"></a>
51+
#### The `close()` method
8952
Called when the application is no longer interested in the pin. Until the next [initialization](#init), invoking the `read()` method SHOULD throw `InvalidAccessError`.
53+
54+
### Examples
55+
```javascript
56+
var board = require("board");
57+
58+
// Configure AIO using the board
59+
board.aio("A1").then(function(aio){
60+
// Read pin values.
61+
console.log(board.name + " AIO pin 1 value: " + aio.read());
62+
63+
// Release the pin.
64+
aio.close();
65+
});
66+
67+
board.aio({pin: "A4", precision: 12 })
68+
.then(function(aio){ // read 10 samples, one every second
69+
setTimeout(function() {
70+
aio.close();
71+
}, 10500);
72+
setInterval(function() {
73+
console.log("AIO pin 4 value: " + aio.read());
74+
}, 1000);
75+
}).catch(function(err) {
76+
console.log("AIO error.");
77+
});
78+
```

‎api/board/arduino101.md

Lines changed: 28 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
Board Support for Arduino 101
22
=============================
33

4-
This page defines the values returned by the [`Board.pins()`](./README.md/#getpins) method and describes the pin mapping for the [`Board.pin()`](./README.md/#getpin) method, from board labels that are printed on the board to operating system-specific values.
4+
This document defines the pin values that are accepted by implementations.
55

6-
The board labels are described in the [Arduino 101](https://www.arduino.cc/en/Main/ArduinoBoard101) board documentation. Also, for each board pin, the [`supportedModes`](./README.md/#pin) property of each pin is described.
6+
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

88
The [Arduino 101](https://www.arduino.cc/en/Main/ArduinoBoard101) board has 20 I/O pins that operate at 3.3V and can be configured as described by the following table.
99

1010
Pins 0 and 1 can be also configured to be used as UART. The port name is exposed as `uart0`.
1111

1212
On GPIO pins (0..13) interrupts can be configured to be triggered on low value, high value, rising edge and falling edge. Some of the GPIO pins can trigger interrupt on value *change* (pins 2, 5, 7, 8, 10, 11, 12, 13).
1313

14-
Pins 3, 5, 6 and 9 can be used for PWM output. These pins are marked on the board by a ~ (tilde) symbol next to the pin numbers. Pin 3 corresponds to PWM channel 0, pin 9 to PWM channel 3, etc.
14+
Pins 3, 5, 6 and 9 can be used for PWM output. These pins are marked on the board by a ~ (tilde) symbol next to the pin numbers. Pin 3 corresponds to PWM channel 0, pin 5 to PWM channel 1, pin 6 to PWM channed 2, and pin 9 to PWM channel 3.
1515

1616
Pins A0 to A5 can be used for analog input and each provide 10 bits of resolution (i.e. 1024 different values).
1717

@@ -29,29 +29,28 @@ Other names:
2929

3030
Arduino 101 pins are summarized in the following table (channel means the index of the same I/O type):
3131

32-
|Pin name |Supported modes (channel) |
33-
| --- | --- |
34-
| `0` | `"input"`, `"output"`, `"uart-rx"` (0) |
35-
| `1` | `"input"`, `"output"`, `"uart-tx"` (0) |
36-
| `2` | `"input"`, `"output"` |
37-
| `3` | `"input"`, `"output"`, `"pwm"`(0) |
38-
| `4` | `"input"`, `"output"` |
39-
| `5` | `"input"`, `"output"`, `"pwm"`(1) |
40-
| `6` | `"input"`, `"output"`, `"pwm"`(2) |
41-
| `7` | `"input"`, `"output"` |
42-
| `8` | `"input"`, `"output"` |
43-
| `9` | `"input"`, `"output"`, `"pwm"`(3) |
44-
| `10` | `"input"`, `"output"`, `"spi_ss"` |
45-
| `11` | `"input"`, `"output"`, `"spi-mosi"` |
46-
| `12` | `"input"`, `"output"`, `"spi-miso"` |
47-
| `13` | `"input"`, `"output"`, `"spi-sclk"` |
48-
| `"A0"` | `"analog-in"`(0) |
49-
| `"A1"` | `"analog-in"`(1) |
50-
| `"A2"` | `"analog-in"`(2) |
51-
| `"A3"` | `"analog-in"`(3) |
52-
| `"A4"` | `"analog-in"`(4) |
53-
| `"A5"` | `"analog-in"`(5) |
54-
| `"LED0"`| `"output"` [active on 1] |
55-
| `"LED1"`| `"output"` [active on 0] |
56-
| `"LED2"`| `"output"` [active on 0] |
57-
32+
|Pin value |Supported modes (channel) |
33+
| --- | --- |
34+
| `0` | GPIO_IN, GPIO_OUT, UART_RX(0) |
35+
| `1` | GPIO_IN, GPIO_OUT, UART_TX(0) |
36+
| `2` | GPIO_IN, GPIO_OUT |
37+
| `3` | GPIO_IN, GPIO_OUT, PWM(0) |
38+
| `4` | GPIO_IN, GPIO_OUT |
39+
| `5` | GPIO_IN, GPIO_OUT, PWM(1) |
40+
| `6` | GPIO_IN, GPIO_OUT, PWM(2) |
41+
| `7` | GPIO_IN, GPIO_OUT |
42+
| `8` | GPIO_IN, GPIO_OUT |
43+
| `9` | GPIO_IN, GPIO_OUT, PWM(3) |
44+
| `10` | GPIO_IN, GPIO_OUT, SPI_SS(0) |
45+
| `11` | GPIO_IN, GPIO_OUT, SPI_MOSI(0) |
46+
| `12` | GPIO_IN, GPIO_OUT, SPI_MISO(0) |
47+
| `13` | GPIO_IN, GPIO_OUT, SPI_SCLK(0) |
48+
| `"A0"` | ANALOG_IN(0) |
49+
| `"A1"` | ANALOG_IN(1) |
50+
| `"A2"` | ANALOG_IN(2) |
51+
| `"A3"` | ANALOG_IN(3) |
52+
| `"A4"` | ANALOG_IN(4) |
53+
| `"A5"` | ANALOG_IN(5) |
54+
| `"LED0"` | active on 1 |
55+
| `"LED1"` | active on 0 |
56+
| `"LED2"` | active on 0 |

‎api/board/frdm_k64f.md

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -3,43 +3,43 @@ Board Support for FRDM-K64F
33

44
The FRDM-K64F board pin names and locations are shown [here](https://developer.mbed.org/platforms/FRDM-K64F/).
55

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

8-
There is an onboard RGB LED which can be controlled through three different GPIO outputs for the red, green, and blue components. `LEDR` controls the red portion, `LEDG` the green portion, and `LEDB` the blue
8+
There is an onboard RGB LED which can be controlled through three different GPIO_OUTs for the red, green, and blue components. `LEDR` controls the red portion, `LEDG` the green portion, and `LEDB` the blue
99
portion. They are all active on high.
1010

11-
There are three onboard switches labeled `SW2`, `SW3`, and `RESET`. The `SW2` switch can be used as a GPIO input. The `RESET` switch can be used as an output.
11+
There are three onboard switches labeled `SW2`, `SW3`, and `RESET`. The `SW2` switch can be used as a GPIO_IN. The `RESET` switch can be used as an output.
1212

1313
There are ten pins that can be used as PWM output, `PWM0` - `PWM9`.
1414

1515
There are six analog input pins, `A0` - `A5`.
1616

1717
Supported pins are summarized in the following table:
1818

19-
|Pin name |Supported modes (channel), [other] |
20-
| --- | --- |
21-
| `D0` | `"input"`, `"output"`, "uart-rx" (3)|
22-
| `D1` | `"input"`, `"output"`, "uart-tx" (3)|
23-
| `D2` | `"input"`, `"output"` |
24-
| `D3` | `"input"`, `"output"`, `"pwm"`(0) |
25-
| `D4` | `"input"`, `"output"` |
26-
| `D5` | `"input"`, `"output"`, `"pwm"`(1) |
27-
| `D6` | `"input"`, `"output"`, `"pwm"`(2) |
28-
| `D7` | `"input"`, `"output"`, `"pwm"`(3) |
29-
| `D8` | `"input"`, `"output"`, `"pwm"`(4) |
30-
| `D9` | `"input"`, `"output"`, `"pwm"`(5) |
31-
| `D10` | `"input"`, `"output"`, `"pwm"`(6) |
32-
| `D11` | `"input"`, `"output"`, `"pwm"`(7), `"spi-mosi"` |
33-
| `D12` | `"input"`, `"output"`, `"pwm"`(8), `"spi-miso"` |
34-
| `D13` | `"input"`, `"output"`, `"pwm"`(9), `"spi-sclk"` |
35-
| `D14` | `"input"`, "i2c-sda" |
36-
| `D15` | `"input"`, "i2c-scl" |
37-
| `"A0"` | `"analog-in"`(0) |
38-
| `"A1"` | `"analog-in"`(1) |
39-
| `"A2"` | `"analog-in"`(2) |
40-
| `"A3"` | `"analog-in"`(3) |
41-
| `"A4"` | `"analog-in"`(4), `"pwm"` |
42-
| `"A5"` | `"analog-in"`(5), `"pwm"` |
43-
| `"LED0"`| `"output"` (active on 1) |
44-
| `"LED1"`| `"output"` (active on 0) |
45-
| `"LED2"`| `"output"` (active on 0) |
19+
|Pin name |Supported modes (channel) |
20+
| --- | --- |
21+
| `D0` | GPIO_IN, GPIO_OUT, UART_RX(3) |
22+
| `D1` | GPIO_IN, GPIO_OUT, UART_TX(3) |
23+
| `D2` | GPIO_IN, GPIO_OUT |
24+
| `D3` | GPIO_IN, GPIO_OUT, PWM(0) |
25+
| `D4` | GPIO_IN, GPIO_OUT |
26+
| `D5` | GPIO_IN, GPIO_OUT, PWM(1) |
27+
| `D6` | GPIO_IN, GPIO_OUT, PWM(2) |
28+
| `D7` | GPIO_IN, GPIO_OUT, PWM(3) |
29+
| `D8` | GPIO_IN, GPIO_OUT, PWM(4) |
30+
| `D9` | GPIO_IN, GPIO_OUT, PWM(5) |
31+
| `D10` | GPIO_IN, GPIO_OUT, PWM(6) |
32+
| `D11` | GPIO_IN, GPIO_OUT, PWM(7), SPI_MOSI(0) |
33+
| `D12` | GPIO_IN, GPIO_OUT, PWM(8), SPI_MISO(0) |
34+
| `D13` | GPIO_IN, GPIO_OUT, PWM(9), SPI_SCLK(0) |
35+
| `D14` | GPIO_IN, I2C_SDA(0) |
36+
| `D15` | GPIO_IN, I2C_SCL(0) |
37+
| `"A0"` | ANALOG_IN(0) |
38+
| `"A1"` | ANALOG_IN(1) |
39+
| `"A2"` | ANALOG_IN(2) |
40+
| `"A3"` | ANALOG_IN(3) |
41+
| `"A4"` | ANALOG_IN(4), PWM |
42+
| `"A5"` | ANALOG_IN(5), PWM |
43+
| `"LED0"`| active on 1 |
44+
| `"LED1"`| active on 0 |
45+
| `"LED2"`| active on 0 |

0 commit comments

Comments
 (0)