IoT Web APIs

Introduction

The following JavaScript APIs are aimed for handling Internet of Things (IoT) applications on a given device:

• Open Connect Foundation (OCF) API, exposing OCF Client and Server APIs
  • OCF API Test Suite
• Bluetooth Smart API, exposing functionality for Bluetooth Peripheral mode
• Sensor API, exposing sensor functionality supported on the device
• Board API providing low-level interfaces for I/O operations supported by the device board, so that applications could implement support for new types of sensors that are not supported by the Sensor API.

Since implementations of these APIs exist also on constrained hardware, they might not support the latest ECMAScript versions. However, implementations should support at least ECMAScript 5.1. Examples are limited to ECMAScript 5.1 with the exception of using Promises.

Structures

The following structures SHOULD be implemented in a constrained environment:

• Promise
• Buffer
• EventEmitter
• Error.

Promises

The API uses Promises. In constrained implementations, at least the following Promise methods MUST be implemented:

• the Promise constructor
• the then(onFulfilled, onRejected) method
• the catch(onRejected) method.

Buffer

Buffer is a node.js API to read and write binary data accurately from JavaScript. This API supports a subset that will be expanded as needed:

• constructor with a number argument size
• the length property
• the readUint8(offset) method
• the writeUint8(value, offset) method
• the toString(encoding) method.

Events

The API uses Node.js-style events. In constrained implementations, at least the following subset of the EventEmitter interface MUST be supported:

• the on(eventName, callback) method
• the addListener(eventName, callback) method, as an alias to the on() method
• the removeListener(eventName, callback) method
• the removeAllListeners method.

Note that in order to make sure only one entity responds to a request, server request handling is done with registering callbacks at the serving objects (end points), rather than using events. Also, when subscribing to notifications requires options or filters, callbacks are used instead of events.

In the future events may be replaced by Observables with signal semantics.

Error handling

Errors are exposed via onerror events and Promise rejections, using augmented instances of a minimal subset of Error objects with added properties.

The Error object MUST contain at least the following properties:

Property	Type	Optional	Default value	Represents
name	string	no	"Error"	The standard name of the error
message	string	yes	""	The error reason

The following error names may be used by all APIs:

• SecurityError for lack of permission or invalid access.
• NotSupportedError for features not implemented.
• SyntaxError for broken JavaScript and eval errors. Use it sparingly.
• TypeError for invalid types, parameters, etc.
• RangeError for parameters out of permitted range.
• TimeoutError for timeouts.
• NetworkError for generic connection or protocol related errors.
• SystemError for generic platform errors, including reference errors.

Further errors may be defined in specific APIs.

Examples:

var error = new SecurityError("No permissions");

if ((error instanceof Error) && (error instanceof SecurityError)) {  // true
  console.log(error.name);  // "SecurityError"
  console.log(error.message);  // "No permissions"
}

Testing

A test runner is provided in this repository. It is designed to launch a series of tests for each API specified here, each test in its own process. test-runner.md provides more details on launching tests.