From 6b7e6c6253811d3f91362cd3faa15520b4894fb5 Mon Sep 17 00:00:00 2001 From: Timothy Harvey Date: Wed, 24 Jan 2018 16:11:14 -0600 Subject: [PATCH 1/3] jfjfjf --- docs/aio.md | 46 +++++++++++++++++++++++----------------------- docs/buffer.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 23 deletions(-) diff --git a/docs/aio.md b/docs/aio.md index 8fd8c99e7..4d342f2e7 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)](#aiopin-openaioinit) +* [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 @@ -30,16 +36,15 @@ specific API functions. // 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,11 +55,12 @@ interface AIOPin { callback ReadCallback = void (unsigned long value); ``` -API Documentation ------------------ -### AIO.open - -`AIOPin open(AIOInit init);` +AIO API +------- +### AIOPin open(AIOInit) +* 'init' *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). The `init` object lets you set the pin number. You can either use a raw number for your device or use the board support module such as @@ -63,15 +69,13 @@ 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. Blocks until it gets the result. +Returns the latest reading from the pin (an unsigned integer). Blocks until it gets the result. -### AIOPin.readAsync - -`void readAsync(ReadCallback callback);` +### pin.readAsync(ReadCallback) Pass a function for `callback` that will be called later when the result is obtained. @@ -85,9 +89,7 @@ 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, ReadCallback) 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, @@ -96,11 +98,9 @@ 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/buffer.md b/docs/buffer.md index 17f1bb363..5529eeb96 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,6 +21,33 @@ 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 +------- + +[ + Constructor(Uint8Array initial_values), + Constructor(unsigned long size), + Constructor(ByteString initial_string) +] +interface Buffer { + readonly attribute unsigned long length; + unsigned long copy(Buffer target, optional unsigned long targetStart, + optional unsigned long sourceStart + optional unsigned long sourceEnd); + octet readUInt8(unsigned long offset); + void writeUInt8(octet value, unsigned long offset); + unsigned short readUInt16BE(unsigned long offset); + void writeUInt16BE(unsigned short value, unsigned long offset); + unsigned short readUInt16LE(unsigned long offset); + void writeUInt16LE(unsigned short value, unsigned long offset); + unsigned long readUInt32BE(unsigned long offset); + void writeUInt32BE(unsigned long value, unsigned long offset); + unsigned long readUInt32LE(unsigned long offset); + void writeUInt32LE(unsigned long value, unsigned long offset); + string toString(string encoding); +}; + + Buffer API ---------- ### new Buffer(array) From b2e4ff7a3dc7cc02cc13510031861d31241a86f2 Mon Sep 17 00:00:00 2001 From: Timothy Harvey Date: Sun, 28 Jan 2018 17:05:16 -0600 Subject: [PATCH 2/3] 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. --- docs/Notes_on_WebIDL.md | 33 +++++++ docs/aio.md | 34 ++++--- docs/ble.md | 194 +++++++++++++++++++++++----------------- docs/buffer.md | 58 ++++++------ 4 files changed, 200 insertions(+), 119 deletions(-) create mode 100644 docs/Notes_on_WebIDL.md diff --git a/docs/Notes_on_WebIDL.md b/docs/Notes_on_WebIDL.md new file mode 100644 index 000000000..dc75a1620 --- /dev/null +++ b/docs/Notes_on_WebIDL.md @@ -0,0 +1,33 @@ +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 4d342f2e7..87ccdea55 100644 --- a/docs/aio.md +++ b/docs/aio.md @@ -4,7 +4,7 @@ ZJS API for Analog I/O (AIO) * [Introduction](#introduction) * [Web IDL](#web-idl) * [Class: AIO](#aio-api) - * [aio.open(AIOInit)](#aiopin-openaioinit) + * [aio.open(AIOInit)](#aioopenaioinit) * [Class: AIOPin](#aiopin-api) * [pin.read()](#pinread) * [pin.readAsync(ReadCallback)](#pinreadasyncreadcallback) @@ -29,8 +29,11 @@ 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. Click +[here](Notes_on_WebIDL.md) for an explanation of zephyr.js' WebIDL +conventions. ```javascript // require returns an AIO object @@ -57,17 +60,17 @@ callback ReadCallback = void (unsigned long value); AIO API ------- -### AIOPin open(AIOInit) -* 'init' *object* The AIOInit object has a single field called "pin" +### aio.open(AIOInit) +* '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). -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. +Returns an AIOPin object that be used to read values from the pin. AIOPin API ---------- @@ -76,24 +79,29 @@ AIOPin API Returns the latest reading from the pin (an unsigned integer). Blocks until it gets the result. ### pin.readAsync(ReadCallback) +* 'ReadCallback' *callback* User-provided callback function that takes + a single unsigned integer and has no return value. -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.* ### pin.on(eventType, ReadCallback) +* 'eventType' *string* Type of event; currently, the only supported + type is "change". +* 'ReadCallback' *callback* 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. diff --git a/docs/ble.md b/docs/ble.md index aa127d963..b4cb5fafc 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,23 @@ 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. Click [here](Notes_on_WebIDL.md) for an +explanation of zephyr.js' WebIDL conventions. + ```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,36 +73,36 @@ 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' @@ -118,97 +133,114 @@ one previously sent with the 'accept' event. 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. + +Advertises the name of the device. + +### ble.stopAdvertising() -### BLE.startAdvertising +Currently does nothing. -`void startAdvertising(string name, string[] uuids, string url);` +### ble.setServices(primaryServices) +* primaryServices *array of PrimaryService objects* The PrimaryService + objects are used to set up the services that are implemented by your + app. + +The PrimaryService object contains the following fields: -The `name` is limited to 26 characters and will be advertised as the device -name to nearby BLE devices. -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.newPrimaryService(init) +* 'init' *PrimaryServiceInit*(#primaryserviceinit) -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. +Returns a new PrimaryService object. -### BLE.stopAdvertising +### ble.newCharacteristic(init) +* init *CharacteristicInit* -`void stopAdvertising();` +Returns a new Characteristic object. -Currently does nothing. -### BLE.setServices +### ble.newDescriptor(init) +* 'init' *DescriptorInit*(#descriptorinit-struct) -`void setServices(PrimaryService[]);` +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)* -### 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 5529eeb96..8d9054f65 100644 --- a/docs/buffer.md +++ b/docs/buffer.md @@ -23,54 +23,62 @@ 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. Click [here](Notes_on_WebIDL.md) for an +explanation of zephyr.js' WebIDL conventions. -[ - Constructor(Uint8Array initial_values), +```javascript +[ Constructor(Uint8Array initial_values), Constructor(unsigned long size), - Constructor(ByteString initial_string) -] + Constructor(ByteString initial_string) ] interface Buffer { readonly attribute unsigned long length; - unsigned long copy(Buffer target, optional unsigned long targetStart, - optional unsigned long sourceStart - optional unsigned long sourceEnd); - octet readUInt8(unsigned long offset); - void writeUInt8(octet value, unsigned long offset); - unsigned short readUInt16BE(unsigned long offset); - void writeUInt16BE(unsigned short value, unsigned long offset); - unsigned short readUInt16LE(unsigned long offset); - void writeUInt16LE(unsigned short value, unsigned long offset); - unsigned long readUInt32BE(unsigned long offset); - void writeUInt32BE(unsigned long value, unsigned long offset); - unsigned long readUInt32LE(unsigned long offset); - void writeUInt32LE(unsigned long value, unsigned long offset); + unsigned long copy(Buffer target, optional unsigned long targetStart = 0, + optional unsigned long sourceStart = 0, + optional unsigned long sourceEnd = this.length); + this fill((string or Buffer or long) value, optional long offset = 0, + optional long end = this.length, + 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. -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. -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. From 3dce399124182c1cd24c9d2690016a1098158e71 Mon Sep 17 00:00:00 2001 From: Timothy Harvey Date: Thu, 1 Feb 2018 20:33:48 -0600 Subject: [PATCH 3/3] Made changes based on the first round of pull request 1800 --- docs/Notes_on_WebIDL.md | 13 ++++----- docs/aio.md | 24 +++++++--------- docs/ble.md | 62 +++++++++++++++++++---------------------- docs/buffer.md | 19 ++++++------- 4 files changed, 54 insertions(+), 64 deletions(-) diff --git a/docs/Notes_on_WebIDL.md b/docs/Notes_on_WebIDL.md index dc75a1620..d4dab86e8 100644 --- a/docs/Notes_on_WebIDL.md +++ b/docs/Notes_on_WebIDL.md @@ -4,30 +4,29 @@ 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, +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: +We map WebIDL definitions to JavaScript objects as follows: -1. dictionaries -- these map to Javascript objects that simply don't +1. dictionaries -- these map to JavaScript objects that simply don't have methods attached to them. -2. interfaces -- like definitions, these correspond to Javascript +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 +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 +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 87ccdea55..dfd9e919d 100644 --- a/docs/aio.md +++ b/docs/aio.md @@ -31,9 +31,7 @@ Web IDL ------- This IDL provides an overview of the interface; see below for -documentation of specific API functions. Click -[here](Notes_on_WebIDL.md) for an explanation of zephyr.js' WebIDL -conventions. +documentation of specific API functions. We have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md). ```javascript // require returns an AIO object @@ -60,26 +58,24 @@ callback ReadCallback = void (unsigned long value); AIO API ------- -### aio.open(AIOInit) -* 'AIOInit' *object* The AIOInit object has a single field called "pin" +### 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. 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. -Returns an AIOPin object that be used 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. -Returns the latest reading from the pin (an unsigned integer). Blocks until it gets the result. - -### pin.readAsync(ReadCallback) -* 'ReadCallback' *callback* User-provided callback function that takes +### pin.readAsync(callback) +* 'callback' *ReadCallback* User-provided callback function that takes a single unsigned integer and has no return value. Pass a function for `ReadCallback` that will be called later when the result is @@ -95,11 +91,11 @@ any given time.* *NOTE: This function will probably be replaced with a version that instead returns a promise.* -### pin.on(eventType, ReadCallback) +### pin.on(eventType, callback) * 'eventType' *string* Type of event; currently, the only supported type is "change". -* 'ReadCallback' *callback* User-provided callback function that takes - a single, unsigned integer and has no return value; can be null. +* 'callback' *ReadCallback* User-provided callback function that takes + a single, unsigned integer and has no return value; can be null. 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 diff --git a/docs/ble.md b/docs/ble.md index b4cb5fafc..0092ac732 100644 --- a/docs/ble.md +++ b/docs/ble.md @@ -38,8 +38,7 @@ treat them like decimals.* Web IDL ------- This IDL provides an overview of the interface; see below for documentation of -specific API functions. Click [here](Notes_on_WebIDL.md) for an -explanation of zephyr.js' WebIDL conventions. +specific API functions. We also have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md). ```javascript @@ -79,16 +78,16 @@ interface Characteristic { attribute SubscribeCallback onSubscribe; attribute UnsubscribeCallback onUnsubscribe; attribute NotifyCallback onNotify; - attribute CharacteristicResult response; + attribute CharacteristicResult response; }; callback ReadCallback = void (unsigned long offset, - FulfillReadCallback fulfillreadcallback); + FulfillReadCallback fulfillReadCallback); callback WriteCallback = void (Buffer data, unsigned long offset, boolean withoutResponse, - FulfillWriteCallback fulfillwritecallback); + FulfillWriteCallback fulfillWriteCallback); callback SubscribeCallback = void (unsigned long maxValueSize, - FulfillSubscribeCallback fullfillsubscribecallback); + FulfillSubscribeCallback fullfillSubscribeCallback); callback FulfillReadCallback = void (CharacteristicResult result, Buffer data); callback FulfillWriteCallback = void (CharacteristicResult result); callback FulfillSubscribeCallback = void (Buffer data); @@ -105,83 +104,80 @@ 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 API ------- ### ble.disconnect(address) -*'address' *string* The address of the connected client. +* `address` *string* The address of the connected client. Disconnect the remote client. ### ble.startAdvertising(name, uuids, url) -* name *string* The `name` is limited to 26 characters and will be +* `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` *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 +* `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. - -Advertises the name of the device. + +Advertises the name and url of the device. ### ble.stopAdvertising() Currently does nothing. ### ble.setServices(primaryServices) -* primaryServices *array of PrimaryService objects* The PrimaryService +* `primaryServices` *array of [PrimaryService](#primaryservice) objects* The PrimaryService objects are used to set up the services that are implemented by your app. - + The PrimaryService object contains the following fields: ### ble.newPrimaryService(init) -* 'init' *PrimaryServiceInit*(#primaryserviceinit) - -Returns a new PrimaryService object. +* `init` [*PrimaryServiceInit*](#primaryserviceinit) +* Returns: a new PrimaryService object. ### ble.newCharacteristic(init) -* init *CharacteristicInit* - -Returns a new Characteristic object. +* `init` [*CharacteristicInit*](#characteristicinit) +* Returns: a new Characteristic object. ### ble.newDescriptor(init) -* 'init' *DescriptorInit*(#descriptorinit-struct) - -Returns a new DescriptorInit object. +* `init` [*DescriptorInit*](#descriptorinit) +* Returns: a new DescriptorInit object. Characteristic API @@ -204,8 +200,8 @@ Supporting Objects ### PrimaryServiceInit 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)* +1. `uuid` *string* This field is a 16-bit service UUID (4 hex chars). +2. `characteristics` *array of [Characteristics](#characteristic-api)* ### CharacteristicInit @@ -236,9 +232,9 @@ It may also contain these optional callback fields: ### DescriptorInit This object has two fields: -1. 'uuid' *string* This is a 16-bit descriptor UUID (4 hex chars) +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. +2. `value` *string* This string supplies the defined information. * *NOTE: Values can also be Buffer objects, but that's not currently supported.* diff --git a/docs/buffer.md b/docs/buffer.md index 8d9054f65..0449e39b3 100644 --- a/docs/buffer.md +++ b/docs/buffer.md @@ -24,20 +24,19 @@ 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. Click [here](Notes_on_WebIDL.md) for an -explanation of zephyr.js' WebIDL conventions. +specific API functions. We have a short document explaining [ZJS WebIDL conventions](Notes_on_WebIDL.md). ```javascript -[ Constructor(Uint8Array initial_values), +[ Constructor(Uint8Array initialValues), Constructor(unsigned long size), - Constructor(ByteString initial_string) ] + 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.length); + optional unsigned long sourceEnd); this fill((string or Buffer or long) value, optional long offset = 0, - optional long end = this.length, + optional long end, optional string encoding = "utf8"); octet readUInt8(optional unsigned long offset = 0); short readUInt16BE(optional unsigned long offset = 0); @@ -58,8 +57,8 @@ interface Buffer { 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. 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 @@ -73,8 +72,8 @@ represents. If a negative length is passed, a 0-length Buffer will be returned. 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 an array of UTF8 values and will be used to initialize the new buffer. If there is not enough