Board: change default pin namespace to board

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

Author: zolkis

board/README.md

@@ -9,9 +9,11 @@ The [Board](#board) API provides low level interfaces for I/O operations:
   - [SPI - Serial Peripheral Interface](./spi.md)
   - [UART - Universal Asynchronous Receiver/Transmitter](./uart.md).
 
-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.
+Hardware pin names are usually marked on the circuit boards, that defines a board namespace for pins. However, operating systems, such as Linux, or [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 (system) defined namespaces. Pin names are opaque to the application, either strings or numbers that gain meaning in either the board or OS namespace. Also, the API exposes board name, OS name (including OS version) and API version for all board APIs.
 
-The supported board namespaces are listed in [this directory](./):
+Since it is generally easier for developers to just look at a given board and use the names printed there in the API, by default the board namespace is used, but developers can specify to use the system namespace as well. If a given pin value is not found in the default (or provided) namespace, an error is thrown: there is no fallback search in the other namespace.
+
+Examples for the supported board namespaces are listed in [this directory](./):
 - [arduino101.md](./arduino101.md)
 - [frdm_k64f.md](./frdm_k64f.md).
 

board/aio.md

@@ -25,7 +25,7 @@ Configures an AIO pin using data provided by the `options` argument. It involves
 - Otherwise if `options` is a number, create a dictionary 'init' and let `init.pin` be `options`.
 - 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;
-  * `mapping` to specify if OS or board namespace is to be used with the pin (by default `"system"`).
+  * `mapping` to specify if OS or board namespace is to be used with the pin (by default `"board"`).
   * `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,  throw `TypeError`.
 - Request the underlying platform to initialize AIO on the pin identified by `init.pin` in the namespace specified by `init.mapping` if that is defined. If not found, throw `InvalidAccessError`. If `init.mapping is not defined, then search `init.pin` first in the OS namespace, then in board namespace. In case of failure, throw `InvalidAccessError`.
@@ -40,7 +40,7 @@ Configures an AIO pin using data provided by the `options` argument. It involves
 | Property   | Type   | Optional | Default value | Represents |
 | ---        | ---    | ---      | ---           | ---        |
 | `pin`      | String or Number | no | `undefined`  | pin name |
-| `mapping`   | enum | no | `"system"`  | pin mapping, `"system"` or `"board"` |
+| `mapping`   | enum | no | `"board"`  | pin mapping, `"system"` or `"board"` |
 | `precision` | unsigned long | yes | `undefined` | bit length of digital sample |
 
 | Method              | Description      |
@@ -65,12 +65,12 @@ Called when the application is no longer interested in the pin. Until the next [
 try {
   var aio = require("aio");  // initialize AIO on the board
 
-  var a1 = aio.open(1);  // pin 1 in OS namespace
+  var a1 = aio.open("A1");  // pin 1 in board namespace
   console.log(board.name + " AIO pin 1 value: " + a1.read());
   a1.close();
 
-  // Open pin A4 in board namespace, i.e. the value printed on the board
-  var a4 = aio.open({pin: "A4", mapping: "board", precision: 12 });
+  // Open pin A4 in system namespace
+  var a4 = aio.open({pin: "ADC4", mapping: "system", precision: 12 });
 
   setTimeout(function() {
     a4.close();

board/gpio.md

@@ -27,15 +27,15 @@ The following dictionary is used for initializing GPIO pins and ports.
 | Property   | Type   | Optional | Default value | Represents |
 | ---        | ---    | ---      | ---           | ---        |
 | `pin `     | String or Number | no | `undefined`   | pin name |
-| `mapping`  | String | no | `"system"`   | pin mapping |
+| `mapping`  | String | no | `"board"`   | pin mapping |
 | `mode`     | String | no       | `undefined`   | I/O mode |
 | `activeLow` | boolean | yes   | `false` | whether the pin is active on logical low |
 | `edge`     | string | yes      | `"any"`       | Interrupt generation mode |
 | `state`    | string | yes      | `undefined`      | "pulldown", "pullup" |
 
 The `pin` property is either a number or string, with values defined by the OS or board documentation. The default value is `undefined`.
 
-The `mapping` property represents the pin namespace, either `"system"` or `"board"`, by default `"system"`.
+The `mapping` property represents the pin namespace, either `"system"` or `"board"`, by default `"board"`.
 
 The `mode` property MUST take the value `"in"` or `"out"`. The default value is `"out"`.
 

board/pwm.md

@@ -27,7 +27,7 @@ Configures a PWM pin using data provided by the `options` argument. It runs the
 - If `options` is a string or 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 [`PWM`](#pwm) properties, but at least `name`
   * `pin` for pin name
-  * `mapping` for pin mapping, either `"system"` or `"board"`, by default `"system"`
+  * `mapping` for pin mapping, either `"system"` or `"board"`, by default `"board"`
   * `reversePolarity`, by default `false`.
 - If any of the `init` properties is specified, but has invalid value on the board, throw `InvalidAccessError`.
 - Let `mapping` be `init.mapping`.
@@ -43,7 +43,7 @@ Represents the properties and methods that expose PWM functionality.
 | Property   | Type   | Optional | Default value | Represents |
 | ---        | ---    | ---      | ---           | ---        |
 | `pin`      | String or Number | no | `undefined`   | pin name |
-| `mapping`  | String | no | `"system"`   | pin mapping |
+| `mapping`  | String | no | `"board"`   | pin mapping |
 | `reversePolarity` | boolean | yes |   `false`   | PWM polarity |
 | `write()`  | function | no | defined by implementation | set and enable PWM signal |
 | `stop()`   | function | no | defined by implementation | stop the PWM signal |

board/webidl.md

@@ -24,7 +24,7 @@ interface AIOObject {
 
 dictionary AIOOptions {
   PinName pin;
-  PinMapping mapping = "system";
+  PinMapping mapping = "board";
   unsigned long precision = 10;
 };
 
@@ -56,7 +56,7 @@ GPIO implements EventEmitter;
 
 dictionary GPIOOptions {
   PinName pin;
-  PinMapping mapping = "system";
+  PinMapping mapping = "board";
   GPIOMode mode = "out";
   boolean activeLow = false;
   GPIOEdge edge = "none";
@@ -74,7 +74,7 @@ interface PWMObject {
 
 dictionary PWMOptions {
   PinName pin;
-  PinMapping mapping = "system";
+  PinMapping mapping = "board";
   boolean reversePolarity = false;
   double period;
   double pulseWidth;