diff --git a/docs/Notes_on_WebIDL.md b/docs/Notes_on_WebIDL.md new file mode 100644 index 000000000..d4dab86e8 --- /dev/null +++ b/docs/Notes_on_WebIDL.md @@ -0,0 +1,32 @@ +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". diff --git a/docs/aio.md b/docs/aio.md index 8fd8c99e7..dfd9e919d 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,23 +29,23 @@ not have support for this. 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 an AIO object // var aio = require('aio'); -[NoInterfaceObject] +[ReturnFromRequire] interface AIO { AIOPin open(AIOInit init); }; dictionary AIOInit { - unsigned long pin; + (unsigned long or string) pin; }; -[NoInterfaceObject] interface AIOPin { unsigned long read(); void readAsync(ReadCallback callback); // TODO: change to return a promise @@ -50,57 +56,55 @@ interface AIOPin { 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.read - -`unsigned long read();` +AIOPin API +---------- +### pin.read() +* Returns: the latest reading from the pin (an unsigned integer). Blocks until it gets the result. -Returns the latest reading from the pin. Blocks until it gets the result. +### pin.readAsync(callback) +* 'callback' *ReadCallback* User-provided callback function that takes + a single unsigned integer and has no return value. -### 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 +### 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. -`void on(string eventType, ReadCallback callback);` - -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 aa127d963..0092ac732 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) @@ -25,21 +38,22 @@ treat them like decimals.* Web IDL ------- This IDL provides an overview of the interface; see below for documentation of -specific API functions. +specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md). + ```javascript // require returns a BLE object // var ble = require('ble'); -[NoInterfaceObject] +[ReturnFromRequire] interface BLE: EventEmitter { void disconnect(string address); void startAdvertising(string name, string[] uuids, string url); void stopAdvertising(); - void setServices(PrimaryService services[]); - PrimaryService PrimaryService(PrimaryServiceInit init); - Characteristic Characteristic(CharacteristicInit init); - Descriptor Descriptor(DescriptorInit init); + void setServices(PrimaryService[] services); + PrimaryService newPrimaryService(PrimaryServiceInit init); + Characteristic newCharacteristic(CharacteristicInit init); + Descriptor newDescriptor(DescriptorInit init); }; dictionary PrimaryServiceInit { @@ -58,157 +72,171 @@ dictionary CharacteristicInit { NotifyCallback onNotify; // optional }; -callback ReadCallback = void (unsigned long offset, FulfillReadCallback); +interface Characteristic { + attribute ReadCallback onReadRequest; + attribute WriteCallback onWriteRequest; + attribute SubscribeCallback onSubscribe; + attribute UnsubscribeCallback onUnsubscribe; + attribute NotifyCallback onNotify; + attribute CharacteristicResult response; +}; + +callback ReadCallback = void (unsigned long offset, + FulfillReadCallback fulfillReadCallback); 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); +enum CharacteristicResult { "RESULT_SUCCESS", "RESULT_INVALID_OFFSET", "RESULT_INVALID_ATTRIBUTE_LENGTH", "RESULT_UNLIKELY_ERROR" } ; + dictionary DescriptorInit { string uuid; string value; }; - -[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/buffer.md b/docs/buffer.md index 17f1bb363..0449e39b3 100644 --- a/docs/buffer.md +++ b/docs/buffer.md @@ -2,6 +2,7 @@ ZJS API for Buffer ================== * [Introduction](#introduction) +* [Web IDL](#web-idl) * [Class: Buffer](#buffer-api) * [new Buffer(array)](#new-bufferarray) * [new Buffer(size)](#new-buffersize) @@ -20,29 +21,63 @@ 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). + +```javascript +[ Constructor(Uint8Array initialValues), + Constructor(unsigned long size), + Constructor(ByteString initialString) ] +interface Buffer { + readonly attribute unsigned long length; + 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 = this.length-offset, + 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); +}; +``` + 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.