Board: make API synchronous

Signed-off-by: Zoltan Kis <[email protected]>

Author: zolkis

board/README.md

@@ -57,7 +57,7 @@ Represents a hardware board.
 | [`name`](#name)   | String | no       | `undefined`   | board name |
 | [`version`](#version) | String | no   | `versions.board` in [`package.json`](../package.json) | API version |
 
-| Method signature  | Description            |
+| Method            | Description            |
 | ---               | ---                    |
 | [`aio()`](#aio)   | request an AIO object  |
 | [`gpio()`](#gpio) | request a GPIO object  |
@@ -85,57 +85,43 @@ Board errors are represented as augmented [`Error`](https://nodejs.org/api/error
 #### `Board` methods
 
 <a name="aio"></a>
-##### The `aio(options)` method
-Configures an AIO pin. The method runs the following steps:
-- Return a [`Promise`](../README.md/#promise) object `promise` and continue [in parallel](https://html.spec.whatwg.org/#in-parallel).
-- If the AIO functionality is not supported, reject `promise` with `"NotSupportedError"`.
-- Run the internal [`AIO initialization`](./aio.md/#init) algorithm with `options` as argument and let `aio` be the returned result.
-- If it throws an error, reject promise with that error.
-- Resolve `promise` with the `aio` object.
+##### The `aio()` method
+Provides the AIO API object. The method runs the following steps:
+- If the AIO functionality is not supported on the board, throw `"NotSupportedError"`.
+- Initialize AIO functionality on the board. If it fails, throw `"SystemError"`.
+- Let `aio` be the [AIO API object](./aio.md/#apiobject). Return `aio`.
 
 <a name="gpio"></a>
-##### The `gpio(options)` method
-Configures a GPIO pin or GPIO port. The method runs the following steps:
-- Return a [`Promise`](../README.md/#promise) object `promise` and continue [in parallel](https://html.spec.whatwg.org/#in-parallel).
-- If the GPIO functionality is not supported, reject `promise` with `"NotSupportedError"`.
-- Run the internal [`GPIO initialization`](./gpio.md/#init) algorithm with `options` as argument and let `gpio` be the returned result.
-- If it throws an error, reject promise with that error.
-- Resolve `promise` with the `gpio` object.
+##### The `gpio()` method
+Provides the GPIO API object. The method runs the following steps:
+- If the GPIO functionality is not supported on the board, throw `"NotSupportedError"`.
+- Initialize GPIO functionality on the board. If it fails, throw `"SystemError"`.
+- Let `gpio` be the [GPIO API object](./gpio.md/#apiobject). Return `gpio`.
 
 <a name="pwm"></a>
-##### The `pwm(options)` method
-Configures a PWM pin. The method runs the following steps:
-- Return a [`Promise`](../README.md/#promise) object `promise` and continue [in parallel](https://html.spec.whatwg.org/#in-parallel).
-- If the PWM functionality is not supported, reject `promise` with `"NotSupportedError"`.
-- Run the internal [`PWM initialization`](./pwm.md/#init) algorithm with `options` as argument and let `pwm` be the returned result.
-- If it throws an error, reject promise with that error.
-- Resolve `promise` with the `pwm` object.
+##### The `pwm()` method
+Provides the PWM API object. The method runs the following steps:
+- If the PWM functionality is not supported on the board, throw `"NotSupportedError"`.
+- Initialize PWM functionality on the board. If it fails, throw `"SystemError"`.
+- Let `pwm` be the [PWM API object`](./pwm.md/#apiobject). Return `pwm`.
 
 <a name="i2c"></a>
-##### The `i2c(options)` method
-Configures I2C communication. The method runs the following steps:
-- Return a [`Promise`](../README.md/#promise) object `promise` and continue [in parallel](https://html.spec.whatwg.org/#in-parallel).
-- If the I2C functionality is not supported, reject `promise` with `"NotSupportedError"`.
-- Run the internal [`I2C initialization`](./i2c.md/#init) algorithm with `options` as argument and let `i2c` be the returned result.
-- If it throws an error, reject promise with that error.
-- Resolve `promise` with the `i2c` object.
+##### The `i2c()` method
+Provides the I2C API object. The method runs the following steps:
+- If the I2C functionality is not supported on the board, throw `"NotSupportedError"`.
+- Initialize I2C functionality on the board. If it fails, throw `"SystemError"`.
+- Let `i2c` be the [I2C API Object](./i2c.md/#apiobject). Return `pwm`.
 
 <a name="spi"></a>
-##### The `spi(options)` method
-Configures SPI communication.
-The method runs the following steps:
-- Return a [`Promise`](../README.md/#promise) object `promise` and continue [in parallel](https://html.spec.whatwg.org/#in-parallel).
-- If the SPI functionality is not supported, reject `promise` with `"NotSupportedError"`.
-- Run the [`SPI init`](./spi.md/#init) steps with `options` as argument and let `spi` be the returned result.
-- If it throws an error, reject promise with that error.
-- Resolve `promise` with the `spi` object.
+##### The `spi()` method
+Provides the SPI API object. The method runs the following steps:
+- If the SPI functionality is not supported on the board, throw `"NotSupportedError"`.
+- Initialize SPI functionality on the board. If it fails, throw `"SystemError"`.
+- Let `spi` be the [SPI API object](./spi.md/#apiobject). Return `spi`.
 
 <a name="uart"></a>
-##### The `uart(options)` method
-Configures UART communication. It takes a dictionary object as argument.
-The method runs the following steps:
-- Return a [`Promise`](../README.md/#promise) object `promise` and continue [in parallel](https://html.spec.whatwg.org/#in-parallel).
-- If the UART functionality is not supported, reject `promise` with `"NotSupportedError"`.
-- Run the [`UART init`](./uart.md/#init) steps with `options` as argument and let `uart` be the returned result.
-- If it throws an error, reject promise with that error.
-- Resolve `promise` with the `uart` object.
+##### The `uart()` method
+Provides the UART API object. The method runs the following steps:
+- If the UART functionality is not supported on the board, throw `"NotSupportedError"`.
+- Initialize UART functionality on the board. If it fails, throw `"SystemError"`.
+- Let `uart` be the [UART API object](./uart.md/#apiobject) object. Return `uart`.

board/aio.md

@@ -3,22 +3,42 @@ AIO API
 
 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.
 
-On some boards access to AIO may be asynchronous. This API uses synchronous read.
+On some boards access to AIO may be asynchronous. This API uses synchronous methods.
 
-The API object
---------------
-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).
+<a name="apiobject"></a>
+### The AIO API object
+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:
+
+| Method              | Description      |
+| ---                 | ---              |
+| [`open()`](#open)   | synchronous open |
+
+<a name="open"></a>
+#### The `AIO open(options)` method
+Configures an AIO pin using data provided by the `options` argument. It involves the following steps:
+- If `options` is a string, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
+- Otherwise if `options` is a number, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
+- 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:
+  * `pin` for board pin name with the valid values defined by the board, or for the numeric index of the analog pin;
+  * `precision` for the bit width of a sample (if the board supports setting the sampling rate).
+- If any property of `init` is specified and has an invalid value on the given board, as defined by the board documentation,  throw `TypeError`.
+- Request the underlying platform to initialize AIO on `init.pin` (if defined) or otherwise `init.channel`.
+- In case of failure, throw `InvalidAccessError`.
+- Let `aio` be the `AIOPin`](#aiopin) object that represents the hardware pin identified by `init.pin`, as defined by the board documentation.
+- 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`.
+- Initialize the `aio.value` property with `undefined`.
+- Return the `aio` object.
 
 <a name="aio"></a>
 ### The `AIO` interface
-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:
+The `AIO` object extends the [`Pin`](./README.md/#pin) object.
 
 | Property   | Type   | Optional | Default value | Represents |
 | ---        | ---    | ---      | ---           | ---        |
 | `pin`      | String or Number | no | `undefined`   | board name for the pin |
 | `precision` | unsigned long | yes | `undefined` | bit length of digital sample |
 
-| Method signature    | Description      |
+| Method              | Description      |
 | ---                 | ---              |
 | [`read()`](#read)   | synchronous read |
 | [`close()`](#close) | close the pin    |
@@ -27,52 +47,33 @@ The `pin` property inherited from [`Pin`](./README.md/#pin) can take values defi
 
 The `precision` property represents the bit length of the digital sample. It is usually 10 or 12 bits, depending on board.
 
-<a name="init"></a>
-#### AIO initialization
-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:
-- If `options` is a string, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
-- Otherwise if `options` is a number, create a dictionary 'init' and use the value of `options` to initialize the `init.pin` property.
-- 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:
-  * `pin` for board pin name with the valid values defined by the board, or for the numeric index of the analog pin;
-  * `precision` for the bit width of a sample (if the board supports setting the sampling rate).
-- If any property of `init` is specified and has an invalid value on the given board, as defined by the board documentation,  throw `TypeError`.
-- Request the underlying platform to initialize AIO on `init.pin` (if defined) or otherwise `init.channel`.
-- In case of failure, throw `InvalidAccessError`.
-- Let `aio` be the `AIO`](#aio) object that represents the hardware pin identified by `init.pin`, as defined by the board documentation.
-- 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`.
-- Initialize the `aio.value` property with `undefined`.
-- Return the `aio` object.
-
 <a name="read"></a>
 #### The `unsigned long read()` method
 Performs a synchronous read operation for the pin value. It returns the pin value representing the last sampling.
 
 <a name="close"></a>
 #### The `close()` method
-Called when the application is no longer interested in the pin. Until the next [initialization](#init), invoking the `read()` method SHOULD throw `InvalidAccessError`.
+Called when the application is no longer interested in the pin. Until the next [open()](#open) is called, invoking the `read()` method throws `InvalidAccessError`.
 
 ### Examples
 ```javascript
-var board = require("board");
+try {
+  var aio = require("board").aio();  // initialize AIO on the board
 
-// Configure AIO using the board
-board.aio("A1").then(function(aio){
-  // Read pin values.
-  console.log(board.name + " AIO pin 1 value: " + aio.read());
+  var a1 = aio.open("A1");
+  console.log(board.name + " AIO pin 1 value: " + a1.read());
+  a1.close();
 
-  // Release the pin.
-  aio.close();
-});
+  var a4 = aio.open({pin: "A4", precision: 12 });
 
-board.aio({pin: "A4", precision: 12 })
-.then(function(aio){  // read 10 samples, one every second
   setTimeout(function() {
-    aio.close();
+    a4.close();
   }, 10500);
+
   setInterval(function() {
-    console.log("AIO pin 4 value: " + aio.read());
+    console.log("AIO pin 4 value: " + a4.read());
   }, 1000);
-}).catch(function(err) {
-  console.log("AIO error.");
-});
+} catch (err) {
+  console.log("AIO error: " + err.message);
+};
 ```