aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authort-harvey <t-harvey@ti.com>2018-07-13 10:20:24 -0500
committerGeoff Gustafson <geoff@linux.intel.com>2018-07-13 08:20:24 -0700
commit6d21e1710076b3b67759aaa7d88ecbd84e8ac68a (patch)
treeb38ac32bdd5a7c32dede940349df93406985cf6f
parent3a701fbe2f17982ea696d86a83e7ba775e9587d7 (diff)
[docs] Update WebIDL and modify docs to fit new "node.js-like" style, Part 2 (#1893)
Reinserted WebIDL for buffer.md; changed the WebIDL in aio and ble to be syntactically correct and to follow the new style of buffer.md. Added a new file that explains some of the differences between WebIDL and Javascript. Signed-off-by: Timothy Harvey <t-harvey@ti.com>
-rw-r--r--docs/Notes_on_WebIDL.md40
-rw-r--r--docs/aio.md95
-rw-r--r--docs/ble.md234
-rw-r--r--docs/board.md34
-rw-r--r--docs/buffer.md64
-rw-r--r--docs/console.md82
-rw-r--r--docs/dgram.md104
-rw-r--r--docs/events.md132
-rw-r--r--docs/fs.md217
-rw-r--r--docs/gfx.md161
-rw-r--r--docs/gpio.md124
-rw-r--r--docs/grove_lcd.md163
-rw-r--r--docs/i2c.md75
-rw-r--r--docs/mathstubs.md28
-rw-r--r--docs/net-config.md60
-rw-r--r--docs/net.md225
-rw-r--r--docs/ocf.md282
-rw-r--r--docs/performance.md53
-rw-r--r--docs/pme.md231
-rw-r--r--docs/pwm.md100
-rw-r--r--docs/sensors.md99
-rw-r--r--docs/spi.md114
-rw-r--r--docs/timers.md113
-rw-r--r--docs/uart.md82
-rw-r--r--docs/web-socket.md98
25 files changed, 1537 insertions, 1473 deletions
diff --git a/docs/Notes_on_WebIDL.md b/docs/Notes_on_WebIDL.md
new file mode 100644
index 0000000..bd51703
--- /dev/null
+++ b/docs/Notes_on_WebIDL.md
@@ -0,0 +1,40 @@
+Notes on WebIDL for zephyr.js documentation:
+
+The WebIDL fragments are for reference only; the description of the
+API should be considered correct -- please report discrepancies as
+soon as possible.
+
+Although both WebIDL and JavaScript are aimed at web applications,
+numerous incompatibilities exist between the two. In general, we try
+to use basic (as opposed to "advanced") WebIDL to describe each
+API; below, we list some of our conventions.
+
+We map WebIDL definitions to JavaScript objects as follows:
+
+1. dictionaries -- these map to JavaScript objects that simply don't
+ have methods attached to them.
+2. interfaces -- like definitions, these correspond to JavaScript
+ objects, except that they may also include methods.
+3. callbacks -- these are type definitions for functions used as
+ parameters or object fields.
+4. enumerations -- these are largely the same in both languages.
+
+Unless a constructor is explicitly defined/denied (*e.g.*, see the
+note about "require", below), we assume the JavaScript model that the
+object can be constructed with "new" -- WebIDL specifies that the
+external attribute "constructor" be applied to a definition that can
+be new'd, but putting the attribute on every object would be
+cumbersome.
+
+The node.js notion of "require" is subtly different from constructing
+an object with JavaScript's "new", but it has appealing semantics. We
+annotate WebIDL definitions that should be implemented with node.js's
+"require" semantics with the external attribute "ReturnFromRequire".
+
+Similarly, many people's general model is one of separate compilation,
+which WebIDL does not support. WebIDL's model is to assume that all
+of the required files will be concatenated together and then compiled
+-- thus, one file can reference types that are found in another file,
+and there is no annotation to alert the reader that the definition of
+some type is to be found elsewhere. We use WebIDL attributes to
+specify and call attention to types that are defined in other files.
diff --git a/docs/aio.md b/docs/aio.md
index 8fd8c99..bdd1d15 100644
--- a/docs/aio.md
+++ b/docs/aio.md
@@ -3,7 +3,13 @@ ZJS API for Analog I/O (AIO)
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: AIO](#aio-api)
+ * [aio.open(AIOInit)](#aioopenaioinit)
+* [Class: AIOPin](#aiopin-api)
+ * [pin.read()](#pinread)
+ * [pin.readAsync(ReadCallback)](#pinreadasyncreadcallback)
+ * [pin.on(eventType, ReadCallback)](#pinoneventtype-readcallback)
+ * [pin.close()](#pinclose)
* [Sample Apps](#sample-apps)
Introduction
@@ -23,84 +29,77 @@ not have support for this.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-```javascript
-// require returns an AIO object
-// var aio = require('aio');
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-[NoInterfaceObject]
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>
+// require returns an AIO object
+// var aio = require('aio');<p>[ReturnFromRequire]
interface AIO {
AIOPin open(AIOInit init);
-};
-
-dictionary AIOInit {
- unsigned long pin;
-};
-
-[NoInterfaceObject]
-interface AIOPin {
+};<p>dictionary AIOInit {
+ (unsigned long or string) pin;
+};<p>interface AIOPin {
unsigned long read();
void readAsync(ReadCallback callback); // TODO: change to return a promise
void on(string eventType, ReadCallback callback);
void close();
-};
+};<p>callback ReadCallback = void (unsigned long value);
+</pre> </details>
-callback ReadCallback = void (unsigned long value);
-```
-
-API Documentation
------------------
-### AIO.open
-
-`AIOPin open(AIOInit init);`
+AIO API
+-------
+### aio.open(init)
+* 'init' *AIOInit object* The AIOInit object has a single field called "pin"
+ that represents the name of the pin (either an integer or a string,
+ depending on the board).
+* Returns: an AIOPin object that may be used to read values from the pin.
-The `init` object lets you set the pin number. You can either use a raw
+When setting the pin number, you can either use a raw
number for your device or use the board support module such as
[Arduino 101](./boards/arduino_101.md) or [K64F](./boards/frdm_k64f.md) to
specify a named pin.
-Use the AIOPin object returned to read values from the pin.
+AIOPin API
+----------
+### pin.read()
+* Returns: the latest reading from the pin (an unsigned integer). Blocks until it gets the result.
-### AIOPin.read
+### pin.readAsync(callback)
+* 'callback' *ReadCallback* User-provided callback function that takes
+ a single unsigned integer and has no return value.
-`unsigned long read();`
-
-Returns the latest reading from the pin. Blocks until it gets the result.
-
-### AIOPin.readAsync
-
-`void readAsync(ReadCallback callback);`
-
-Pass a function for `callback` that will be called later when the result is
+Pass a function for `ReadCallback` that will be called later when the result is
obtained.
*WARNING: Making an async call like this allocates some memory while the call
-is pending, so if you issue them faster than they are fulfilled, you will
+is pending; if async calls are issued faster than they are fulfilled,
+the system will
eventually run out of memory - pretty soon on these small devices. So the best
-practice would be to make sure you only have a small, fixed number pending at
+practice would be to have only a small, fixed number pending at
any given time.*
*NOTE: This function will probably be replaced with a version that instead
returns a promise.*
-### AIOPin.on
-
-`void on(string eventType, ReadCallback callback);`
+### pin.on(eventType, callback)
+* 'eventType' *string* Type of event; currently, the only supported
+ type is "change".
+* 'callback' *ReadCallback* User-provided callback function that takes
+ a single, unsigned integer and has no return value; can be null.
-Currently, the only supported `eventType` is 'change', and `callback` should
-be either a function or null. When a function is passed for the change event,
-the function will be called any time the analog voltage changes. (At the moment,
+The callback function is called any time the analog voltage changes. (At the moment,
it actually gets called periodically even when it hasn't changed.) When null is
passed for the change event, the previously registered callback will be
discarded and no longer called.
-### AIOPin.close
-
-`void close();`
+### pin.close()
-Closes the AIOPin. Once it is closed, all event handlers registered will no
+Closes the AIOPin. Once it is closed, all registered event handlers will no
longer be called.
Sample Apps
diff --git a/docs/ble.md b/docs/ble.md
index aa127d9..5908562 100644
--- a/docs/ble.md
+++ b/docs/ble.md
@@ -3,7 +3,20 @@ ZJS API for Bluetooth Low Energy (BLE)
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [BLE-supported Events](#ble\-supported-events)
+* [Class: BLE](#ble-api)
+ * [ble.disconnect(address)](#bledisconnectaddress)
+ * [ble.startAdvertising(name, uuids, [url])](#blestartadvertisingname-uuids-url)
+ * [ble.stopAdvertising()](#blestopadvertising)
+ * [ble.setServices(primaryServices)](#blesetservicesprimaryservices)
+ * [ble.newPrimaryService(init)](#blenewprimaryserviceinit)
+ * [ble.newCharacteristic(init)](#blenewcharacteristicinit)
+ * [ble.newDescriptor(init)](#blenewdescriptorinit)
+* [Class: Characteristic](#characteristic-api)
+* [Supporting Objects](#supporting-objects)
+ * [PrimaryServiceInit](#primaryserviceinit)
+ * [CharacteristicInit](#characteristicinit)
+ * [DescriptorInit](#descriptorinit)
* [Client Requirements](#client-requirements)
* [Sample Apps](#sample-apps)
@@ -24,191 +37,204 @@ treat them like decimals.*
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-```javascript
+This IDL provides an overview of the interface; see below for documentation of
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a BLE object
// var ble = require('ble');
-
-[NoInterfaceObject]
+[ReturnFromRequire,ExternalInterface=(EventEmitter)]
interface BLE: EventEmitter {
void disconnect(string address);
- void startAdvertising(string name, string[] uuids, string url);
+ void startAdvertising(string name, sequence < string > uuids, optional string url);
void stopAdvertising();
- void setServices(PrimaryService services[]);
- PrimaryService PrimaryService(PrimaryServiceInit init);
- Characteristic Characteristic(CharacteristicInit init);
- Descriptor Descriptor(DescriptorInit init);
-};
-
+ void setServices(sequence < PrimaryService > services);
+ PrimaryService newPrimaryService(PrimaryServiceInit init);
+ Characteristic newCharacteristic(CharacteristicInit init);
+ DescriptorInit newDescriptor(DescriptorInit init);
+};<p>
dictionary PrimaryServiceInit {
string uuid;
- Characteristic[] characteristics;
-};
-
-dictionary CharacteristicInit {
+ sequence < Characteristic > characteristics;
+};<p>dictionary PrimaryService {
+ string uuid;
+ sequence < Characteristic > characteristics;
+};<p>dictionary CharacteristicInit {
string uuid;
- string[] properties; // 'read', 'write', 'notify'
- Descriptor[] descriptors;
+ sequence < string > properties; // 'read', 'write', 'notify'
+ sequence < DescriptorInit > descriptors;
ReadCallback onReadRequest; // optional
WriteCallback onWriteRequest; // optional
SubscribeCallback onSubscribe; // optional
UnsubscribeCallback onUnsubscribe; // optional
NotifyCallback onNotify; // optional
-};
-
-callback ReadCallback = void (unsigned long offset, FulfillReadCallback);
+};<p>interface Characteristic {
+ attribute ReadCallback onReadRequest;
+ attribute WriteCallback onWriteRequest;
+ attribute SubscribeCallback onSubscribe;
+ attribute UnsubscribeCallback onUnsubscribe;
+ attribute NotifyCallback onNotify;
+ attribute CharacteristicResult response;
+};<p>callback ReadCallback = void (unsigned long offset,
+ FulfillReadCallback fulfillReadCallback);
+[ExternalInterface=(Buffer)]
callback WriteCallback = void (Buffer data, unsigned long offset,
- boolean withoutResponse, FulfillWriteCallback);
+ boolean withoutResponse,
+ FulfillWriteCallback fulfillWriteCallback);
callback SubscribeCallback = void (unsigned long maxValueSize,
- FulfillSubscribeCallback);
+ FulfillSubscribeCallback fullfillSubscribeCallback);
callback FulfillReadCallback = void (CharacteristicResult result, Buffer data);
callback FulfillWriteCallback = void (CharacteristicResult result);
callback FulfillSubscribeCallback = void (Buffer data);
-
+callback NotifyCallback = void (any... params);
+callback UnsubscribeCallback = void (any... params);
+enum CharacteristicResult { "RESULT_SUCCESS", "RESULT_INVALID_OFFSET",
+ "RESULT_INVALID_ATTRIBUTE_LENGTH", "RESULT_UNLIKELY_ERROR" };
dictionary DescriptorInit {
string uuid;
string value;
-};
+};</pre>
+</details>
-[NoInterfaceObject]
-interface Characteristic {
- attribute ReadCallback onReadRequest;
- attribute WriteCallback onWriteRequest;
- attribute SubscribeCallback onSubscribe;
- attribute UnsubscribeCallback onUnsubscribe;
- attribute NotifyCallback onNotify;
- unsigned long RESULT_SUCCESS;
- unsigned long RESULT_INVALID_OFFSET;
- unsigned long RESULT_INVALID_ATTRIBUTE_LENGTH;
- unsigned long RESULT_UNLIKELY_ERROR;
-};
-```
-
-API Documentation
------------------
+BLE-supported Events
+--------------------
BLE is an [EventEmitter](./events.md) with the following events:
-### Event: 'accept'
+### Event: `accept`
* `string` `clientAddress`
Emitted when a BLE client has connected. `clientAddress` is a unique BLE address
for the client in colon-separated format (e.g. 01:23:45:67:89:AB).
-### Event: 'advertisingStart'
+### Event: `advertisingStart`
* `int` `status`
Emitted when BLE services have begun to be advertised. The `status` will be 0
for success, otherwise for an error.
-### Event: 'disconnect'
+### Event: `disconnect`
* `string` `clientAddress`
Emitted when a BLE client has disconnected. `clientAddress` will be the same as
-one previously sent with the 'accept' event.
+one previously sent with the `accept` event.
-### Event: 'stateChange'
+### Event: `stateChange`
* `string` `newState`
-Emitted with 'poweredOn' when the BLE stack is ready to be used. No other states
+Emitted with `poweredOn` when the BLE stack is ready to be used. No other states
are supported at this time.
-### BLE.disconnect
-
-`void disconnect(string address);`
+BLE API
+-------
+### ble.disconnect(address)
+* `address` *string* The address of the connected client.
Disconnect the remote client.
-The `address` is the address of the connected client.
+### ble.startAdvertising(name, uuids, [url])
+* `name` *string* The `name` is limited to 26 characters and will be
+ advertised as the device name to nearby BLE devices.
+* `uuids` *string[]* The `uuids` array may contain at most 7 16-bit
+ UUIDs (four hex digits each). These UUIDs identify available
+ services to nearby BLE devices.
+* `url` *string* The `url` is optional and limited to around 24
+ characters (slightly more if part of the URL is able to be
+ [encoded](https://github.com/google/eddystone/tree/master/eddystone-url). If
+ provided, this will be used to create a physical web advertisement
+ that will direct users to the given URL. At that URL they might be
+ able to interact with the advertising device somehow.
-### BLE.startAdvertising
+Advertises the name and url of the device.
-`void startAdvertising(string name, string[] uuids, string url);`
+### ble.stopAdvertising()
-The `name` is limited to 26 characters and will be advertised as the device
-name to nearby BLE devices.
+Currently does nothing.
-The `uuids` array may contain at most 7 16-bit UUIDs (four hex digits each).
-These UUIDs identify available services to nearby BLE devices.
+### ble.setServices(primaryServices)
+* `primaryServices` *array of [PrimaryService](#primaryservice) objects* The PrimaryService
+ objects are used to set up the services that are implemented by your
+ app.
-The `url` is optional and limited to around 24 characters (slightly more
-if part of the URL is able to be [encoded](https://github.com/google/eddystone/tree/master/eddystone-url). If provided,
-this will be used to create a physical web advertisement that will direct users
-to the given URL. At that URL they might be able to interact with the
-advertising device somehow.
+The PrimaryService object contains the following fields:
-### BLE.stopAdvertising
-`void stopAdvertising();`
+### ble.newPrimaryService(init)
+* `init` [*PrimaryServiceInit*](#primaryserviceinit)
+* Returns: a new PrimaryService object.
-Currently does nothing.
+### ble.newCharacteristic(init)
+* `init` [*CharacteristicInit*](#characteristicinit)
+* Returns: a new Characteristic object.
-### BLE.setServices
-`void setServices(PrimaryService[]);`
+### ble.newDescriptor(init)
+* `init` [*DescriptorInit*](#descriptorinit)
+* Returns: a new DescriptorInit object.
-Pass an array of PrimaryService objects to set up the services that are
-implemented by your app.
-### BLE.PrimaryService constructor
+Characteristic API
+------------------
+The "Characteristic" object contains the set of callbacks that...[[TODO!!!]]
-`PrimaryService(PrimaryServiceInit init);`
+Explanation of common arguments to the above functions:
+* `offset` is a 0-based integer index into the data the characteristic
+ represents.
+* `result` is one of these values defined in the Characteristic object.
+ * RESULT_SUCCESS
+ * RESULT_INVALID_OFFSET
+ * RESULT_INVALID_ATTRIBUTE_LENGTH
+ * RESULT_UNLIKELY_ERROR
+* `data` is a [Buffer](./buffer.md) object.
+
+Supporting Objects
+------------------
+
+### PrimaryServiceInit
-The `init` object should contain a `uuid` field with a 16-bit service UUID (4
-hex chars) and a `characteristics` field with an array of Characteristic
-objects.
+This object has two fields:
+1. `uuid` *string* This field is a 16-bit service UUID (4 hex chars).
+2. `characteristics` *array of [Characteristics](#characteristic-api)*
-### BLE.Characteristic constructor
-`Characteristic(CharacteristicInit init);`
+### CharacteristicInit
-The `init` object should contain:
-* `uuid` field with a 16-bit characteristic UUID (4 hex chars)
-* `properties` field with an array of strings that may include 'read', 'write',
- and 'notify', depending on what is supported
-* `descriptors` field with an array of Descriptor objects
+This object has 3 required fields:
+1. `uuid` *string* This field is a 16-bit characteristic UUID (4 hex chars).
+2. `properties` *array of strings* Possible values: 'read', 'write', and 'notify', depending on what is supported.
+3. `descriptors` *array of [Descriptors](#descriptor)*
It may also contain these optional callback fields:
-* `onReadRequest` function(offset, callback(result, data))
+1. `onReadRequest` *ReadCallback*
* Called when the client is requesting to read data from the characteristic.
* See below for common argument definitions
-* `onWriteRequest` function(data, offset, withoutResponse, callback(result))
+2. `onWriteRequest` *WriteCallback*
* Called when the client is requesting to write data to the characteristic.
* `withoutResponse` is true if the client doesn't want a response
* *TODO: verify this*
-* `onSubscribe` function(maxValueSize, callback(data))
+3. `onSubscribe` *SubscribeCallback*
* Called when a client signs up to receive notify events when the
characteristic changes.
* `maxValueSize` is the maximum data size the client wants to receive.
-* `onUnsubscribe` function()
+4. `onUnsubscribe` *UnsubscribeCallback*
* *NOTE: Never actually called currently.*
-* `onNotify` function()
+5. `onNotify` *NotifyCallback*
* *NOTE: Never actually called currently.*
-Explanation of common arguments to the above functions:
-* `offset` is a 0-based integer index into the data the characteristic
- represents.
-* `result` is one of these values defined in the Characteristic object.
- * RESULT_SUCCESS
- * RESULT_INVALID_OFFSET
- * RESULT_INVALID_ATTRIBUTE_LENGTH
- * RESULT_UNLIKELY_ERROR
-* `data` is a [Buffer](./buffer.md) object.
-
-### BLE.Descriptor constructor
-`Descriptor(DescriptorInit init);`
+### DescriptorInit
-The `init` object should contain:
-* `uuid` field with a 16-bit descriptor UUID (4 hex chars)
- * Defined descriptors are listed here in [Bluetooth Specifications](https://www.bluetooth.com/specifications/gatt/descriptors)
-* `value` field with a string supplying the defined information
- * *NOTE: Values can also be Buffer objects, but that's not currently supported.*
+This object has two fields:
+1. `uuid` *string* This is a 16-bit descriptor UUID (4 hex chars)
+ * Defined descriptors are listed here in [Bluetooth Specifications](https://www.bluetooth.com/specifications/gatt/descriptors)
+2. `value` *string* This string supplies the defined information.
+ * *NOTE: Values can also be Buffer objects, but that's not currently
+ supported.*
Client Requirements
-------------------
diff --git a/docs/board.md b/docs/board.md
index e4edf85..c738baf 100644
--- a/docs/board.md
+++ b/docs/board.md
@@ -3,7 +3,9 @@ ZJS Board API
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: Board](#board-api)
+ * [board.name](#boardname)
+ * [board.version](#boardversion)
* [Sample Apps](#sample-apps)
Introduction
@@ -15,23 +17,23 @@ but both that and ZJS are under a lot of change at the moment.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-```javascript
-// require returns the Board API object
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>// require returns the Board API object
// var board = require('board');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface Board {
- string name;
- string version;
-};
-```
+ attribute string name5;
+ attribute string version;
+};</pre>
+</details>
-API Documentation
+Board API
-----------------
-### Board.name
+### board.name
`string name;`
@@ -42,14 +44,14 @@ When code is run under Linux with the jslinux utility, it currently reports a
board name of "linux (partially simulating arduino_101)".
Any other board will show up with "unknown". Even if the board is unknown, you
-can still use the [GPIO API](gpio.md) at least by consulting Zephyr
+can still use the [GPIO API](gpio.md) by consulting Zephyr
documentation for the board's GPIO port names and pin numbers.
-### Board.version
+### board.version
`string version;`
-For now, just returns "0.1". Stay tuned!
+Currently, this value is always set to "0.1". Stay tuned!
Sample Apps
-----------
diff --git a/docs/buffer.md b/docs/buffer.md
index 17f1bb3..56b8b25 100644
--- a/docs/buffer.md
+++ b/docs/buffer.md
@@ -2,10 +2,11 @@ ZJS API for Buffer
==================
* [Introduction](#introduction)
+* [Web IDL](#web-idl)
* [Class: Buffer](#buffer-api)
- * [new Buffer(array)](#new-bufferarray)
+ * [new Buffer(initialValues)](#new-bufferinitialvalues)
* [new Buffer(size)](#new-buffersize)
- * [new Buffer(string)](#new-bufferstring)
+ * [new Buffer(initialString)](#new-bufferinitialstring)
* [buf.copy(target[, targetStart, [sourceStart[, sourceEnd]]])](#bufcopytarget-targetstart-sourcestart-sourceend)
* [buf.fill(value[, offset[, end[, encoding]]])](#buffillvalue-offset-end-encoding)
* [buf.readUInt*(offset)](#bufreaduint-family)
@@ -20,29 +21,66 @@ Buffer is a [Node.js API](https://nodejs.org/dist/latest-v8.x/docs/api/buffer.ht
to read and write binary data accurately from JavaScript. ZJS supports a minimal
subset of this API that will be expanded as the need arises.
+Web IDL
+-------
+This IDL provides an overview of the interface; see below for documentation of
+specific API functions. We have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
+[ Constructor(sequence < Uint8 > initialValues),
+ Constructor(unsigned long size),
+ Constructor(ByteString initialString), ]
+interface Buffer {
+ readonly attribute unsigned long length;
+ attribute ArrayBuffer buffer;
+ unsigned long copy(Buffer target, optional unsigned long targetStart = 0,
+ optional unsigned long sourceStart = 0,
+ optional unsigned long sourceEnd);
+ this fill((string or Buffer or long) value, optional long offset = 0,
+ optional long end,
+ optional string encoding = "utf8");
+ octet readUInt8(optional unsigned long offset = 0);
+ short readUInt16BE(optional unsigned long offset = 0);
+ short readUInt16LE(optional unsigned long offset = 0);
+ long readUInt32BE(optional unsigned long offset = 0);
+ long readUInt32LE(optional unsigned long offset = 0);
+ string toString(string encoding);
+ long write(string value, optional long offset = 0,
+ optional long length = 0,
+ optional string encoding = "utf8");
+ long writeUInt8(octet value, unsigned long offset);
+ long writeUInt16BE(unsigned short value, unsigned long offset);
+ long writeUInt16LE(unsigned short value, unsigned long offset);
+ long writeUInt32BE(unsigned long value, unsigned long offset);
+ long writeUInt32LE(unsigned long value, unsigned long offset);
+};</pre>
+</details>
+
Buffer API
----------
-### new Buffer(array)
-* `array` *integer[]* Array of octets to use as initial data.
+### new Buffer(initialValues)
+* `initialValues` *integer-array* of octets to use as initial data.
-The `array` argument should be an array of numbers that will be treated as
-UInt8 integers. A new buffer object will be returned with the same size as the
-array and initialized with its contents. If there is not enough available
-memory, an error will be thrown.
+A new Buffer object will be returned with the same size as the array
+and initialized with the array's contents. If there is not enough
+available memory, an error will be thrown.
### new Buffer(size)
* `size` *integer* Length in bytes of the new buffer.
The `size` argument specifies the length in bytes of the array that the Buffer
represents. If a negative length is passed, a 0-length Buffer will be returned.
-If the size is too long and there is not enough available memory, an error will
+If there is not enough available memory to allocate the Buffer, an error will
be thrown.
-### new Buffer(string)
-* `string` *string* String to use as initial data.
+### new Buffer(initialString)
+* `initialString` *string* String to use as initial data.
-The `string` argument will be treated as UTF8 and used to initialize the new
-buffer. If there is not enough available memory, an error will be thrown.
+The `string` argument will be treated as an array of UTF8 values and
+will be used to initialize the new buffer. If there is not enough
+available memory, an error will be thrown.
### buf.copy(target[, targetStart, [sourceStart[, sourceEnd]]])
* `target` *Buffer* Buffer to receive the copied data.
diff --git a/docs/console.md b/docs/console.md
index a03aebe..eee4c81 100644
--- a/docs/console.md
+++ b/docs/console.md
@@ -2,55 +2,85 @@ ZJS API for Console
==================
* [Introduction](#introduction)
-* [API Documentation](#api-documentation)
+* [Web IDL](#web-idl)
+* [Class: Console](#console-api)
+ * [console.assert(value, [message])](#consoleassertvalue-message)
+ * [console.error([data])](#consoleerrordata)
+ * [console.warn([data])](#consolewarndata)
+ * [console.log([data])](#consolelogdata)
+ * [console.info([data])](#consoleinfodata)
+ * [console.time(label)](#consoletimelabel)
+ * [console.timeEnd(label)](#consoletimeendlabel)
* [Sample Apps](#sample-apps)
Introduction
------------
-ZJS provides console API's which match Node.js' Console module. We describe them here as there could
-potentially be minor differences.
-
-Note that the console API's do not support format specifiers (e.g. %d, %f etc.).
-
-API Documentation
------------------
+ZJS provides console APIs which match Node.js' Console module. We
+describe them here as there could be minor differences.
+
+Note that the console APIs do not support format specifiers (e.g., %d, %f etc.).
+
+Web IDL
+-------
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>
+// require returns a Console object
+// var console = require('console');
+[ReturnFromRequire]
+interface Console {
+ void assert(boolean value, optional string message);
+ void error(optional string data);
+ void warn(optional string data);
+ void log(optional string data);
+ void info(optional string data);
+ void time(string label);
+ void timeEnd(string label);
+};</pre>
+</details>
+
+Console API
+-----------
-### assert
-`void assert(boolean value, optional string message);`
+### console.assert(value, [message])
+* `value` *boolean*
+* `message` *string* Optional message to print.
Assert/throw an error if `value` is false.
-### error
-`void error(optional string data);`
+### console.error([data])
+* `data` *string* Optional message to print.
Prints `data` to `stderr` with newline. (On Zephyr this will just print to stdout).
-### warn
-`void warn(optional string data);`
+### console.warn([data])
+* `data` *string* Optional message to print.
Alias for `console.error()`
-### log
-`void log(optional string data);`
+### console.log([data])
+* `data` *string* Optional message to print.
Prints `data` to `stdout` with newline.
-### info
-`void info(optional string data);`
+### console.info([data])
+* `data` *string* Optional message to print.
Alias for `console.log()`.
-### time
-`void time(string label);`
+### console.time(label)
+* `label` *string* This string is used to reference the timer when calling `console.timeEnd()`.
-Starts a timer used to compute the duration of an operation. The `label` string is used
-to reference the timer when calling `console.timeEnd()`.
+Starts a timer used to compute the duration of an operation.
-### timeEnd
-`void timeEnd(string label);`
+### console.timeEnd(label)
+* `label` *string* The label identifying the timer started with `console.time()`.
-Stops a timer previously started with `console.time()` and prints the resulting time
-difference to `stdout`.
+Stops a timer previously started with `console.time()` and prints the resulting time difference to `stdout`.
Sample Apps
-----------
diff --git a/docs/dgram.md b/docs/dgram.md
index bfe2127..1284db5 100644
--- a/docs/dgram.md
+++ b/docs/dgram.md
@@ -3,8 +3,13 @@ ZJS API for UDP datagram sockets
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
-* [Client Requirements](#requirements)
+* [Dgram API](#dgram-api)
+ * [dgram.createSocket(type)](#dgramcreatesockettype)
+* [DgramSocket API](#dgramsocket-api)
+ * [DgramSocket.on(event, callback)](#dgramsocketonevent-callback)
+ * [DgramSocket.bind(port, ip_addr)](#dgramsocketbindport-ip_addr)
+ * [DgramSocket.send(buf, offset, len, port, ip_addr, [cb])](#dgramsocketsendbuf-offset-len-port-ip_addr-cb)
+ * [DgramSocket.close](#dgramsocketclose)
* [Sample Apps](#sample-apps)
Introduction
@@ -16,49 +21,46 @@ It allows you to send and receive UDP datagrams.
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-
-```javascript
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a socket factory object
// var dgram = require('dgram');
-
-[NoInterfaceObject]
-interface dgram {
+[ReturnFromRequire]
+interface Dgram {
DgramSocket createSocket(string udp4_or_udp6);
-};
-
-[NoInterfaceObject]
+};<p>
+[ExternalInterface=(Buffer)]
interface DgramSocket {
void on(string event, RecvCallback cb);
- void bind(int port, string ip_addr);
- void send(Buffer buf, unsigned long offset, unsigned long len, int port, string ip_addr, [SendCallback cb]);
+ void bind(long port, string ip_addr);
+ void send(Buffer buf, unsigned long offset, unsigned long len, long port,
+ string ip_addr, optional SendCallback cb);
void close();
-};
-
-callback RecvCallback = void (Buffer msg, RemoteInfo rinfo);
+};<p>callback RecvCallback = void (Buffer msg, RemoteInfo rinfo);
callback SendCallback = void (Error err); // or undefined if no error
-
-
-callback EventCallback = void (various); // callback arg depends on event
-
-dictionary RemoteInfo {
+callback EventCallback = void (any... args); // callback args depend on event<p>dictionary RemoteInfo {
string ip_addr;
string family;
- int port;
+ long port;
};
-```
-
-API Documentation
------------------
-### dgram.createSocket
+</pre>
+</details>
-`DgramSocket createSocket(string type);`
+Dgram API
+---------
+### dgram.createSocket(type)
+* `type` *string* Must be `'udp4'` or `'udp6'`.
+* Returns: DgramSocket object.
-Create a datagram socket of given type, which must be `'udp4'` or `'udp6'`.
+Create a datagram socket of the given type.
-### DgramSocket.on
-
-`void on(string event, RecvCallback callback);`
+DgramSocket API
+---------------
+### DgramSocket.on(event, callback)
+* `event` *string*
+* `callback` *RecvCallback*
Registers a callback. The `event` may be one of the following:
@@ -69,35 +71,37 @@ Registers a callback. The `event` may be one of the following:
(In the current version, this callback is never called, but this
will change in future versions.)
-### DgramSocket.bind
-
-`void bind(int port, string ip_addr);`
-
-Bind socket to a local address and port. This is required operation for
-server-side sockets, i.e. sockets which wait and receive data from other
-network nodes. `ip_addr` must be a string representing an IP address of
+### DgramSocket.bind(port, ip_addr)
+* `port` *long*
+* `ip_addr` *string* `ip_addr` A string representing an IP address of
a *local* network interface, or a "wildcard" address of `'0.0.0.0'` (IPv4)
or `'::'` (IPv6), in which case a socket will be bound to all local
-interfaces. This module does not support domain name resolution, so only
+interfaces.
+
+Bind socket to a local address and port. This is a required operation for
+server-side sockets, i.e., sockets that wait and receive data from other
+network nodes. This module does not support domain name resolution, so only
IP addresses are allowed. At the time of writing, local interface
addresses are hardcoded to be: `'192.0.2.1'` (IPv4) and `'2001:db8::1'`
-(IPv6) (but these will become configurable in the future).
+(IPv6), but these will become configurable in the future.
-### DgramSocket.send
-
-`void send(Buffer buf, unsigned long offset, unsigned long len, int port, string ip_addr, [SendCallback cb]);`
+### DgramSocket.send(buf, offset, len, port, ip_addr, [cb])
+* `buf` *Buffer*
+* `offset` *unsigned long*
+* `len` *unsigned long*
+* `port` *long*
+* `ip_addr` *string*
+* `cb` *SendCallback* Optional.
Send data contained in a buffer to remote network node. A subset of
data in `buf` can be sent using `offset` and `len` parameters. To send
-entire buffer, using values `0` and `buf.length` respectively. See
-`bind()` method description for the format of `ip_addr`. An optional
+the entire buffer, use values `0` and `buf.length` respectively. See
+the `bind()`-method description for the format of `ip_addr`. An optional
callback may be provided, which will be called with the result of the send
-operation: either NetworkError object in case of error, or `undefined`
+operation: either a NetworkError object in the case of error, or `undefined`
on success.
-### DgramSocket.close
-
-`void close();`
+### DgramSocket.close()
Closes socket.
diff --git a/docs/events.md b/docs/events.md
index 4b8ec6c..48e0c8f 100644
--- a/docs/events.md
+++ b/docs/events.md
@@ -3,121 +3,105 @@ ZJS API for Events
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: EventEmitter](#eventemitter-api)
+ * [EventEmitter.on(event, listener)](#eventemitteronevent-listener)
+ * [EventEmitter.addListener(event, listener)](#eventemitteraddlistenerevent-listener)
+ * [EventEmitter.emit(event, [args...])](#eventemitteremitevent-args)
+ * [EventEmitter.removeListener(event, listener)](#eventemitterremovelistenerevent-listener)
+ * [EventEmitter.removeAllListeners(event)](#eventemitterremovealllistenersevent)
+ * [EventEmitter.eventNames()](#eventemittereventnames)
+ * [EventEmitter.getMaxListeners()](#eventemittergetmaxlisteners)
+ * [EventEmitter.listeners(event)](#eventemitterlistenersevent)
+ * [EventEmitter.setMaxListeners(max)](#eventemittersetmaxlistenersmax)
* [Sample Apps](#sample-apps)
Introduction
------------
-ZJS provides event API's which match Node.js Event's. We describe them here as there could
-potentially be minor differences.
+ZJS provides event APIs that match `Node.js` `Event`s. We describe
+them here as there could be minor differences.
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-
-```javascript
-
-callback ListenerCallback = void (...);
-
-interface EventEmitter {
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
+callback ListenerCallback = void (any... params);<p>interface EventEmitter {
this on(string event, ListenerCallback listener);
this addListener(string event, ListenerCallback listener);
- boolean emit(string event, optional arg1, ...);
+ boolean emit(string event, any... args);
this removeListener(string event, ListenerCallback listener);
this removeAllListeners(string event);
- string[] eventNames(void);
- number getMaxListeners(void);
- ListenerCallback[] listeners(string event);
- this setMaxListeners(number max);
+ sequence < string > eventNames();
+ long getMaxListeners();
+ sequence < ListenerCallback > listeners(string event);
+ this setMaxListeners(long max);
};
-```
+</pre>
+</details>
-API Documentation
------------------
-
-### on
-`this on(string event, ListenerCallback listener);`
+EventEmitter API
+----------------
+### EventEmitter.on(event, listener)
+* `event` *string* The name of the event that you are adding a listener to.
+* `listener` *ListenerCallback* The function that you wish to be called when this event is emitted/triggered.
+* Returns: `this` so calls can be chained.
Add an event listener function.
-The `event` argument is the name of the event which you are adding a listener too.
-
-The `listener` argument is the function that you wish to be called when this event
-is emitted/triggered.
+### EventEmitter.addListener(event, listener)
+* `event` *string* The name of the event that you are adding a listener to.
+* `listener` *ListenerCallback* The function that you wish to be called when this event is emitted/triggered.
+* Returns: `this` so calls can be chained.
-Returns `this` so calls can be chained.
+Same as `EventEmitter.on()`.
-### addListener
-`this addListener(string event, ListenerCallback listener);`
+### EventEmitter.emit(event, [args...])
+* `event` *string* The name of the event that you want to emit.
+* `args` *optional* All other arguments will be given to any registered listener functions.
+* Returns: true if there were any listener functions called.
-Same as `on()`.
+Triggers an event. Any listener functions that have been added to the
+event emitter under the event name will be called.
-### emit
-`boolean emit(string event, optional arg1, ...);`
-Triggers an event. Any listener functions which have been added to the event emitter
-under the event name will be called.
-
-The `event` argument is the name of the event that you want to emit.
-
-All other arguments will be given to any registered listener functions.
-
-Returns true if there were any listener functions called.
-
-### removeListener
-`this removeListener(string event, ListenerCallback listener);`
+### EventEmitter.removeListener(event, listener)
+* `event` *string* The name of the event you are removing the listener from.
+* `listener` *ListenerCallback* The function you want to remove as a listener.
+* Returns: `this` so calls can be chained.
Removes a listener function from an event.
-The `event` argument is the name of the event you are removing the listener from.
-
-The `listener` arugment is the actual function you want to remove as a listener.
-
-Returns `this` so calls can be chained.
-
-### removeAllListeners
-`this removeAllListeners(string event);`
+### EventEmitter.removeAllListeners(event)
+* `event` *string* The name of the event from which to remove all listeners.
+* Returns: `this` so calls can be chained.
Removes all listeners from an event
-The `event` argument is the name of the event to remove all listeners from
-
-Returns `this` so calls can be chained
-### eventNames
-`string[] eventNames(void);`
+### EventEmitter.eventNames()
+* Returns: an array of strings that correspond to any events. Will return undefined if there are no event's or event listeners for this event emitter.
Get a list of event names from an event emitter object.
-Returns an array of strings that correspond to any events. Will return undefined
-if there are no event's or event listeners for this event emitter.
-
-### getMaxListeners
-`number getMaxListeners(void);`
+### EventEmitter.getMaxListeners()
+* Returns: the maximum number of listeners allowed.
Get the maximum number of listeners allowed for this event emitter object.
-Returns the max number of listeners allowed.
-
-### listeners
-`ListenerCallback[] listeners(string event);`
+### EventEmitter.listeners(event)
+* `event` *string* The name of the event from which to retrieve the listerners.
+* Returns: an array of functions that correspond to the `ListenerCallbacks` for the event specified.
Get a list of listeners for an event.
-The `event` parameter is the name of the event you are retrieving the listerners from.
-
-Returns an array of functions which correspond to the listeners for the event specified.
-
-### setMaxListeners
-`this setMaxListeners(number max);`
+### EventEmitter.setMaxListeners(max)
+* `max` *long* The number of listeners the event emitter can have.
+* Returns: `this`, so calls can be chained.
Set the max number of listeners for an event emitter object
-The `max` argument is the number of listeners the event emitter can have
-
-Returns `this` so calls can be chained.
-
Sample Apps
-----------
* [Events sample](../samples/tests/Events.js)
diff --git a/docs/fs.md b/docs/fs.md
index c6a6afb..0cd9819 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -2,21 +2,36 @@ ZJS API for File System
==================
* [Introduction](#introduction)
-* [API Documentation](#api-documentation)
-* [Sample Apps](#sample-apps)
+* [Web IDL](#web-idl)
+* [Class FS](#fs-api)
+ * [fs.openSync(path, mode)](#fsopensyncpath-mode)
+ * [fs.closeSync(fd)](#fsclosesyncfd)
+ * [fs.unlinkSync(path)](#fsunlinksyncpath)
+ * [fs.rmdirSync(path)](#fsrmdirsyncpath)
+ * [fs.writeSync(fd, data, offset, length, [position])](#fswritesyncfd-data-offset-length-position)
+ * [fs.readSync(fd, data, offset, length, [position])](#fsreadsyncfd-data-offset-length-position)
+ * [fs.truncateSync(path, length)](#fstruncatesyncpath-length)
+ * [fs.mkdirSync(path)](#fsmkdirsyncpath)
+ * [fs.readdirSync(path)](#fsreaddirsyncpath)
+ * [fs.statSync(path)](#fsstatsyncpath)
+ * [writeFileSync(file, data)](#writefilesyncfile-data)
+* [Class Stat](#stat-api)
+ * [stat.isFile()](#statisfile)
+ * [stat.isDirectory()](#statisdirectory)
Introduction
------------
-ZJS provides File System API's which match Node.js' FS module. We describe them
-here as there could potentially be minor differences. It should be noted that by
-default the FS module only contains the synchronous Node.js API's. The
-asynchronous API's can be compiled in by enabling the pre-processor define
-`ZJS_FS_ASYNC_APIS`. They are compiled out because all of Zephyr's File
-System API's are synchronous, so making the JavaScript API's asynchronous was
-only adding ROM space.
-
-On the Arduino 101 the flash file system uses SPI and the pins are shared with
-IO10-13. For this reason you will not be able to use these GPIO pins at the
+
+ZJS provides File System APIs that match Node.js' FS module. We
+describe them here to document any minor differences. It should be
+noted that by default, the FS module only contains the synchronous
+Node.js APIs. The asynchronous APIs can be compiled in by enabling the
+pre-processor value `ZJS_FS_ASYNC_APIS`. The default is to leave them
+out, because all of Zephyr's File System APIs are synchronous, so
+making the JavaScript APIs asynchronous was only adding ROM space.
+
+On the Arduino 101, the flash file system uses SPI, and the pins are shared with
+IO10-13. For this reason, you will not be able to use these GPIO pins at the
same time as the file system.
Available file modes:
@@ -27,148 +42,142 @@ not exist.
`'r+'` - Open a file for reading and writing. An error will be thrown if the
file does not exist.
-`'w'` - Opens a file for writing. The file will be overwritten if it already
+`'w'` - Open a file for writing. The file will be overwritten if it already
exists.
-`'w+'` - Opens a file for writing and reading. The file will be overwritten if
+`'w+'` - Open a file for writing and reading. The file will be overwritten if
it already exists.
`'a'` - Opens a file for appending. The write pointer will always seek
to the end of the file during a write.
-`'a+'` - Opens a file for appending and reading. As with `'a'` the write
-pointer will seek to the end for writes, but reads can be done from the
-start of the file (read pointer saved across different read calls).
+`'a+'` - Opens a file for appending and reading. The write
+pointer will seek to the end for writes, but reads will be done from the
+start of the file (the read pointer is saved across different read calls).
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>
// require returns a FS object
// var fs = require('fs');
-
-interface Stat {
+[ReturnFromRequire, ExternalInterface=(Buffer)]
+interface FS {
+ FileDescriptor openSync(string path, FileMode mode);
+ void closeSync(FileDescriptor fd);
+ void unlinkSync(string path);
+ void rmdirSync(string path);
+ long writeSync(FileDescriptor fd, (string or Buffer) data, long offset,
+ long length, optional long position);
+ long readSync(FileDescriptor fd, Buffer data, long offset,
+ long length, optional long position);
+ void truncateSync(string path, long length);
+ void mkdirSync(string path);
+ sequence < string > readdirSync(string path);
+ Stat statSync(string path);
+ void writeFileSync(string file, (string or Buffer) data);
+};<p>
+// file descriptors are inherently platform specific, so we leave this
+// as a placeholder
+dictionary FileDescriptor {
+ //string name;
+};<p>interface Stat {
boolean isFile();
boolean isDirectory();
-};
-```
+};<p>enum FileMode { "r", "w", "a", "r+", "w+", "a+" };</pre>
+</details>
-API Documentation
------------------
+FS API
+------
-### FS.openSync
-`object openSync(string path, string mode);`
+### fs.openSync(path, mode)
+* `path` *string* The name and path of the file to open.
+* `mode` *FileMode* The mode in which to open the file.
+* Returns: an object representing the file descriptor.
Opens a file.
-`path` is the name/path of the file to open.
-
-`mode` is the mode to open the file in (r/w/a/r+/w+/a+).
-
-Returns an object representing the file descriptor.
-
-### FS.closeSync
-`void closeSync(object fd);`
+### fs.closeSync(fd)
+* `fd` *FileDescriptor* The file descriptor for the file that will be closed.
Closes a file.
-`fd` is the descriptor returned from `openSync()`.
-
-### FS.unlinkSync
-`void unlinkSync(string path);`
+### fs.unlinkSync(path)
+* `path` *string* The name and path of the file to remove.
Unlink (remove) a file from the file system.
-`path` is the file to remove.
-
-### FS.rmdirSync
-`void rmdirSync(string path);`
+### fs.rmdirSync(path)
+* `path` *string* The name and path of the directory to be removed.
Remove a directory from the file system.
-`path` is the name of the directory.
-
-### FS.writeSync
-`number writeSync(object fd, Buffer data, number offset, number length, optional number position);`
+### fs.writeSync(fd, data, offset, length, [position])
+* `fd` *FileDescriptor* The file descriptor returned from `openSync()`.
+* `data` *string or Buffer* The data to write to 'fd'.
+* `offset` *long* The position in 'data' from which to start writing.
+* `length` *long* The number of bytes to write to 'fd' from 'data'.
+* `position` *long* The offset from the beginning of the file where
+ 'data' should be written. The parameter is optional; the default value is 0.
+* Returns: the number of bytes actually written (this may be different from 'length').
Write bytes to an opened file.
-`fd` is the file descriptor returned from `openSync()`.
-
-`data` is either a string or buffer to write.
-
-`offset` is the position in `data` to start writing from.
-
-`length` is the number of bytes to write from `data`.
-
-`position` is the offset from the beginning of the file where `data` should be
-written. Default is 0.
-
-Returns the number of bytes actually written (this may be different from `length`).
-
-### FS.readSync
-`number readSync(object fd, buffer data, number offset, number length, number position);`
+### fs.readSync(fd, data, offset, length, [position])
+* `fd` *FileDescriptor* The file descriptor returned from 'openSync()'.
+* `data` *Buffer* The buffer into which the data will be read.
+* `offset` *long* The offset in 'data' at which to start writing.
+* `length` *long* The number of bytes to read.
+* `position` *long* The position in the file from which to start reading.
+* Returns: the number of bytes actually read. This may be different from
+'length' if there was a read error or if the file had no more data left to read.
Read bytes from a file.
-`fd` is the file descriptor returned from `openSync()`.
-
-`data` is a buffer where the data will be read into.
-
-`offset` is the offset in `data` to start writing at.
-
-`length` is the number of bytes to read.
-
-`position` is the position in the file to start reading from.
-
-Returns the number of bytes actually read. This may be different from `length`
-if there was a read error or if the file had no more data left to read.
-
-### FS.truncateSync
-`void truncateSync(string path, number length);`
+### fs.truncateSync(path, length)
+* `path` *string* The name and path of the file.
+* `length` *long* The new length of the file.
Truncate a file. If the length passed in is shorter than the existing file
-length then the trailing file data will be lost.
-
-`path` is the name of the file.
+length, then the trailing file data will be lost.
-`length` is the new length of the file.
+### fs.mkdirSync(path)
+* `path` *string* The name and path of the directory.
-### FS.mkdirSync
-`void mkdirSync(string path)`
+Create a directory. There is no effect if the directory already exists.
-Create a directory. If the directory already exists there is no effect.
-
-`path` is the name of the directory.
-
-### FS.readdirSync
-`string[] readdirSync(string path);`
+### fs.readdirSync(path)
+* `path` *string* The name and path of the directory to read.
+* Returns: an array of filenames and directories found in 'path'.
Read the contents of a directory.
-`path` directory path to read.
-
-Returns an array of filenames and directories found in `path`.
-
-### FS.statSync
-`Stat statSync(string path);`
+### fs.statSync(path)
+* `path` *string* The name and path of the file or directory.
+* Returns: a 'Stat' object for the file or directory or undefined if the
+file or directory does not exist.
Get stats about a file or directory.
-`path` name of file or directory.
-
-Returns a `Stat` object for that file or directory or undefined if file or directory does not exist.
-
-### FS.writeFileSync
-`void writeFileSync(string file, [string|buffer] data);`
+### writeFileSync(file, data)
+* `file` *string* The name of the file to which to write.
+* `data` *string or Buffer* The data to write into the file.
Open and write data to a file. This will replace the file if it already exists.
-`file` is the name of the file to write to.
+Stat API
+--------
+
+### stat.isFile()
+* Returns: true if the file descriptor is a file.
-`data` is the bytes to write into the file.
+### stat.isDirectory()
+* Returns: true if the file descriptor is a directory.
Sample Apps
-----------
diff --git a/docs/gfx.md b/docs/gfx.md
index b5812ef..d772636 100644
--- a/docs/gfx.md
+++ b/docs/gfx.md
@@ -3,118 +3,155 @@ ZJS API for GFX
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: GFX](#gfx-api)
+ * [gfx.init(screen_width, screen_height, init_screen, draw, [this])](#gfxinitscreen_width-screen_height-init_screen-draw-this)
+* [Class: GFXContext](#gfxcontext-api)
+ * [gfxcontext.fillRect(x_coord, y_coord, width, height, color)](#gfxcontextfillrectx_coord-y_coord-width-height-color)
+ * [gfxcontext.drawPixel(x_coord, y_coord, color)](#gfxcontextdrawpixelx_coord-y_coord-color)
+ * [gfxcontext.drawLine(x0_coord, y0_coord, x1_coord, y1_coord, color, [size])](#gfxcontextdrawlinex0_coord-y0_coord-x1_coord-y1_coord-color-size)
+ * [gfxcontext.drawVLine(x_coord, y_coord, height, color, [size])](#gfxcontextdrawvlinex_coord-y_coord-height-color-size)
+ * [gfxcontext.drawHLine(x_coord, y_coord, width, color, [size])](#gfxcontextdrawhlinex_coord-y_coord-width-color-size)
+ * [gfxcontext.drawRect(x_coord, y_coord, width, height, color, [size])](#gfxcontextdrawrectx_coord-y_coord-width-height-color-size)
+ * [gfxcontext.drawChar(x_coord, y_coord, char, color, [size])](#gfxcontextdrawcharx_coord-y_coord-char-color-size)
+ * [gfxcontext.drawString(x_coord, y_coord, str, color, [size])](#gfxcontextdrawstringx_coord-y_coord-str-color-size)
* [Sample Apps](#sample-apps)
Introduction
------------
-The GFX module provides a generic way to create pixel buffers, which can then
+The GFX module provides a generic way to create pixel buffers that can
be displayed on a display of some kind. A JavaScript method for initializing
-the screen, and drawing a data buffer are required to use it.
+the screen and drawing a data buffer are required to use it.
See module/ST7735.js and samples/SPI_Screen.js for an example.
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-
-```javascript
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a GFX object
// var gfx = require('gfx');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface GFX {
- GFXContext init(screen width, screen height, init screen function,
- draw function, optional this);
-};
-
-[NoInterfaceObject]
+ GFXContext init(long screen_width, long screen_height, InitCallback init_screen,
+ DrawingCallback draw, optional this this_object);
+};<p>
interface GFXContext {
- fillRect(number x coord, number y coord, number width, number height,
- char array color);
- drawPixel(number x coord, number y coord, char array color);
- drawLine(number x0 coord, number y0 coord, number x1 coord,
- number y1 coord, char array color, optional number size);
- drawVLine(number x coord, number y coord, number height, char array color,
- optional number size);
- drawHLine(number x coord, number y coord, number width, char array color,
- optional number size);
- drawRect(number x coord, number y coord, number width, number height,
- char array color, optional number size);
- drawChar(number x coord, number y coord, character char, char array color,
- optional number size);
- drawString(number x coord, number y coord, string str, char array color,
- optional number size);
-};
-```
-
-API Documentation
------------------
-### GFX.init
-
-`GFXContext init(screen width, screen height, init screen function, draw function,
- optional this);`
+ void fillRect(long x_coord, long y_coord, long width, long height,
+ sequence < byte > color);
+ void drawPixel(long x_coord, long y_coord, sequence < byte > color);
+ void drawLine(long x0_coord, long y0_coord, long x1_coord,
+ long y1_coord, sequence < byte > color, optional long size);
+ void drawVLine(long x_coord, long y_coord, long height, sequence < byte > color,
+ optional long size);
+ void drawHLine(long x_coord, long y_coord, long width, sequence < byte > color,
+ optional long size);
+ void drawRect(long x_coord, long y_coord, long width, long height,
+ sequence < byte > color, optional long size);
+ void drawChar(long x_coord, long y_coord, byte char, sequence < byte > color,
+ optional long size);
+ void drawString(long x_coord, long y_coord, string str, sequence < byte > color,
+ optional long size);
+};<p>callback InitCallback = void (any... params);
+callback DrawingCallback = void (any... params);
+</pre>
+</details>
+
+GFX API
+-------
+### gfx.init(screen_width, screen_height, init_screen, draw, this)
+* `screen_width` *long* Width of the screen.
+* `screen_height` *long* Height of the screen.
+* `init_screen` *InitCallback*
+* `draw` *DrawingCallback*
+* `this` *object*
Initializes the GFX module with the screen size, an init function, and a draw
callback. A 'this' object can also be provided if needed.
-### GFXContext.fillRect
-
-`void fillRect(number x coord, number y coord, number width, number height,
- char array color);`
+GFXContext API
+--------------
+### gfxcontext.fillRect(x_coord, y_coord, width, height, color)
+* `x_coord` *long*
+* `y_coord` *long*
+* `width` *long*
+* `height` *long*
+* `color` *byte array*
Draws a solid rectangle of the given color at the coordinates provided.
-### GFXContext.drawPixel
-
-`void drawPixel(number x coord, number y coord, char array color);`
+### gfxcontext.drawPixel(x_coord, y_coord, color)
+* `x_coord` *long*
+* `y_coord` *long*
+* `color` *byte array*
Draws a pixel of the given color at the coordinates provided.
-### GFXContext.drawLine
+### gfxcontext.drawLine(x0_coord, y0_coord, x1_coord, y1_coord, color, [size])
+* `x0_coord` *long*
+* `y0_coord` *long*
+* `x1_coord` *long*
+* `y1_coord` *long*
+* `color` *byte array*
+* `size` *long* Optional.
-`void drawLine(number x0 coord, number y0 coord, number x1 coord,
- number y1 coord, char array color, optional number size);`
Draws a line of the given color at the coordinates provided. The optional
size number controls how thick the line is.
-### GFXContext.drawVLine
+### gfxcontext.drawVLine(x_coord, y_coord, height, color, [size])
+* `x_coord` *long*
+* `y_coord` *long*
+* `height` *long*
+* `color` *byte array*
+* `size` *long* Optional.
-`void drawVLine(number x coord, number y coord, number height, char array color,
- optional number size);`
Draws a vertical line of the given color at the coordinates provided. The
optional size number controls how thick the line is.
-### GFXContext.drawHLine
+### gfxcontext.drawHLine(x_coord, y_coord, width, color, [size])
+* `x_coord` *long*
+* `y_coord` *long*
+* `width` *long*
+* `color` *byte array*
+* `size` *long* Optional.
-`void drawHLine(number x coord, number y coord, number width, char array color,
- optional number size);`
Draws a horizontal line of the given color at the coordinates provided. The
optional size number controls how thick the line is.
-### GFXContext.drawRect
+### gfxcontext.drawRect(x_coord, y_coord, width, height, color, [size])
+* `x_coord` *long*
+* `y_coord` *long*
+* `width` *long*
+* `height` *long*
+* `color` *byte array*
+* `size` *long* Optional.
-`void drawRect(number x coord, number y coord, number width, number height,
- char array color, optional number size);`
Draws a hollow rectangle of the given color at the coordinates provided. The
optional size number controls how thick the line is.
-### GFXContext.drawChar
+### gfxcontext.drawChar(x_coord, y_coord, char, color, [size])
+* `x_coord` *long*
+* `y_coord` *long*
+* `char` *byte*
+* `color` *byte array*
+* `size` *long* Optional.
-`void drawChar(number x coord, number y coord, character char, char array color,
- optional number size);`
Draw a character at the coordinates given. The optional size number sets how
large the character is.
-### GFXContext.drawString
+### gfxcontext.drawString(x_coord, y_coord, str, color, [size])
+* `x_coord` *long*
+* `y_coord` *long*
+* `str` *string*
+* `color` *byte array*
+* `size` *long* Optional.
-`void drawString(number x coord, number y coord, string str, char array color,
- optional number size);`
Draw a string at the coordinates given. The optional size number sets how
large the character is.
diff --git a/docs/gpio.md b/docs/gpio.md
index 19277a8..5e9d976 100644
--- a/docs/gpio.md
+++ b/docs/gpio.md
@@ -3,7 +3,13 @@ ZJS API for General Purpose I/O (GPIO)
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class GPIO](#gpio-api)
+ * [GPIO.open(init)](#gpioopeninit)
+* [Class GPIOPin](#gpiopin-api)
+ * [pin.read()](#pinread)
+ * [pin.write()](#pinwritevalue)
+ * [pin.close()](#pinclose)
+ * [pin.onchange](#pinonchange)
* [Sample Apps](#sample-apps)
Introduction
@@ -17,108 +23,96 @@ but both that and ZJS are under a lot of change at the moment.
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+specific API functions. We have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a GPIO object
// var gpio = require('gpio');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface GPIO {
- GPIOPin open(number or string or GPIOInit init);
-};
-
+ GPIOPin open( (long or string or GPIOInit) init);
+};<p>
dictionary GPIOInit {
- number or string pin;
+ (long or string) pin;
boolean activeLow = false;
- string mode = "out"; // in, out
- string edge = "none"; // none, rising, falling, any
- string state = "none"; // none, up, down
-};
-
-[NoInterfaceObject]
-interface GPIOPin {
- number read();
- void write(number value);
+ GPIOMode mode = "out";
+ GPIOEdge edge = "none";
+ GPIOState state = "none";
+};<p>interface GPIOPin {
+ long read();
+ void write(long value);
void close();
attribute ChangeCallback onchange;
-};
-
-callback ChangeCallback = void (GPIOEvent);
-
-dictionary GPIOEvent {
- number value;
-}
-```
-
-API Documentation
------------------
-### GPIO.open
-
-`GPIOPin open(number or string or GPIOInit init);`
-
-If the argument is a number, it is a pin number. If it is a string, it is a
-pin name. Otherwise, it must be a GPIOInit object.
-
-The `init` object lets you set the pin number or name with the `pin` property.
+};<p>callback ChangeCallback = void (GPIOEvent event);<p>dictionary GPIOEvent {
+ long value;
+};<p>enum GPIOMode { "out", "in" };
+enum GPIOEdge { "none", "rising", "falling", "any" };
+enum GPIOState { "none", "up", "down" };</pre>
+</details>
+
+GPIO API
+--------
+### gpio.open(init)
+* `init` *long or string or GPIOInit* If the argument is a number, it is a pin number. If it is a
+string, it is a pin name. Otherwise, it must be a GPIOInit object.
+* Returns: a GPIOPin object that can be used to read or write the pin.
If the pin number or name is valid for the given board, the call will succeed.
You can use a pin name like "GPIO_0.10" where "GPIO_0" is the name of a Zephyr
gpio port device for your board and 10 is the pin number. This will work on any
board as long as you find the right values in Zephyr documentation. But for
-boards with specific ZJS support, you can use friendly names. Currently this
+boards with specific ZJS support, you can use friendly names. Currently, this
means Arduino 101 and FRDM-K64F. For the A101, you can use numbers 0-13 or
strings "IO0" through "IO13", as well as "LED0" through "LED2". For K64F, you
can use numbers 0-15 or strings "D0" through "D15", as well as "LEDR", "LEDG",
and "LEDB" for the RGB LED, and "SW2" and "SW3" for onboard switches.
-The other values are optional. The `activeLow` setting determines whether
-high (default) or low means active. When you read or write a boolean value,
-true means 'active' and false means 'inactive'.
+The GPIOInit object can take a string or number as the pin argument,
+and all of the rest of the fields are optional. The `activeLow`
+setting determines whether high (default) or low means active. When
+you read or write a boolean value, true means 'active' and false means
+'inactive'.
The `mode` value determines whether the pin is an input ('in') or output
-('out', default).
+('out').
The `edge` value is for input pins and tells whether the `onchange` callback
will be called on the rising edge of the signal, falling edge, or both.
-The `state` value is to enable an internal pullup or pulldown resistor. This
-would be used for inputs to provide a default (high or low) when the input is
-floating (not being intentionally driven to a particular value).
+The `state` value is useful when the architecture has an internal
+pullup or pulldown resistor. This would be used for inputs to provide
+a default (high or low) when the input is floating (not being
+intentionally driven to a particular value).
*NOTE: When we last checked, Zephyr did not use this state setting, at least for
-Arduino 101. Perhaps there is no hardware support, but in any case it didn't
+Arduino 101. Perhaps there is no hardware support, but in any case, it didn't
work. You can always provide an external resistor for this purpose instead.*
-The function returns a GPIOPin object that can be used to read or write the pin.
-
-### GPIOPin.read
-
-`number read();`
+GPIOPin API
+-----------
+### pin.read()
+* Returns: the current reading from the pin.
-Returns the current reading from the pin. This is a synchronous function because
-it should be nearly instantaneous on the devices we've tested with so far. The
-value will be 1 if the pin is active (high by default, low for a pin configured
+This is a synchronous function, because it is nearly
+instantaneous on the devices we've tested with so far. The value will
+be 1 if the pin is active (high by default, low for a pin configured
active low), 0 if inactive.
-### GPIOPin.write
-
-`void write(number value);`
-
-Pass 1 for `value` to make an output pin active (high by default, low for a pin
-configured active low), 0 to make it inactive.
-
-### GPIOPin.close
+### pin.write(value)
+* `value` *long* Pass 1 for `value` to make an output pin active
+(high by default, low for a pin configured active low), 0 to make it inactive.
-`void close();`
+### pin.close()
Free up resources associated with the pin. The onchange function for this pin
will no longer be called, and the object should not be used for reading and
writing anymore.
-### GPIOPin.onchange
+### pin.onchange
-`attribute ChangeCallback onchange;`
+* `onchange` *ChangeCallback*
Set this attribute to a function that will receive events whenever the pin
changes according to the edge condition specified at pin initialization. The
diff --git a/docs/grove_lcd.md b/docs/grove_lcd.md
index 24e489d..ed7c611 100644
--- a/docs/grove_lcd.md
+++ b/docs/grove_lcd.md
@@ -3,53 +3,58 @@ ZJS API for Grove LCD
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [GroveLCD API](#grovelcd-api)
+ * [grove_lcd.init()](#grove_lcdinit)
+* [GroveLCDDevice API](#grovelcddevice-api)
+ * [groveLCDDevice.print(string text)](#grovelcddeviceprinttext)
+ * [groveLCDDevice.clear()](#grovelcddeviceclear)
+ * [groveLCDDevice.setCursorPos(col, row)](#grovelcddevicesetcursorposcol-row)
+ * [groveLCDDevice.selectColor(index)](#grovelcddeviceselectcolorindex)
+ * [groveLCDDevice.setColor(r, g, b)](#grovelcddevicesetcolorr-g-b)
+ * [groveLCDDevice.setFunction(config)](#grovelcddevicesetfunctionconfig)
+ * [groveLCDDevice.getFunction()](#grovelcddevicegetfunction)
+ * [groveLCDDevice.setDisplayState(config)](#grovelcddevicesetdisplaystateconfig)
+ * [GroveLCDDevice.getDisplayState()](#grovelcddevicegetdisplaystate)
+
* [Sample Apps](#sample-apps)
Introduction
------------
The Grove LCD API is the JavaScript version of the Zephyr API that supports the
Grove LCD. It works over I2C to allow user to send text to the LCD screen
-and also configure LCD to different RGB backlight colors.
+and also configure the LCD to different RGB backlight colors.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
-// require returns a GroveLCD object
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>// require returns a GroveLCD object
// var grove_lcd = require('grove_lcd');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface GroveLCD {
GroveLCDDevice init();
- unsigned long GLCD_FS_8BIT_MODE;
- unsigned long GLCD_FS_ROWS_2;
- unsigned long GLCD_FS_ROWS_1;
- unsigned long GLCD_FS_DOT_SIZE_BIG;
- unsigned long GLCD_FS_DOT_SIZE_LITTLE;
-
- unsigned long GLCD_DS_DISPLAY_ON;
- unsigned long GLCD_DS_DISPLAY_OFF;
- unsigned long GLCD_DS_CURSOR_ON;
- unsigned long GLCD_DS_CURSOR_OFF;
- unsigned long GLCD_DS_BLINK_ON;
- unsigned long GLCD_DS_BLINK_OFF;
-
- unsigned long GLCD_IS_SHIFT_INCREMENT;
- unsigned long GLCD_IS_SHIFT_DECREMENT;
- unsigned long GLCD_IS_ENTRY_LEFT;
- unsigned long GLCD_IS_ENTRY_RIGHT;
-
- unsigned long GROVE_RGB_WHITE;
- unsigned long GROVE_RGB_RED;
- unsigned long GROVE_RGB_GREEN;
- unsigned long GROVE_RGB_BLUE;
-};
-
-[NoInterfaceObject]
-interface GroveLCDDevice {
+ attribute unsigned long GLCD_FS_8BIT_MODE;
+ attribute unsigned long GLCD_FS_ROWS_2;
+ attribute unsigned long GLCD_FS_ROWS_1;
+ attribute unsigned long GLCD_FS_DOT_SIZE_BIG;
+ attribute unsigned long GLCD_FS_DOT_SIZE_LITTLE;<p>
+ attribute unsigned long GLCD_DS_DISPLAY_ON;
+ attribute unsigned long GLCD_DS_DISPLAY_OFF;
+ attribute unsigned long GLCD_DS_CURSOR_ON;
+ attribute unsigned long GLCD_DS_CURSOR_OFF;
+ attribute unsigned long GLCD_DS_BLINK_ON;
+ attribute unsigned long GLCD_DS_BLINK_OFF;<p> attribute unsigned long GLCD_IS_SHIFT_INCREMENT;
+ attribute unsigned long GLCD_IS_SHIFT_DECREMENT;
+ attribute unsigned long GLCD_IS_ENTRY_LEFT;
+ attribute unsigned long GLCD_IS_ENTRY_RIGHT; <p> attribute unsigned long GROVE_RGB_WHITE;
+ attribute unsigned long GROVE_RGB_RED;
+ attribute unsigned long GROVE_RGB_GREEN;
+ attribute unsigned long GROVE_RGB_BLUE;
+};<p>interface GroveLCDDevice {
void print(string text);
void clear();
void setCursorPos(unsigned long col, unsigned long row);
@@ -59,50 +64,43 @@ interface GroveLCDDevice {
unsigned long getFunction();
void setDisplayState(unsigned long config);
unsigned long getDisplayState();
-};
-```
-
-API Documentation
------------------
-### GroveLCD.init
-
-`GroveLCDDevice init();`
-
-Initialize the Grove LCD panel
+};</pre>
+</details>
-*NOTE: Zephyr's Grove LCD API is on top of the I2C which is only accessible
-from the ARC side on the Arduino 101, so all the API in here will use the
-IPM to send commands over to the API, and all the API will be synchronous*
-
-The function returns a GroveLCDDevice object instance that can be used to
+GroveLCD API
+------------
+### grove_lcd.init()
+* Returns: a GroveLCDDevice object that can be used to
talk to the Grove LCD panel.
-### GroveLCDDevice.print
+Initializes the Grove LCD panel.
+
+*NOTE: Zephyr's Grove LCD API is on top of the I2C, which is only accessible
+from the ARC side on the Arduino 101, so all the APIs in here will use the
+IPM to send commands over to the API, and all this API will be synchronous.*
-`void print(string text);`
+GroveLCDDevice API
+------------------
+### groveLCDDevice.print(text)
+* `text` *string* The text to be printed.
Send text to the screen on the current line cursor is set to,
if the text is longer than number of characters it can fit on that line,
any additional characters will not wrap around and be dropped,
so a 16x2 LCD will have a maximum of 16 characters.
-### GroveLCDDevice.clear
-
-`void clear();`
+### groveLCDDevice.clear()
Clear the current display.
-### GroveLCDDevice.setCursorPos
-
-`void setCursorPos(unsigned long col, unsigned long row);`
+### groveLCDDevice.setCursorPos(col, row)
+* `col` *unsigned long* The column for the cursor to be moved to (0-15).
+* `row` *unsigned long* The row the column should be moved to (0 or 1).
-Set text cursor position for next additions.
-The `col` is the column for the cursor to be moved to (0-15).
-The `row` is the row it should be moved to (0 or 1).
+Set text cursor position for the next print.
-### GroveLCDDevice.selectColor
-
-`void selectColor(unsigned long index);`
+### groveLCDDevice.selectColor(index)
+* `index` *unsigned long* The color selection, as defined, below.
Set LCD background to a predfined color.
@@ -116,25 +114,21 @@ GroveLCD.GROVE_RGB_GREEN
GroveLCD.GROVE_RGB_BLUE
-### GroveLCDDevice.setColor
-
-`void setColor(unsigned long r, unsigned long g, unsigned long b);`
-
-Set LCD background to custom RGB color value
+### groveLCDDevice.setColor(r, g, b)
+* `r` *unsigned long* The numeric value for the red color (max is 255).
+* `g` *unsigned long* The numeric value for the green color (max is 255).
+* `b` *unsigned long* The numeric value for the blue color (max is 255).
-The `r` is a numeric value for the red color (max is 255).
-The `g` is a numeric value for the green color (max is 255).
-The `b` is a numeric value for the blue color (max is 255).
+Set LCD background to custom RGB color value.
-### GroveLCDDevice.setFunction
-
-`void setFunction(unsigned long config);`
+### groveLCDDevice.setFunction(config)
+* `config` *unsigned long* The bit mask to change the display state, as described, below.
This function provides the user the ability to change the state
of the display, controlling things like the number of rows,
dot size, and text display quality.
-The `config` is bit mask of the following configurations:
+The `config` bit mask can take the following configurations:
GroveLCD.GLCD_FS_8BIT_MODE
@@ -146,15 +140,11 @@ GroveLCD.GLCD_FS_DOT_SIZE_BIG
GroveLCD.GLCD_FS_DOT_SIZE_LITTLE
-### GroveLCDDevice.getFunction
+### groveLCDDevice.getFunction()
+*Returns: the function-features set associated with the device.
-`unsigned long getFunction();`
-
-Return the function features set associated with the device.
-
-### GroveLCDDevice.setDisplayState
-
-`void setDisplayState(unsigned long config);`
+### groveLCDDevice.setDisplayState(config)
+* `config` *unsigned long* The bit mask to change the display state, as described, below.
This function provides the user the ability to change the state
of the display, controlling things like powering on or off
@@ -175,11 +165,8 @@ GroveLCD.GLCD_DS_BLINK_ON
GroveLCD.GLCD_DS_BLINK_OFF
-### GroveLCDDevice.getDisplayState
-
-`unsigned long getDisplayState();`
-
-Return the display feature set associated with the device.
+### GroveLCDDevice.getDisplayState()
+* Returns: the display-feature set associated with the device.
Sample Apps
-----------
diff --git a/docs/i2c.md b/docs/i2c.md
index 7849e31..c60c653 100644
--- a/docs/i2c.md
+++ b/docs/i2c.md
@@ -3,7 +3,12 @@ ZJS API for I2C
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [I2C API](#i2c-api)
+ * [i2c.open(init)](#i2copeninit)
+* [I2CBus API](#i2cbus-api)
+ * [i2cBus.write(device, data)](#i2cbuswritedevice-data)
+ * [i2cBus.read(device, size, registerAddress)](#i2cbusreaddevice-size-registeraddress)
+ * [I2CBus.burstRead(device, size, registerAddress)](#i2cbusburstreaddevice-size-registeraddress)
* [Sample Apps](#sample-apps)
Introduction
@@ -14,60 +19,62 @@ and SCL. SDA is the data signal and SCL is the clock signal.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>
// require returns a I2C object
// var i2c = require('i2c');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface I2C {
I2CBus open(I2CInit init);
-};
-
+};<p>
dictionary I2CInit {
octet bus;
I2CBusSpeed speed;
-};
-
-[NoInterfaceObject]
+};<p>[ExternalInterface=(Buffer)]
interface I2CBus {
// has all the properties of I2CInit as read-only attributes
- write(octet device, Buffer data);
- read(octet device, unsigned int size, octet registerAddress);
- burstRead(octet device, unsigned int size, octet registerAddress);
-};
-```
-
-API Documentation
------------------
-### I2C.open
-
-`I2CBus open(I2CInit init);`
-
-The `init` object lets you set the I2C bus you wish to use and the speed you
-want to operate at. Speed options are 10, 100, 400, 1000, and 34000. Speed is
+ void write(octet device, Buffer data);
+ void read(octet device, unsigned long size, octet registerAddress);
+ void burstRead(octet device, unsigned long size, octet registerAddress);
+};<p>typedef long I2CBusSpeed;
+</pre>
+</details>
+
+I2C API
+-------
+### i2c.open(init)
+* `init` *I2CInit* Lets you set the I2C bus you wish to use and the speed you
+want to operate at. Speed options are 10, 100, 400, 1000, and 34000. Speed is
measured in kbs.
+* Returns: an I2CBus object.
-### I2CBus.write
-
-`void write(octet device, Buffer data);`
+I2CBus API
+----------
+### i2cBus.write(device, data)
+* `device` *octet* The device address.
+* `data` *Buffer* The data to be written.
Writes the data to the given device address. The first byte of data typically
contains the register you want to write the data to. This will vary from device
to device.
-### I2CBus.read
-
-`Buffer read(octet device, unsigned int size, octet registerAddress);`
+### i2cBus.read(device, size, registerAddress)
+* `device` *octet* The device address.
+* `size` *unsigned long* The number of bytes of data to read.
+* `registerAddress` *octet* The register on the device from which to read.
Reads 'size' bytes of data from the device at the registerAddress. The default
value of registerAdress is 0x00;
-### I2CBus.burstRead
-
-`Buffer burstRead(octet device, unsigned int size, octet registerAddress);`
+### I2CBus.burstRead(device, size, registerAddress)
+* `device` *octet* The device address.
+* `size` *long* The number of bytes of data to read.
+* `registerAddress` *octet* The number of the starting address from which to read.
Reads 'size' bytes of data from the device across multiple addresses starting
at the registerAddress. The default value of registerAdress is 0x00;
diff --git a/docs/mathstubs.md b/docs/mathstubs.md
index 6d27a3a..88bd1c6 100644
--- a/docs/mathstubs.md
+++ b/docs/mathstubs.md
@@ -3,12 +3,13 @@ ZJS API for MathStubs
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Mathstubs API](#mathstubs-api)
+ * [random()](#mathstubsrandom)
* [Sample Apps](#sample-apps)
Introduction
------------
-"MathStubs" module implements a subset of the Math libary's functions such
+The "MathStubs" module implements a subset of the Math library's functions such
as random(). This module is served as a replacement for the JerryScript's Math
libary when you only need certain math functions without the need to import
Math so your application can be smaller, since enabling the whole Math
@@ -19,18 +20,23 @@ round(), floor(), etc.
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+specific API functions. We have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
-double MathStubs.random();
-```
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>// require returns a MathStubs object
+// var mathStubs = require('mathstubs');
+[ReturnFromRequire]
+interface MathStubs {
+ double random();
+};
+</pre>
+</details>
-API Documentation
+Mathstubs API
-----------------
-### random
-`double random();`
-
-Returns a floating-point, pseudo-random number between 0 (inclusive)and 1 (exclusive).
+### mathStubs.random()
+* Returns: a floating-point, pseudo-random number between 0 (inclusive) and 1 (exclusive).
Sample Apps
-----------
diff --git a/docs/net-config.md b/docs/net-config.md
index 752438a..6792d03 100644
--- a/docs/net-config.md
+++ b/docs/net-config.md
@@ -3,8 +3,12 @@ ZJS API for Network Configuration
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
-* [Sample Apps](#sample-apps)
+* [NetConfig API](#netconfig-api)
+ * [Event: 'netup'](#event-netup)
+ * [Event: 'netdown'](#event-netdown)
+ * [net_cfg.setStaticIP(ip)](#net_cfgsetstaticipip)
+ * [net_cfg.dhcp(callback)](#net_cfgdhcpcallback)
+ * [net_cfg.setBleAddress(address)](#net_cfgsetbleaddressaddress)
Introduction
------------
@@ -19,26 +23,23 @@ static IP addresses of 192.0.2.1 and 2001:db8::1.
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+specific API functions. We have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a Net object
-// var net_cfg = require('netconfig');
-
+// var net_cfg = require('netconfig');<p>[ReturnFromRequire,ExternalInterface=(EventEmitter)]
interface NetConfig: EventEmitter {
- // set a static IP
- Boolean setStaticIP(String ip);
- // start DHCP
+ boolean setStaticIP(string ip);
void dhcp(DHCPCallback callback);
- // set the BLE MAC address
- void setBleAddress(String address);
-};
-
-callback DHCPCallback = void (String address, String subnet, String gateway);
-```
+ void setBleAddress(string address);
+};<p>callback DHCPCallback = void (string address, string subnet, string gateway);
+</pre>
+</details>
-API Documentation
------------------
+NetConfig API
+-------------
NetConfig is an [EventEmitter](./events.md) with the following events:
### Event: 'netup'
@@ -51,35 +52,30 @@ wait for a BLE connection before issuing any socket connections.
Emitted when the networking interface goes offline.
-### NetConfig.setStaticIP
-`Boolean setStaticIP(String ip)`
+### net_cfg.setStaticIP(ip)
+* `ip` *string* This should be either an IPv4 or IPv6 string.
+* Returns: true if the IP was successfully set and false if there was a problem setting the IP.
Set the device to use a static IP address.
-`ip` should be either an IPv4 or IPv6 string.
-
-This returns a true if the IP was successfully set. It will return false if
-there was a problem setting that IP. An error will be returned if there was
+An error will be returned if there was
a misconfiguration, e.g. setting an IPv6 address when IPv6 was not built.
-### NetConfig.dhcp
-`void dhcp(DHCPCallback callback)`
+### net_cfg.dhcp(callback)
+* `callback` *DHCPCallback*
Start DHCP to obtain an IP address.
-`callback` should be a `DHCPCallback` type. This event listener will be called
-when DHCP has finished. The callback will contain 3 arguments: `address`,
+This `callback` event listener will be called when DHCP has
+finished. The callback will contain 3 arguments: `address`,
`subnet`, and `gateway`.
-### NetConfig.setBleAddress
-`void setBleAddress(string address);`
+### net_cfg.setBleAddress(address)
+* `address` *string* The MAC address string in the format `XX:XX:XX:XX:XX:XX`, where each character is in HEX format (0-9, A-F).
Sets the device's BLE MAC address. This function is only defined on
Zephyr boards with BLE capabilities (e.g. Arduino 101).
-The `address` parameter should be a MAC address string in the format
-`XX:XX:XX:XX:XX:XX` where each character is in HEX format (0-9, A-F).
-
Note: This function has be called when the JS is initially run when
loaded. This means no calling from within any callback functions like
setTimeout(), setInterval() and promises. Also, If the image was built
diff --git a/docs/net.md b/docs/net.md
index 6b04654..3506789 100644
--- a/docs/net.md
+++ b/docs/net.md
@@ -3,120 +3,132 @@ ZJS API for Net
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: Net](#net-api)
+ * [net.createServer([onconnection])](#netcreateserveronconnection)
+ * [net.Socket()](#netsocket)
+ * [net.isIP(input)](#netisipinput)
+ * [Net.isIPv4(input)](#netisipv4input)
+ * [Net.isIPv6(input)](#netisipv6input)
+* [Class: Socket](#socket-api)
+ * [Event: 'close'](#event-close)
+ * [Event: 'connect'](#event-connect)
+ * [Event: 'data'](#event-data)
+ * [Event: 'error'](#event-error)
+ * [Event: 'timeout'](#event-timeout)
+ * [Socket.connect(options, [onconnect])](#socketconnectoptions-onconnect)
+ * [Socket.pause()](#socketpause)
+ * [Socket.resume()](#socketresume)
+ * [Socket.setTimeout(time, ontimeout)](#socketsettimeouttime-ontimeout)
+ * [Socket.write(buf, [writeDone])](#socketwritebuf-writedone)
+* [Class: Server](#server-api)
+ * [Event: 'close'](#event-close)
+ * [Event: 'connection'](#event-connection)
+ * [Event: 'error'](#event-error)
+ * [Event: 'listening'](#event-listening)
+ * [Server.address](#serveraddress)
+ * [Server.close()](#serverclose)
+ * [Server.getConnections(onconnection)](#servergetconnectionsonconnection)
+ * [Server.listen(options, [onlistening])](#serverlistenoptions-onlistening)
* [Sample Apps](#sample-apps)
Introduction
------------
-ZJS provides net (TCP) APIs which closely mimic the Node.js 'net' module. This
-module allows you to create a TCP/IP server or client.
+ZJS provides net (TCP) APIs that closely mimic the Node.js 'net'
+module, which allows you to create a TCP/IP server or client.
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-
-```javascript
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a Net object
// var net = require('net');
-
+[ReturnFromRequire,ExternalCallback=(ListenerCallback)]
interface Net {
- // create a server object
- Server createServer(callback onconnection);
- // Socket constructor, create a new Socket
+ Server createServer(optional ListenerCallback onconnection);
Socket Socket();
- Number isIP(input);
- Boolean isIPv4(input);
- Boolean isIPv6(input);
-};
-
+ long isIP(string input);
+ boolean isIPv4(string input);
+ boolean isIPv6(string input);
+};<p>
+[ExternalInterface=(EventEmitter),ExternalInterface=(Buffer),ExternalCallback=(ListenerCallback)]
interface Socket: EventEmitter {
// Socket methods
- void connect(Object options, callback onconnect);
+ void connect(object options, optional ListenerCallback onconnect);
void pause();
void resume();
- void setTimeout(Number timeout, callback ontimeout);
- void write(Buffer buf, callback writeDone);
+ void setTimeout(long timeout, ListenerCallback ontimeout);
+ void write(Buffer buf, optional ListenerCallback writeDone);
// Socket properties
- Number bufferSize; // Size of read buffer
- Number bytesRead; // Total bytes read for the socket
- Number bytesWritten; // Total bytes written for the socket
- String localAddress; // Sockets local IP
- Number localPort; // Sockets local port
- String remoteAddress; // Remote IP address
- String remoteFamily; // Remote IP family
- Number remotePort; // Remote port
-};
-
+ attribute long bufferSize; // Size of read buffer
+ attribute long bytesRead; // Total bytes read for the socket
+ attribute long bytesWritten; // Total bytes written for the socket
+ attribute string localAddress; // Sockets local IP
+ attribute long localPort; // Sockets local port
+ attribute string remoteAddress; // Remote IP address
+ attribute string remoteFamily; // Remote IP family
+ attribute long remotePort; // Remote port
+};<p>[ExternalInterface=(EventEmitter),ExternalCallback=(ListenerCallback)]
interface Server: EventEmitter {
// Server methods
AddressInfo address();
void close();
- void getConnections(callback);
- void listen(Object options, callback onlistening);
+ void getConnections(ListenerCallback onconnection);
+ void listen(object options, optional ListenerCallback onlistening);
// Server properties
- Boolean listening; // true if the server is listening
- Number maxConnections; // maximum number of connections
+ attribute boolean listening; // true if the server is listening
+ attribute long maxConnections; // maximum number of connections
+};<p>dictionary AddressOptions {
+ long port; // Port the client should connect to (required)
+ string host; // Host the client should connect to
+ string localAddress; // Local address to bind to
+ long localPort; // local port to bind to
+ long family; // Version of IP stack, deafults to 4
+};<p>dictionary AddressInfo {
+ long port; // Server port
+ string family; // IPv4 or IPv6
+ string address; // IP address for the server
};
+</pre>
+</details>
-dictionary AddressOptions {
- Number port; // Port the client should connect to (required)
- String host; // Host the client should connect to
- String localAddress; // Local address to bind to
- Number localPort; // local port to bind to
- Number family; // Version of IP stack, deafults to 4
-}
-
-dictionary AddressInfo {
- Number port; // Server port
- String family; // IPv4 or IPv6
- String address; // IP address for the server
-}
-```
-
-Net API Documentation
----------------------
+Net API
+-------
-### Net.createServer
-`Server createServer(callback onconnection)`
+### net.createServer([onconnection])
+* `onconnection` *callback* The (optional) callback function registered as the the event listener for the `connection` event.
+* Returns: a `Server` object.
Create a TCP server that can accept client connections.
-`onconnection` is an optional callback function that, if supplied, will be
-registered as the the event listener for the `connection` event.
-
-Returns a `Server` object.
+### net.Socket()
+* Returns: a new Socket object that can be used to connect to a remote TCP server.
-### Net.Socket
-`Socket Socket(void)`
+Socket constructor.
-Socket constructor. Calling `new Socket()` will return a new Socket object
-that can be used to connect to a remote TCP server.
-
-### Net.isIP
-`Number isIP(input)`
+### net.isIP(input)
+* `input` *string*
+* Returns: 4 if the input is an IPv4 address, 6 if the input is an IPv6 address,
+or 0 if the input is not an IP address.
Checks if the input is a valid IP address.
-Returns 4 if the input is an IPv4 address, 6 if the input is an IPv6 address,
-or 0 if the input is not an IP address.
-
-### Net.isIPv4
-`Boolean isIPv4(input)`
+### Net.isIPv4(input)
+* `input` *string*
+* Returns: true if input is IPv4, false otherwise.
Checks if input is an IPv4 address.
-Returns true if input is IPv4.
-
-### Net.isIPv6
-`Boolean isIPv6(input)`
+### Net.isIPv6(input)
+* `input` *string*
+* Returns: true if input is IPv6, false otherwise.
Checks if input is an IPv6 address.
-Returns true if input is IPv6.
-
-Socket API Documentation
-------------------------
+Socket API
+----------
Socket is an [EventEmitter](./events.md) with the following events:
@@ -143,46 +155,37 @@ Emitted when there was an error on the socket during read, write, or connect.
Emitted only when a timeout set with `setTimeout` expires.
-### Socket.connect
-`void connect(AddressOptions options, callback onconnect)`
+### Socket.connect(options, [onconnect])
+* `options` *AddressOptions* Describes the remote server being connected to.
+* `onconnect` *ListenerCallback* Optional callback added as the listener for the
+`connect` event.
Connect to a remote TCP server.
-`options` should describe the remote server your connecting to.
-
-`onconnect` is optional and, if specified, will be added as the listener for the
-`connect` event.
-
-### Socket.pause
-`void pause(void)`
+### Socket.pause()
Pause a socket from receiving data. `data` event will not be emitted until
-`resume` is called.
+`Socket.resume` is called.
-### Socket.resume
-`void resume(void)`
+### Socket.resume()
-Allow a socket to resume receiving data after a call to `pause`.
+Allow a socket to resume receiving data after a call to `Socket.pause`.
-### Socket.setTimeout
-`void setTimeout(Number time, callback ontimeout)`
+### Socket.setTimeout(time, ontimeout)
+* `time` *long*
+* `ontimeout` *ListenerCallback* Optional callback registered as a listener for the `timeout` event.
-Set a socket timeout. This will start a timer on the socket which will expire
-in `time` milliseconds if there has been no activity on the socket. The
-`ontimeout` parameter, if specified, will register a listener for the
-`timeout` event.
+Set a socket timeout. This will start a timer on the socket that will expire
+in `time` milliseconds if there has been no activity on the socket.
-### Socket.write
-`void write(Buffer buf, callback writeDone)`
+### Socket.write(buf, [writeDone])
+* `buf` *Buffer* `buf` Contains the data to be written.
+* `writeDone` *ListenerCallback* Optional function called once the data is written.
Send data on the socket.
-`buf` should contain the data you wish to send.
-
-`writeDone` is optional and will be called once the data is written.
-
-Server API Documentation
-------------------------
+Server API
+----------
Server is an [EventEmitter](./events.md) with the following events:
@@ -212,21 +215,20 @@ Emitted when the server has been bound, after calling `server.listen()`.
Returns an AddressInfo object for the server:
-### Server.close
-`void close(void)`
+### Server.close()
Signals the server to close. This will stop the server from accepting any new
connections but will keep any existing connections alive. Once all existing
connections have been closed the server will emit the `close` event.
-### Server.getConnections(callback)
-`void getConnections(callback)`
+### Server.getConnections(onconnection)
+* `onconnection` *ListenerCallback* Should be a function with `err` and `count` parameters.
-Get the number of connections to the server. The `callback` parameter should be
-a function with `err` and `count` parameters.
+Get the number of connections to the server.
-### Server.listen
-`void listen(Object options, callback onlistening)`
+### Server.listen(options, [onlistening])
+* `options` *object*
+* `onlistening` *ListenerCallback* Optional function added to the `listening` event.
Start listening for connections. The `options` object supports the following
properties:
@@ -238,9 +240,6 @@ properties:
}
```
-`onlistening` is optional and, if specified, will add a listener to the
-`listening` event.
-
Sample Apps
-----------
* [IPv6 Server sample](../samples/TCPEchoServ6.js)
diff --git a/docs/ocf.md b/docs/ocf.md
index 70c012a..6feab53 100644
--- a/docs/ocf.md
+++ b/docs/ocf.md
@@ -3,42 +3,53 @@ ZJS API for OCF
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [OCF Object](#the-ocf-object)
-* [OCF API Documentation](#ocf-api-documentation)
-* [OCF Server](#ocf-server)
-* [Server API Documentation](#server-api-documentation)
-* [Server Samples](#server-samples)
-* [OCF Client](#ocf-client)
-* [Client API Documentation](#client-api-documentation)
-* [Client Samples](#client-samples)
+* [Class: OCF](#ocf-api)
+ * [ocf.start()](#ocfstart)
+* [OCFServer-supported Events](#ocfserver-supported-events)
+* [Class: OCFServer](#ocfserver-api)
+ * [server.register(init)](#serverregisterinit)
+* [Class: Request](#request-api)
+ * [request.respond(data)](#requestresponddata)
+* [OCFClient-supported Events](#ocfclient-supported-events)
+* [Class: OCFClient](#ocfclient-api)
+ * [client.findResources(options, [listener])](#clientfindresourcesoptions-listener)
+ * [client.retrieve(deviceId, options)](#clientretrievedeviceid-options)
+ * [client.update(resource)](#clientupdateresource)
+ * [client.getPlatformInfo(deviceId)](#clientgetplatforminfodeviceid)
+ * [client.getDeviceInfo(deviceId)](#clientgetdeviceinfodeviceid)
+* [OCFServer Samples](#ocfserver-samples)
+* [OCFClient Samples](#ocfclient-samples)
Introduction
------------
ZJS provides OCF Server API's which allow communication using the OCF networking
protocol.
-Web IDL
--------
-This IDL provides an overview of the interfaces for OCF common, OCF Server and
-OCF Client; see below for documentation of specific API functions.
-
-The OCF Object
---------------
The OCF object is the top level object containing either OCF Server,
OCF Client, or both, as well as device and platform information.
-```javascript
+The OCF device and platform objects can be set up after requiring 'ocf'. An
+example of this can be found in [OCF Server sample](../samples/OcfServer.js).
+
+Web IDL
+-------
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>
// require returns an OCFObject
// var ocf = require('ocf');
-
+<p>[ReturnFromRequire]
interface OCFObject {
- Server server; // OCF server object
- Client client; // OCF client object
- Platform platform; // OCF platform info
- Device device // OCF device info
-};
-
-dictionary Platform {
+ attribute OCFServer server; // OCF server object
+ attribute OCFClient client; // OCF client object
+ attribute Platform platform; // OCF platform info
+ attribute Device device; // OCF device info
+ void start();
+};<p>dictionary Platform {
string id;
string osVersion;
string model;
@@ -48,40 +59,17 @@ dictionary Platform {
string platformVersion;
string firmwareVersion;
string supportURL;
-}
-
-dictionary Device {
+};<p>dictionary Device {
string uuid;
string name;
string dataModels;
string coreSpecVersion;
-}
-
-```
-The OCF device and platform objects can be set up after requiring 'ocf'. An
-example of this can be found in [OCF Server sample](../samples/OcfServer.js).
-The properties are registered to the system (and available during discovery)
-once either `OCFServer.registerResource()` or `OCFClient.findResources()`
-is called.
-
-OCF API Documentation
----------------------
-
-### OCFObject.start
-`void start(void)`
-
-Start the OCF stack (iotivity-constrained). This should be called after all
-resources have been registered. Any calls to `registerResource` after `start`
-will have no effect.
-
-OCF Server
-----------
-```javascript
-interface Server: EventEmitter {
+};<p>///////////////////////////////////////////
+// OCF Server
+///////////////////////////////////////////<p>[ExternalInterface=(EventEmitter)]
+interface OCFServer: EventEmitter {
Promise<OCFResource> register(ResourceInit init);
-};
-
-dictionary ResourceInit {
+};<p>dictionary ResourceInit {
string resourcePath; // OCF resource path
string[] resourceTypes; // List of resource types
string[] interfaces; // List of interfaces for resource types
@@ -90,24 +78,50 @@ dictionary ResourceInit {
boolean secure; // Is resource security enabled
boolean slow; // Is resource a slow reader
object properties; // Dictionary of resource properties
-};
-
-interface Resource {
+};<p>dictionary Resource {
string resourcePath; // Path for this resource
object properties; // Application specific resource properties
-};
-
-interface Request {
- OCFResource target; // Target/destination resource
- OCFResource source; // Source/origin resource
- object data; // resource representation
+};<p>interface Request {
+ attribute OCFResource target; // Target/destination resource
+ attribute OCFResource source; // Source/origin resource
+ attribute object data; // resource representation
Promise<void> respond(object data);
-};
-```
+};<p>///////////////////////////////////////////
+// OCF Client
+///////////////////////////////////////////<p>[ExternalInterface=(EventEmitter)]
+interface OCFClient: EventEmitter {
+ Promise<Resource> findResources(ClientOptions options, optional FoundListener listener);
+ Promise<Resource> retrieve(string deviceId, object options);
+ Promise<Resource> update(Resource resource);
+ Promise<Platform> getPlatformInfo(string deviceId);
+ Promise<Device> getDeviceInfo(string deviceId);
+};<p>dictionary ClientOptions {
+ string deviceId;
+ string resourceType;
+ string resourcePath;
+};<p>callback FoundListener = void (ClientResource resource);<p>dictionary ClientResource {
+ string deviceId;
+ string resourceType;
+ string resourcePath;
+};<p>typedef long OCFResource; /* may be some other type/object */
+</pre>
+</details>
+
+OCF API
+-------
+The properties are registered to the system (and available during discovery)
+once either `OCFServer.registerResource()` or `OCFClient.findResources()`
+is called.
+
+### ocf.start()
+
+Start the OCF stack (iotivity-constrained). This should be called after all
+resources have been registered. Any calls to `registerResource` after `start`
+will have no effect.
-Server API Documentation
-------------------------
-Server is an [EventEmitter](./events.md) with the following events:
+OCFServer-supported Events
+--------------------------
+An OCFServer is an [EventEmitter](./events.md) with the following events:
### Event: 'retrieve'
@@ -122,60 +136,28 @@ Emitted when a remote client retrieves this server's resource(s).
Emitted when a remote client updates this server's resource(s).
-### Server.register
-`Promise<OCFResource> register(ResourceInit init);`
+OCFServer API
+--------------
+### server.register(init)
+* `init` *ResourceInit* Contains the resource initialization information.
+* Returns: a promise which resolves to an `OCFResource`.
Register a new resource with the server.
-The `init` contains the resource initalization information.
-
-Returns a promise which resolves to an `OCFResource`.
-
-### Request.respond
-`Promise<void> respond(object data);`
-
-Respond to an OCF `retrieve` or `update` event.
-
-The `data` parameter should contain object property data for the resource. In
+Request API
+-----------
+### request.respond(data)
+* `data` *object* Should contain object property data for the resource. In
the case of an `onretrieve` event, `data` will be sent back to the client as
the retrieved property data.
+* Returns: a promise which resolves successfully if there was no network error
+from sending out the data.
-Returns a promise which resolves successfully if there was no network error
-sending out the data.
-
-Server Samples
---------------
-* [OCF Server sample](../samples/OcfServer.js)
-* [OCF Sensor Server](../samples/OcfSensorServer.js)
-
-OCF Client
-----------
-```javascript
-interface Client: EventEmitter {
- Promise<Resource> findResources(ClientOptions options, optional FoundListener listener);
- Promise<Resource> retrieve(string deviceId, object options);
- Promise<Resource> update(Resource resource);
- Promise<Platform> getPlatformInfo(string deviceId);
- Promise<Device> getDeviceInfo(string deviceId);
-};
-
-dictionary ClientOptions {
- string deviceId;
- string resourceType;
- string resourcePath;
-}
-
-interface Resource {
- string resourcePath; // Path for this resource
- object properties; // Application specific resource properties
-};
-
-callback FoundListener = void (ClientResource);
-```
+Respond to an OCF `retrieve` or `update` event.
-Client API Documentation
-------------------------
-Client is an [EventEmitter](./events.md) with the following events:
+OCFClient-supported Events
+--------------------------
+An OCFClient is an [EventEmitter](./events.md) with the following events:
### Event: 'devicefound'
@@ -201,68 +183,52 @@ Emitted when a resource is found during `findResources()`.
Emitted when a resource is updated.
-### Client.findResources
-`Promise<ClientResource> findResources(ClientOptions options, optional FoundListener listener);`
-
-Find remote resources matching `options` filter.
-
-The `options` parameter should contain a filter of resource options. Only
+OCFClient API
+-------------
+### client.findResources(options, [listener])
+* `options` *ClientOptions* Should contain a filter of resource options. Only
resources matching these options will be found.
-
-The `listener` parameter is an optional event listener callback. This
+* `listener` *FoundListener* An optional event-listener callback. This
callback will be called if a resource is found (`onfound` event).
+* Returns: a promise which resolves to a `ClientResource` containing the resource properties if a resource is found.
-Returns a promise which resolves with a `ClientResource` object if a resource
-was found.
-
-### Client.retrieve
-`Promise<Resource> retrieve(string deviceId, object options);`
-
-Retrieve (GET) a remote resource.
+Find remote resources matching `options` filter.
-The `deviceId` parameter is the device ID of the resource you are retrieving.
+### client.retrieve(deviceId, options)
+* `deviceId` *string* The device ID of the resource you are retrieving.
This ID must match a resource which has been found with `findResources()`.
+* `options` *object * Contains flag information for this GET request (e.g., `observable=true`).
-The `options` object properties contain flag information for this GET request
-e.g. `observable=true`.
-
-Returns a promise which resolves to a `ClientResource` containing the resource
-properties.
-
-### Client.update
-`Promise<Resource> update(Resource resource);`
-
-Update remote resource properties.
+Retrieve (GET) a remote resource.
-The `resource` parameter should contain a `deviceId` for the resource to
+### client.update(resource)
+* `resource` *Resource* Should contain a `deviceId` for the resource to
update. The `properties` parameter will be sent to the resource and updated.
-
-Returns a promise which resolves to a resource `Resource` containing the
+* Returns: a promise which resolves to a resource `Resource` containing the
updated properties.
-### Client.getPlatformInfo
-`Promise<Platform> getPlatformInfo(string deviceId);`
+Update remote resource properties.
+
+### client.getPlatformInfo(deviceId)
+* `deviceId` *string* The `deviceId` parameter should be the ID for a resource found with `findResources()`.
+* Returns: a promise which resolves to a `Platform` containing the platform
+information for the resource.
Get `Platform` information for a resource.
-The `deviceId` parameter should be the ID for a resource found with
-`findResources()`.
-
-Returns a promise which resolves to a `Platform` containing the platform
+### client.getDeviceInfo(deviceId)
+* `deviceId` *string* The ID for a resource found with `findResources()`.
+* Returns: a promise which resolves to a `Device` containing the device
information for the resource.
-### Client.getDeviceInfo
-`Promise<Device> getDeviceInfo(string deviceId);`
-
Get `Device` information for a resource.
-The `deviceId` parameter should be the ID for a resource found with
-`findResources()`.
-
-Returns a promise which resolves to a `Device` containing the device
-information for the resource.
+OCFServer Samples
+--------------
+* [OCF Server sample](../samples/OcfServer.js)
+* [OCF Sensor Server](../samples/OcfSensorServer.js)
-Client Samples
+OCFClient Samples
--------------
* [OCF Client sample](../samples/OcfClient.js)
* [OCF Sensor Client](../samples/OcfSensorClient.js)
diff --git a/docs/performance.md b/docs/performance.md
index 0981518..2f04972 100644
--- a/docs/performance.md
+++ b/docs/performance.md
@@ -3,46 +3,53 @@ ZJS API for Benchmarking
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Performance API](#performance-api)
+ * [performance.now()](#performancenow)
* [Sample Apps](#sample-apps)
Introduction
------------
-"Performance" module implements a subset of "High Resolution Time" specification
-from W3C, intended primarily for benchmarking purposes. The key point of this
-module is that it is very light-weight by implementing just one function
-(unlike for example Date object).
+
+The "Performance" module implements a subset of the "High Resolution Time"
+specification from W3C, intended primarily for benchmarking
+purposes. The key point of this module is that it is very light-weight
+by implementing just one function (unlike, for example, the Date object).
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-```javascript
-double now();
-```
+This IDL provides an overview of the interface; see below for documentation of
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
+// require returns a Performance object
+// var ble = require('performance');
+[ReturnFromRequire]
+interface Performance {
+ double now();
+};</pre>
+</details>
-API Documentation
------------------
-### now
-`now();
-`
+Performance API
+---------------
+### performance.now()
+* Returns: the current time in milliseconds, as a floating-point number.
-The module exposes just one function, `now()`. It returns current time in
-milliseconds, as a floating-point number, since an arbitrary point in
-time. It is thus not useful as an absolute value, but subtracting values
-from two calls will give a time duration between these two calls.
+The "time" returned from this function is the offset since an
+arbitrary point in time. It is thus not useful as an absolute value,
+but subtracting values from two calls will give a time duration
+between these two calls.
-As the value returned is floating point, it may have higher resolution
+As the value returned is a floating point value, it may have higher resolution
than a millisecond. However, the actual resolution depends on a platform
-and its configuration. For example, default Zephyr configuration for
+and its configuration. For example, the default Zephyr configuration for
many boards provides resolution of only ones or tens of milliseconds.
-The intended usage of this function is for benchmarking and other testing
+The intended use of this function is for benchmarking and other testing
and development needs.
-
Examples
--------
diff --git a/docs/pme.md b/docs/pme.md
index 04bd08a..148e950 100644
--- a/docs/pme.md
+++ b/docs/pme.md
@@ -3,18 +3,33 @@ ZJS API for Pattern Matching Engine (PME)
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: PME](#pme-api)
+ * [pme.begin()](#pmebegin)
+ * [pme.forget()](#pmeforget)
+ * [pme.configure(context, classificationMode, distanceMode, minInfluence, maxInfluence)](#pmeconfigurecontext-classificationmode-distancemode-mininfluence-maxinfluence)
+ * [pme.learn(pattern, category)](#pmelearnpattern-category)
+ * [pme.classify(pattern)](#pmeclassifypattern)
+ * [pme.readNeuron(id)](#pmereadneuronid)
+ * [pme.writeVector(pattern)](#pmewritevectorpattern)
+ * [pme.getCommittedCount()](#pmegetcommittedcount)
+ * [pme.getGlobalContext()](#pmegetglobalcontext)
+ * [pme.getClassifierMode()](#pmegetclassifiermode)
+ * [pme.setClassifierMode(mode)](#pmesetclassifiermodemode)
+ * [pme.getDistanceMode()](#pmegetdistancemode)
+ * [pme.setDistanceMode(mode)](#pmesetdistancemodemode)
+ * [pme.saveNeurons()](#pmesaveneurons)
+ * [pme.restoreNeurons(objects)](#pmerestoreneuronsobjects)
* [Sample Apps](#sample-apps)
Introduction
------------
-The Pattern Matching Engine API is the JavaScript version of the parallel data recognition engine with the following features:
+The Pattern Matching Engine API is the JavaScript version of the parallel data-recognition engine with the following features:
- 128 parallel Processing Elements (PE) each with
- 128 byte input vector
- 128 byte model memory
- 8-Bit Arithmetic Units
- - Two distance evaluation norms with 16-bit resolution:
+ - Two distance-evaluation norms with 16-bit resolution:
- L1 norm (Manhattan Distance)
- Lsup (Supremum) norm (Chebyshev Distance)
- Support for up to 32,768 Categories
@@ -30,194 +45,129 @@ The Pattern Matching Engine API is the JavaScript version of the parallel data r
Web IDL
-------
This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-
-```javascript
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a PME object
// var pme = require('pme');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface PME {
- begin();
- forget();
- configure(unsigned short context,
- unsigned short classificationMode,
- unsigned short distanceMode,
- unsigned short minInfluence,
- unsigned short maxInfluence);
- learn(number[] pattern, unsigned long category);
- unsigned long classify(number[] pattern);
+ void begin();
+ void forget();
+ void configure(unsigned short context,
+ unsigned short classificationMode,
+ unsigned short distanceMode,
+ unsigned short minInfluence,
+ unsigned short maxInfluence);
+ void learn(sequence < long > pattern, unsigned long category);
+ unsigned long classify(sequence < long > pattern);
Neuron readNeuron(unsigned long id);
- writeVector(number[] pattern);
+ void writeVector(sequence < long > pattern);
unsigned short getCommittedCount();
unsigned short getGlobalContext();
unsigned short getClassifierMode();
- setClassifierMode(unsigned short mode);
+ void setClassifierMode(unsigned short mode);
unsigned short getDistanceMode();
- setDistanceMode(unsigned short mode);
- Json[] saveNeurons();
- restoreNeurons(Json[] objects);
-
- unsigned short RBF_MODE; // RBF classification mode
- unsigned short KNN_MODE; // KNN classification mode
- unsigned short L1_DISTANCE; // L1 distance mode
- unsigned short LSUP_DISTANCE; // LSUP distance mode
- unsigned long NO_MATCH; // indicate a pattern could not be classified
- unsigned short MIN_CONTEXT; // minimum context value
- unsigned short MAX_CONTEXT; // maximum context value
- unsigned long MAX_VECTOR_SIZE; // Maximum pattern size (in bytes)
- unsigned long FIRST_NEURON_ID; // ID of first neuron in network
- unsigned long LAST_NEURON_ID; // ID of last neuron in network
- unsigned long MAX_NEURONS; // Number of neurons in the network
-};
-
-[NoInterfaceObject]
-interface Neuron {
+ void setDistanceMode(unsigned short mode);
+ sequence < Json > saveNeurons();
+ void restoreNeurons(sequence < Json > objects);
+<p>
+ attribute unsigned short RBF_MODE; // RBF classification mode
+ attribute unsigned short KNN_MODE; // KNN classification mode
+ attribute unsigned short L1_DISTANCE; // L1 distance mode
+ attribute unsigned short LSUP_DISTANCE; // LSUP distance mode
+ attribute unsigned long NO_MATCH; // indicates a pattern could not
+ // be classified
+ attribute unsigned short MIN_CONTEXT; // minimum context value
+ attribute unsigned short MAX_CONTEXT; // maximum context value
+ attribute unsigned long MAX_VECTOR_SIZE; // Maximum pattern size (in bytes)
+ attribute unsigned long FIRST_NEURON_ID; // ID of first neuron in network
+ attribute unsigned long LAST_NEURON_ID; // ID of last neuron in network
+ attribute unsigned long MAX_NEURONS; // Number of neurons in the network
+};<p>dictionary Neuron {
unsigned short category;
unsigned short context;
unsigned short AIF;
unsigned short minIF;
};
-```
-
-API Documentation
------------------
-### PME.begin
+</pre>
+</details>
-`void begin();`
+PME API
+-------
+### pme.begin()
Initialize the PME so it is ready for operation.
-### PME.forget
-
-`void forget();`
+### pme.forget()
Clear any data committed to the network, making the network ready to learn again.
-### PME.configure
-
-`configure(unsigned short context,
- unsigned short classificationMode,
- unsigned short distanceMode,
- unsigned short minInfluence,
- unsigned short maxInfluence);`
+### pme.configure(context, classificationMode, distanceMode, minInfluence, maxInfluence)
+* `context` *unsigned short* This value has a range between 1-127. A context value of 0 enables all neurons, with no regard to their context.
+* `classificationMode` *unsigned short* The classifying function to use. Valid values are: PME.RBF_MODE (default) or PME.KNN_MODE.
+* `distanceMode` *unsigned short* The distance function to use. Valid values are: PME.LSUP_DISTANCE or PME.L1_DISTANCE.
+* `minInfluence` *unsigned short* The minimum influence value used on the neuron.
+* `maxInfluence` *unsigned short* The maximum influence value used on the neuron.
Configure the engine with parameters used for training data.
-The `context` is valid context value range between 1-127. A context value of 0 enables all neurons, with no regard to their context.
-The `classificationMode` is the classifying function to use. Valid values are:
-
- - PME.RBF_MODE (default)
- - PME.KNN_MODE
-
-The `distanceMode` is the distance function to use. Valid values are:
-
- - PME.LSUP_DISTANCE
- - PME.L1_DISTANCE
-
-The `minIF` is the minimum influence value used on the neuron.
-The `maxIF` is the maximum influence value used on the neuron.
-
-### PME.learn
-
-`void learn(number[] pattern, unsigned long category);`
+### pme.learn(pattern, category)
+* `pattern` *array of bytes* An array of bytes up to 128 bytes in length.
+* `category` *unsigned long* Indicates to the PME to which category this training vector belongs; that is, if a future input has a sufficiently similar pattern, it will be classified as the same category as the passed-in pattern.
Takes a pattern and commits it to the network as training data for a given category.
-The `pattern` is an array of bytes, up to 128 bytes in length.
-The `category` indicates to the PME which category this training vector belongs to, that is, if a future input has a sufficiently similar pattern, it will be classified as the same category passed with this pattern.
-
-### PME.classify
-
-`unsigned long classify(number[] pattern);`
+### pme.classify(pattern)
+* `pattern` *array of bytes* An array of bytes up to 128 bytes in length.
+* Returns: `PME.NO_MATCH` if the input data did not match any of the trained categories. Otherwise, the trained category assigned by the network will be returned.
Takes a pattern and uses the committed neurons in the network to classify the pattern.
-The `pattern` is an array of bytes, up to 128 bytes in length.
-
-Returns `PME.NO_MATCH` if the input data did not match any of the trained categories. Otherwise, the trained category assigned by the network will be returned.
-
-### PME.readNeuron
-
-`Neuron readNeuron(unsigned long id);`
+### pme.readNeuron(id)
+* `id` *unsigned long* A value between 1-128 representing a specific neuron.
+* Returns: the `Neuron` object in which to write the neuron data.
Read a specific neuron by its ID.
-The `id` is value between 1-128 representing a specific neuron.
-
-Returns the `Neuron` object in which to write the neuron data.
-
-### PME.writeVector (KNN_MODE only)
-
-`void writeVector(number[] pattern);`
+### pme.writeVector(pattern)
+* `pattern` *array of bytes* An array of bytes up to 128 bytes in length.
(Should only be used in KNN_MODE.) Takes a pattern and uses the committed neurons in the network to classify the pattern.
-The `pattern` is an array of bytes, up to 128 bytes in length.
-
-### PME.getCommittedCount
-
-`unsigned short getCommittedCount();`
+### pme.getCommittedCount()
+*Returns: the number of comitted neurons in the network (a value between 0-128).
Gets the number of committed neurons in the network.
-Returns the number of comitted neurons in the network (a value between 0-128).
-
-### PME.getGlobalContext
-
-`unsigned short getGlobalContext();`
+### pme.getGlobalContext()
+* Returns: the contents of the Global Context Register (a value between 0-127).
Reads the Global Context Register.
-Returns the contents of the Global Context Register (a value between 0-127).
-
-### PME.getClassifierMode
-
-`unsigned short getClassifierMode();`
+### pme.getClassifierMode()
+* Returns: the classifying function being used. Possible values are: PME.RBF_MODE or PME.KNN_MODE.
Gets the classifying function being used by the network.
-Returns the the classifying function being used. Possible values are:
-
- - PME.RBF_MODE
- - PME.KNN_MODE
-
-### PME.setClassifierMode
-
-`void setClassifierMode(unsigned short mode);`
+### pme.setClassifierMode(mode)
+* `mode` *unsigned short* The classifying function to use. Valid values are: PME.RBF_MODE (default) or PME.KNN_MODE.
Sets the classifying function to be used by the network.
-The `mode` is the classifying function to use. Valid values are:
-
- - PME.RBF_MODE (default)
- - PME.KNN_MODE
-
-### PME.getDistanceMode
-
-`unsigned short getDistanceMode();`
+### pme.getDistanceMode()
+* Returns: the distance function being used. Possible values are: PME.LSUP_DISTANCE or PME.L1_DISTANCE.
Gets the distance function being used by the network.
-Returns the the distance function being used. Possible values are:
-
- - PME.LSUP_DISTANCE
- - PME.L1_DISTANCE
-
-### PME.setDistanceMode
-
-`void setDistanceMode(unsigned short mode);`
+### pme.setDistanceMode(mode)
+* `mode` *unsigned short* The distance function to use. Valid values are: PME.LSUP_DISTANCE or PME.L1_DISTANCE.
Sets the distance function to be used by the network.
-The `mode` is the distance function to use. Valid values are:
-
- - PME.LSUP_DISTANCE
- - PME.L1_DISTANCE
-
-### PME.saveNeurons
-
-`Json[] saveNeurons();`
+### pme.saveNeurons()
+* Returns: an array of JSON objects.
Export committed neuron data into an array of JSON objects in the following format, maximum number of objects to save is 128:
@@ -229,9 +179,8 @@ Export committed neuron data into an array of JSON objects in the following form
"vector": [10,10,10,10] // up to 128 bytes
}`
-### PME.restoreNeurons
-
-`void restoreNeurons(Json[] objects);`
+### pme.restoreNeurons(objects)
+* `objects` *array of JSON objects*
Restore neurons in an array of JSON objects in the following format, maximum number of objects to restore is 128:
diff --git a/docs/pwm.md b/docs/pwm.md
index 50ad5f1..47f81f6 100644
--- a/docs/pwm.md
+++ b/docs/pwm.md
@@ -3,7 +3,11 @@ ZJS API for Pulse Width Modulation (PWM)
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: PWM](#pwm-api)
+ * [pwm.open(init)](#pwmopeninit)
+* [Class: PWMPin](#pwmpin-api)
+ * [pin.setCycles(period, pulseWidth)](#pinsetcyclesperiod-pulsewidth)
+ * [pin.setMilliseconds(periodMS, pulseWidthMS)](#pinsetmillisecondsperiodms-pulsewidthms)
* [Sample Apps](#sample-apps)
Introduction
@@ -35,68 +39,67 @@ The PWM API intends to follow the [iot-js-api specification](https://github.com/
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-```javascript
+This IDL provides an overview of the interface; see below for documentation of
+specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+<details>
+<summary> Click to show/hide WebIDL</summary>
+<pre>
// require returns a PWM object
// var pwm = require('pwm');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface PWM {
- PWMPin open(PWMInit init);
-};
-
+ PWMPin open((long or string or PWMInit) init);
+};<p>
dictionary PWMInit {
- number or string pin;
+ (long or string) pin;
boolean reversePolarity = false;
-};
-
-[NoInterfaceObject]
-interface PWMPin {
+};<p>interface PWMPin {
void setCycles(unsigned long period, unsigned long pulseWidth);
void setMilliseconds(double period, double pulseWidth);
-};
-```
-
-API Documentation
------------------
-### PWM.open
+};</pre>
+</details>
-`PWMPin open(number or string or PWMInit init);`
+PWM API
+-------
+### pwm.open(init)
-If the argument is a number, it is a pin channel number. If it is a string, it
-is a pin name. Otherwise, it must be a `PWMInit` object.
+* `init` *long of string or PWMInit* A numerical argument indicates
+a pin channel number. If the argument is a string, it is a pin
+name. Otherwise, it must be a `PWMInit` object.
+* Returns: a PWMPin object that can be used to set the period and
+pulse width.
-The `init` object lets you set the pin channel number with the `pin` property.
-You can use a pin name like "PWM_0.2" where "PWM_0" is the name of a Zephyr
-pwm controller device for your board and 210 is the pin/channel number. This
-will work on any board as long as you find the right values in Zephyr
-documentation. But for boards with specific ZJS support, you can use friendly
-names. Currently this means Arduino 101 and FRDM-K64F.
+The `init` object lets you set the pin channel number with the `pin`
+property. You can use a pin name like "PWM_0.2", where "PWM_0" is the
+name of a Zephyr pwm controller device for your board and 210 is the
+pin/channel number. This will work on any board as long as you find
+the right values in the Zephyr documentation. For boards with specific
+ZJS support (currently: Arduino 101 and FRDM-K64F), you can use
+friendly names.
*Arduino 101*
-For the A101, you can use numbers 0-3 or strings "PWM0" through "PWM3", or the
+For the A101, you can use numbers 0-3, strings "PWM0" through "PWM3", or the
corresponding digital pin names "IO3", "IO5", "IO6", and "IO9".
*FRDM-K64F*
-For the K64F, you can use numbers 0-11 or strings "D3", "D5" through "D13",
-"A4" and "A5".
+For the K64F, you can use numbers 0-11, strings "D3", "D5" through "D13",
+and "A4" and "A5".
-The term 'channel' is used to refer to the fact that PWM controller hardware has
-multiple channels, but these are connected to output pins so as the user of the
-hardware you will think of them as pins.
+The term 'channel' refers to multiple channels on the PWM controller
+hardware, but these are connected to output pins, so the hardware user
+should think of them as pins.
The `reversePolarity` value should flip the signal if set to 'reverse', meaning
-the signal will be off (low) for the pulseWidth, and back on (high) for the
+the signal will be off (low) for the pulseWidth, and on (high) for the
rest of the period.
-The function returns a PWMPin object that can be used to set the period and
-pulse width.
+PWMPin API
+----------
-### PWMPin.setCycles
-
-`void setCycles(unsigned long period, unsigned long pulseWidth);`
+### pin.setCycles(period, pulseWidth)
+* `period` *unsigned long*
+* `pulseWidth` *unsigned long*
Sets the repeat period and pulse width for the signal, in terms of hardware
cycles. One hardware cycle is the minimum amount of time the hardware supports
@@ -104,18 +107,19 @@ having the pulse signal on (high).
Throws an error if pulseWidth is greater than period.
-This version of the API is useful when the duty cycle is what matters (e.g.
+This version of the API is useful when the duty cycle is what matters (e.g.,
using the 'analog' model of PWM control described in the
[Introduction](#introduction)). For example, a period of 20 with a pulse width
of 10 will make an LED at 50% brightness, with no flicker because the changes
occur far faster than visible to the human eye.
-### PWMPin.setMilliseconds
-
-`void setMilliseconds(double periodMS, double pulseWidthMS);`
+### pin.setMilliseconds(periodMS, pulseWidthMS)
+* `periodMS` *double* Signal repeat period.
+* ` pulseWidthMS` *double* Signal pulse width.
-Sets the repeat period and pulse width for the signal. It is given in
-milliseconds, so these can be fractional to provide microsecond timings, etc.
+Sets the repeat period and pulse width for the signal. The values are given in
+milliseconds, so these can be fractional to provide microsecond
+timings, for example.
The actual resolution available will depend on the hardware, so the value you
provide may get rounded.
*TODO: We could probably have the period attribute show the actual setting for
@@ -123,7 +127,7 @@ the device when it is read back.*
Throws an error if pulseWidth is greater than period.
-This version of the API is useful when the timing of the pulse matters (e.g.
+This version of the API is useful when the timing of the pulse matters (e.g.,
the 'servo' model of PWM control described in the
[Introduction](#introduction)).
diff --git a/docs/sensors.md b/docs/sensors.md
index 2fcb692..5f6d0f0 100644
--- a/docs/sensors.md
+++ b/docs/sensors.md
@@ -3,30 +3,39 @@ ZJS API for W3C Generic Sensors
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: Sensor](#sensor-api)
+ * [onreading](#onreading)
+ * [onactivate](#onactivate)
+ * [onerror](#onerror)
+ * [sensor.start()](#sensorstart)
+ * [sensor.stop()](#sensorstop)
* [Sample Apps](#sample-apps)
Introduction
------------
ZJS Generic Sensor API implements the W3C Sensor API, and it's intended to
provide a consistent API that allows apps to communicate with sensors like
-accelerometer and gyroscope. Since the W3C Sensor API is still a draft spec,
-our implementation only provide a subset of the API and the API could be
-slightly different, but we try to follow the latest spec as closely as
+an accelerometer or gyroscope. Since the W3C Sensor API is still a draft spec,
+our implementation only provides a subset of the API -- and this API could be
+slightly different even though we try to follow the latest spec as closely as
possible.
-Note: The currently supported hardware is Arduino 101 with its built-in
-BMI160 chip with accelerometer, gyroscope, and temperature. The supported
-ambient light sensor is the Grove light sensor that comes with the
-Grove starter kit, that can be connected using an analog pin.
+Note: The currently supported hardware is Arduino 101 that has a
+built-in BMI160 chip with accelerometer, gyroscope, and temperature
+sensors. The supported ambient light sensor is the Grove light sensor
+that comes with the Grove starter kit. The light sensor can be
+connected using an analog pin.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-####Sensor Interface
-```javascript
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>
interface Sensor {
readonly attribute boolean activated; // whether the sensor is activated or not
readonly attribute boolean hasReading; // whether the sensor has readings available
@@ -37,73 +46,43 @@ interface Sensor {
attribute ChangeCallback onreading; // callback handler for change events
attribute ActivateCallback onactivate; // callback handler for activate events
attribute ErrorCallback onerror; // callback handler for error events
-};
-
+};<p>
dictionary SensorOptions {
- double frequency; // desire frequency, default is 20 if unset
-};
-
-interface SensorErrorEvent {
+ double frequency; // desired frequency, default is 20 if unset
+};<p>interface SensorErrorEvent {
attribute Error error;
-};
-
-callback ChangeCallback = void();
+};<p>callback ChangeCallback = void();
callback ActivateCallback = void();
-callback ErrorCallback = void(SensorErrorEvent error);
-```
-####Accelerometer Interface
-```javascript
-[Constructor(optional AccelerometerOptions accelerometerOptions)]
+callback ErrorCallback = void(SensorErrorEvent error);<p>[Constructor(optional AccelerometerOptions accelerometerOptions)]
interface Accelerometer : Sensor {
readonly attribute double x;
readonly attribute double y;
readonly attribute double z;
-};
-
-dictionary AccelerometerOptions : SensorOptions {
+};<p>dictionary AccelerometerOptions : SensorOptions {
string controller; // controller name, default to "bmi160"
-};
-```
-####GyroscopeSensor Interface
-```javascript
-[Constructor(optional SensorOptions sensorOptions)]
+};<p>[Constructor(optional SensorOptions sensorOptions)]
interface GyroscopeSensor : Sensor {
readonly attribute double x;
readonly attribute double y;
readonly attribute double z;
-};
-
-dictionary GyroscopeOptions : SensorOptions {
+};<p>dictionary GyroscopeOptions : SensorOptions {
string controller; // controller name, default to "bmi160"
-};
-```
-####AmbientLightSensor Interface
-```javascript
-[Constructor(optional SensorOptions sensorOptions)]
+};<p>[Constructor(optional SensorOptions sensorOptions)]
interface AmbientLightSensor : Sensor {
readonly attribute unsigned long pin;
readonly attribute double illuminance;
-};
-
-dictionary AmbientLightSensorOptions : SensorOptions {
+};<p>dictionary AmbientLightSensorOptions : SensorOptions {
string controller; // controller name, default to "ADC_0"
unsigned long pin; // analog pin where the light is connected
-};
-```
-####TemperatureSensor Interface
-```javascript
-[Constructor(optional SensorOptions sensorOptions)]
+};<p>[Constructor(optional SensorOptions sensorOptions)]
interface TemperatureSensor : Sensor {
readonly attribute double celsius;
-};
-
-dictionary TemperatureSensorOptions : SensorOptions {
+};<p>dictionary TemperatureSensorOptions : SensorOptions {
string controller; // controller name, default to "bmi160"
-};
-```
+};</pre></details>
-API Documentation
------------------
+Sensor API
+----------
### onreading
`Sensor.onreading`
@@ -120,13 +99,11 @@ The onactivate attribute is an EventHandler which is called when the sensor is a
The onactivate attribute is an EventHandler which is called whenever an exception cannot be handled synchronously.
-### start
-`void Sensor.start()`
+### sensor.start()
Starts the sensor instance, the sensor will get callback on onreading whenever there's a new reading available.
-### stop
-`void Sensor.stop()`
+### sensor.stop()
Stop the sensor instance, the sensor will stop reporting new readings.
diff --git a/docs/spi.md b/docs/spi.md
index 8c8544b..60d3920 100644
--- a/docs/spi.md
+++ b/docs/spi.md
@@ -3,89 +3,95 @@ ZJS API for SPI
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
-* [Sample Apps](#sample-apps)
+* [SPI API](#spi-api)
+ * [spi.open(options)](#spiopenoptions)
+* [SPIBus API](#spibus-api)
+ * [spiBus.transceive(target, data, direction)](#spibustransceivetarget-data-direction)
+ * [spiBus.close()](#spibusclose)
Introduction
------------
The SPI API supports the Serial Peripheral Interface, a synchronous
-serial protocol that allows multiple slave chips to communicate with a master chip.
-A single SPI bus uses the following pins: SCLK for clock,
-MOSI (Master Out, Slave In) for write, MISO (Master In, Slave Out) for read, and
-one or more SS (Slave Select) for selecting the slave device.
-
-For each clock signal one bit is written from the master to the selected slave and
-one bit is read by the master from the selected slave, so there is no separate
-read and write, but one transceive operation.
-
-When a slave device's chip select is 0 (low), then it communicates with the
-master, otherwise it ignores the master. The master can select multiple slaves in
-a write-only configuration; in this case no slave is writing data, they only read.
-
-Since the SS pins may be connected to slave chip select through a demultiplexer
-and thereby work as an address bus, slave devices are identified by an index in
-this API, rather than by SS pins. Also, since multiple SPI buses may be present
-on a board, these are identified by an index in this API. Implementations SHOULD
-encapsulate the mapping from SPI bus number and device number to the physical SPI
+serial protocol that allows multiple slave chips to communicate with a
+master chip. A single SPI bus uses the following pins: SCLK for
+clock, MOSI (Master Out, Slave In) for write, MISO (Master In, Slave
+Out) for read, and one or more SS (Slave Select) for selecting the
+slave device.
+
+For each clock signal, one bit is written from the master to the
+selected slave, and one bit is read by the master from the selected
+slave, so there is one transceive operation, instead of a separate
+read and write.
+
+When a slave device's chip select is 0 (low), it communicates with the
+master; otherwise it ignores the master. The master can select
+multiple slaves in a write-only configuration; in this case, no slave
+is writing data, each only reads.
+
+Since the SS pins may be connected to slave chip select through a
+demultiplexer and thereby work as an address bus, slave devices are
+identified by an index in this API, rather than by SS pins. Also,
+since multiple SPI buses may be present on a board, these are
+identified by an index in this API. Implementations SHOULD encapsulate
+the mapping from SPI bus number and device number to the physical SPI
pins.
-Note that on the Arduino 101, using SPI will cause one of the onboard LED to
+Note that on the Arduino 101, using SPI will cause one of the onboard LEDs to
become unavailable.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
-// require returns a SPI object
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>// require returns a SPI object
// var spi = require('spi');
-
-[NoInterfaceObject]
+[ReturnFromRequire]
interface SPI {
SPIBus open(SPIOptions init);
-};
-
+};<p>
dictionary SPIOptions {
octet bus;
long speed; // bus clock frequency in Hz
- bool msbFirst;
+ boolean msbFirst;
long polarity;
long phase;
unsigned long frameGap;
string topology;
-
-};
-
-[NoInterfaceObject]
+};<p>[ExternalInterface=(Buffer)]
interface SPIBus {
- transceive(octet target, Buffer data, string direction);
- close();
+ void transceive(octet target, Buffer data, string direction);
+ void close();
};
-```
-
-API Documentation
------------------
-### SPI.open
-
-`SPIBus open(SPIOptions options);`
-
-The `options` object lets you pass optional values to use instead of the defaults.
-Note these values can't be changed once the SPI object is created. If you need
-to change the settings afterwards, you'll need to use the 'close' command and
-create a new SPI object with the settings you desire.
+</pre>
+</details>
-### SPIBus.transceive
-
-`Buffer transceive(octet target, Buffer data, string direction);`
+SPI API
+-------
+### spi.open(options)
+* `options` *SPIOptions* The `options` object lets you pass optional values to use instead of the defaults.
+* Returns: an SPIBus object.
+
+Note these `options` values can't be changed once the SPI object is
+created. If you need to change the settings afterwards, you'll need
+to use the 'close' command and create a new SPI object with the
+settings you desire.
+
+SPIBus API
+----------
+### spiBus.transceive(target, data, direction)
+* `target` *octet* The number identifying the slave.
+* `data` *Buffer* The data to be written to, and returned from, the slave.
+* `direction` *string*
Writes data buffer using SPI to the slave identified by the target argument, and
reads from the slave device into a readBuffer that is returned. The read and
write buffers are the same size.
-### SPIBus.close
-
-`void close();`
+### spiBus.close()
Closes the SPI connection.
diff --git a/docs/timers.md b/docs/timers.md
index 2504581..6f7bab7 100644
--- a/docs/timers.md
+++ b/docs/timers.md
@@ -3,7 +3,11 @@ ZJS API for Timers
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [Class: Timers](#timers-api)
+ * [timers.setInterval(func, delay, args_for_func)](#timerssetintervalfunc-delay-args_for_func)
+ * [timers.setTimeout(func, delay, args_for_func)](#timerssettimeoutfunc-delay-args_for_func)
+ * [timers.clearInterval(intervalID)](#timersclearintervalintervalid)
+ * [timers.clearTimeout(timeoutID)](#timerscleartimeouttimeoutid)
* [Sample Apps](#sample-apps)
Introduction
@@ -13,70 +17,55 @@ available.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
-
-```javascript
-intervalID setInterval(TimerCallback func, unsigned long delay, optional arg1, ...);
-timeoutID setTimeout(TimerCallback func, unsigned long delay, optional arg1, ...);
-void clearInterval(intervalID);
-void clearTimeout(timeoutID);
-
-callback TimerCallback = void (optional arg1, ...);
-```
-
-API Documentation
------------------
-### setInterval
-
-`intervalID setInterval(TimerCallback func, unsigned long delay, optional arg1, ...);
-`
-
-The `func` argument is a callback function that should expect whatever arguments
-you pass as arg1, arg2, and so on.
-
-The `delay` argument is in milliseconds. Currently, the delay resolution is
-about 10 milliseconds and if you choose a value less than that it will probably
-fail.
-
-Any additional arguments such as `arg1` will be passed to the callback you
-provide. They can be whatever type you wish.
-
-Every `delay` milliseconds, your callback function will be called. An
-`intervalID` will be returned that you can save and pass to clearInterval later
-to stop the timer.
-
-### setTimeout
-
-`timeoutID setTimeout(TimerCallback func, unsigned long delay, optional arg1, ...);`
-
-The `func` argument is a callback function that should expect whatever arguments
-you pass as arg1, arg2, and so on.
-
-The `delay` argument is in milliseconds. Currently, the delay resolution is
-about 10 milliseconds.
-
-Any additional arguments such as `arg1` will be passed to the callback you
-provide. They can be whatever type you wish.
-
-After `delay` milliseconds, your callback function will be called *one time*. A
-`timeoutID` will be returned that you can save and pass to clearTimeout later
-to stop the timer.
-
-### clearInterval
-
-`void clearInterval(intervalID);`
-
-The `intervalID` should be what was returned from a previous call to
-`setInterval`. That interval timer will be cleared and its callback function
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
+
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>
+// require returns a Timers object
+// var timers = require('timers');
+[ReturnFromRequire]
+interface Timers {
+ intervalID setInterval(TimerCallback func, unsigned long delay, any... args_for_func);
+ timeoutID setTimeout(TimerCallback func, unsigned long delay, any... args_for_func);
+ void clearInterval(long intervalID);
+ void clearTimeout(long timeoutID);
+};<p>
+callback TimerCallback = void (any... callback_args);
+<p>typedef long timeoutID;
+typedef long intervalID;</pre>
+</details>
+
+Timers API
+----------
+### timers.setInterval(func, delay, args_for_func)
+* `func` *TimerCallback* A callback function that will take the arguments passed in the variadic `args_for_func` parameter.
+* `delay` *unsigned long* The `delay` argument is in milliseconds. Currently, the delay resolution is about 10 milliseconds, and if you choose a value less than that it will probably fail.
+* `args_for_func` *any* The user can pass an arbitrary number of additional arguments that will then be passed to `func`.
+* Returns: an `intervalID` value that can be passed to `clearInterval` to stop the timer.
+
+Every `delay` milliseconds, your callback function will be called.
+
+### timers.setTimeout(func, delay, args_for_func)
+* `func` *TimerCallback* A callback function that will take the arguments passed in the variadic `args_for_func` parameter.
+* `delay` *unsigned long* The `delay` argument is in milliseconds. Currently, the delay resolution is about 10 milliseconds.
+* `args_for_func` *any* The user can pass an arbitrary number of additional arguments that will then be passed to `func`.
+* Returns: a `timeoutID` that can be passed to `clearTimeout` to stop the timer.
+
+After `delay` milliseconds, your callback function will be called *one time*.
+
+### timers.clearInterval(intervalID)
+* `intervalID` *long* This value was returned from a call to `setInterval`.
+
+That interval timer will be cleared and its callback function
no longer called.
-### clearTimeout
-
-`void clearTimeout(timeoutID);`
+### timers.clearTimeout(timeoutID)
+* `timeoutID` *long* This value was returned from a call to `setTimeout`.
-The `timeoutID` should be what was returned from a previous call to
-`setTimeout`. That timer will be cleared and its callback function will not be
+The `timeoutID` timer will be cleared and its callback function will not be
called.
Sample Apps
diff --git a/docs/uart.md b/docs/uart.md
index 4a20170..18f7b49 100644
--- a/docs/uart.md
+++ b/docs/uart.md
@@ -3,13 +3,17 @@ Zephyr.js API for UART
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
-* [Sample Apps](#sample-apps)
+* [Class UART](#uart-api)
+ * [uart.init(options)](#uartinitoptions)
+* [UARTConnection API](#uartconnection-api)
+ * [Event: 'read'](#event-read)
+ * [uartConnection.write(data)](#uartconnectionwritedata)
+ * [uartConnection.setReadRange(min, max)](#uartconnectionsetreadrangemin-max)
Introduction
------------
-The UART module supports both read and write capabilities. Write is achieved
-with a 'write' function, and read is done via a callback function property that
+The UART module supports both read and write capabilities. Writes are
+done through the 'write' function, and reads are done via a callback function property that
can be set. Read and write data should be a JavaScript string.
The module can be used on both QEMU and the Arduino 101. When using QEMU, you
@@ -18,69 +22,61 @@ read/written from the serial console just as print does.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions. Commented out properties or functions are not
-implemented because the feature is not available on Zephyr.
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
-// require returns a UART object
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>// require returns a UART object
// var uart = require('uart');
-
-enum UARTParity { "none", "event", "odd" }
-
interface UART {
UARTConnection init(UARTOptions options);
-};
-
+};<p>
dictionary UARTOptions {
string port;
- // number baud = 115200;
- // number dataBits = 8;
- // number stopBits = 1;
+ // long baud = 115200;
+ // long dataBits = 8;
+ // long stopBits = 1;
// UARTParity parity = "none";
// boolean flowControl = false;
-};
-
-[NoInterfaceObject]
+};<p>[ExternalInterface=(Buffer),ExternalInterface=(EventEmitter)]
interface UARTConnection: EventEmitter {
// void close();
void write(Buffer data);
- void setReadRange(number min, number max);
-};
-```
-
-API Documentation
------------------
-## UART interface
+ void setReadRange(long min, long max);
+};<p>enum UARTParity { "none", "event", "odd" };
+</pre>
+</details>
-### UART.init
+UART API
+--------
+### uart.init(options)
+* `options` *UARTOptions* The `UARTOptions` object lets you choose the
+ UART device/port you would like to initialize. The Arduino 101, for
+ example, should be "tty0".
+* Returns: UARTConnection interface, described below.
-`UARTConnection init(UARTOptions options);`
+UARTConnection API
+------------------
-The `options` object lets you choose the UART device/port you would like to
-initialize. The Arduino 101, for example, should be "tty0".
-
-## UARTConnection interface
-UARTConnection is an [EventEmitter](./events.md) with the following events:
+A UARTConnection is an [EventEmitter](./events.md) with the following events:
### Event: 'read'
-
* `Buffer` `data`
Emitted when data is received on the UART RX line. The `data` parameter is a
`Buffer` with the received data.
-### UARTConnection.write
-
-`void write(Buffer data);`
-
-Write data out to the UART TX line. `data` is a string that will be written.
+### uartConnection.write(data)
+* `data` *Buffer* The data to be written.
-### UARTConnection.setReadRange
+Write data out to the UART TX line.
-`void setReadRange(number min, number max);`
+### uartConnection.setReadRange(min, max);`
+* `min` *long* The minimum number of bytes for triggering the `onread` event.
+* `max` *long* The maximum number of bytes for triggering the `onread` event.
-Set the minimum and maximum number of bytes for triggering the `onread` event.
Whenever at least the `min` number of bytes is available, a `Buffer` object
containing at most `max` number of bytes is sent with the `onread` event.
diff --git a/docs/web-socket.md b/docs/web-socket.md
index f3fc58c..806a7d9 100644
--- a/docs/web-socket.md
+++ b/docs/web-socket.md
@@ -3,47 +3,61 @@ ZJS API for Web Sockets
* [Introduction](#introduction)
* [Web IDL](#web-idl)
-* [API Documentation](#api-documentation)
+* [WebSocket API](#websocket-api)
+ * [ws.Server(options)](#wsserveroptions)
+* [WebSocketServer API](#websocketserver-api)
+ * [Event: 'connection'](#event-connection)
+* [WebSocket API](#websocket-api)
+ * [Event: 'close'](#event-close)
+ * [Event: 'error'](#event-error)
+ * [Event: 'message'](#event-message)
+ * [Event: 'ping'](#event-ping)
+ * [Event: 'pong'](#event-pong)
+* [WebSocketConnection API](#websocketconnection-api)
+ * [webSocketConnection.send(data, mask)](#websocketconnectionsenddata-mask)
+ * [webSocketConnection.ping(data, mask)](#websocketconnectionpingdata-mask)
+ * [webSocketConnection.pong(data, mask)](#websocketconnectionpongdata-mask)
* [Sample Apps](#sample-apps)
Introduction
------------
The Web Socket API is modeled after Node.js' 'ws' module. This module only
-supports the Web Socket server portion of the API.
+supports the Web Socket server portion of that API.
Web IDL
-------
-This IDL provides an overview of the interface; see below for documentation of
-specific API functions.
+This IDL provides an overview of the interface; see below for
+documentation of specific API functions. We have a short document
+explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md).
-```javascript
-// require returns a WebSocket object
+<details>
+<summary>Click to show WebIDL</summary>
+<pre>// require returns a WebSocket object
// var ws = require('ws');
-
+[ReturnFromRequire]
interface WebSocket {
- WebSocketServer Server(Object options);
-};
-
-interface WebSocketServer: EventEmitter;
-
+ WebSocketServer Server(object options);
+};<p>
+[ExternalInterface=(EventEmitter)]
+interface WebSocketServer: EventEmitter{};<p>[ExternalInterface=(Buffer),]
interface WebSocketConnection: EventEmitter {
- // WebSocketConnection methods
- void send(Buffer data, Boolean mask);
- void ping(Buffer data, Boolean mask);
- void pong(Buffer data, Boolean mask);
-};
-```
+ void send(Buffer data, boolean mask);
+ void ping(Buffer data, boolean mask);
+ void pong(Buffer data, boolean mask);
+};</pre>
+</details>
-WebSocket API Documentation
----------------------------
+WebSocket API
+-------------
-### WebSocket.Server
-`WebSocketServer Server(Object options)`
+### ws.Server(options)
+* `options` *Object*
+* Returns: a WebSocketServer object.
Create a Web Socket server object. Options object may contain:
-WebSocketServer API Documentation
----------------------------------
+WebSocketServer API
+-------------------
WebSocketServer is [EventEmitter](./events.md) with the following events:
@@ -70,10 +84,10 @@ strings from the handler.
Returns a `WebSocketServer` object.
-WebSocketConnection API Documentation
--------------------------------------
+WebSocket API
+-------------
-WebSocketServer is [EventEmitter](./events.md) with the following events:
+WebSocketServer is an [EventEmitter](./events.md) with the following events:
### Event: 'close'
@@ -107,29 +121,27 @@ the `data` argument.
Emitted when the socket has received a pong. The pong's payload is contained in
the `data` argument.
-### WebSocketConnection.send
-
-`void send(Buffer data, Boolean mask)`
-Send data to the other end of the web socket connection. The `data` parameter
-should contain the data payload to send. The `mask` parameter says whether the
-data payload should be masked.
+WebSocketConnection API
+-----------------------
-### WebSocketConnection.ping
+### webSocketConnection.send(data, mask)
+* `data` *Buffer* The data payload to send.
+* `mask` *boolean* Describes whether the data payload should be masked.
-`void ping(Buffer data, Boolean mask)`
+Send data to the other end of the web socket connection.
-Send a ping to the other end of the web socket connection. The `data` parameter
-should contain the data payload to send. The `mask` parameter says whether the
-data payload should be masked.
+### webSocketConnection.ping(data, mask)
+* `data` *Buffer* Contains the data payload to send.
+* `mask` *boolean* Describes whether the data payload should be masked.
-### WebSocketConnection.pong
+Send a ping to the other end of the web socket connection.
-`void pong(Buffer data, Boolean mask)`
+### webSocketConnection.pong(data, mask)
+* `data` *Buffer* The data payload to send.
+* `mask` *boolean* Describes whether the data payload should be masked.
-Send a pong to the other end of the web socket connection. The `data` parameter
-should contain the data payload to send. The `mask` parameter says whether the
-data payload should be masked.
+Send a pong to the other end of the web socket connection.
Sample Apps
-----------