restserver-api

Example program This example shows basic restserver-api usage.

const restAPI = require('restserver-api');

const { Lwm2m } = restAPI;
const { RESOURCE_TYPE, encodeResource, decodeResource } = Lwm2m.TLV;

console.log('Initialize service and endpoint');
const service = new restAPI.Service();
const device = new restAPI.Device(service, 'urn:uuid:17200d69-ec9b-43b3-9051-73df2207907c');

console.log('Encode resource to TLV format');
const tlvBuffer = encodeResource({
  identifier: 3,
  type: RESOURCE_TYPE.INTEGER,
  value: 60
});

console.log('Start service');
service.start().then(() => {
  console.log('Service started');
  console.log('Writing into device\'s resource');
  device.write('/3/0/7', (status) => {
    console.log('Received response with status: ', status);
    console.log('Stopping service');
    service.stop().then(() => {
      console.log('Service stopped');
    });
  }, tlvBuffer);
});

Classes

Device: This class represents device (endpoint).
Service: This class represents REST API service.

Constants

TYPE: Represents LwM2M variable (identifier) types (OBJECT_INSTANCE, MULTIPLE_RESOURCE, RESOURCE_INSTANCE, RESOURCE).
RESOURCE_TYPE: Represents resource type (NONE, BOOLEAN, INTEGER, FLOAT, STRING, OPAQUE).

Functions

getDictionaryByValue(dictionaryList, keyName, value) ⇒ Object | string | number: Gets dictionary by given name of the key and value.
encodeResourceValue(resource) ⇒ object: Encodes value of the resource.
decodeResourceValue(buffer, resource) ⇒ Object | string | number | boolean: Decodes value of the resource.
encode(object) ⇒ object: Encodes ant type of instance (Object instance, multiple resources, resources instance, resource).
encodeResourceInstance(resourceInstance) ⇒ object: Encodes resource instance to TLV buffer.
encodeMultipleResourcesTLV(resources) ⇒ object: Encodes multiple resource values to TLV buffer.
encodeResource(resource) ⇒ object: Encodes resource to TLV buffer.
encodeObjectInstance(objectInstance) ⇒ object: Encodes LwM2M object instance to TLV buffer.
encodeObject(object) ⇒ object: Encodes LwM2M object to TLV buffer.
decode(buffer) ⇒ object: Decodes any TLV buffer.
decodeResourceInstance(buffer, resources) ⇒ object: Decodes resource instance.
decodeResourceInstanceValue(buffer, resourceInstance) ⇒ object: Decodes resource instance value
decodeResource(buffer, resource) ⇒ object: Decodes resource.
decodeObjectInstance(buffer, objectInstance) ⇒ object: Decodes object instance from TLV buffer.
decodeObject(buffer, object) ⇒ object: Decodes LwM2M object to TLV buffer.

Device

This class represents device (endpoint).

Kind: global class

Device
- new Device(service, id)
- .getObjects() ⇒ Promise
- .read(path, callback) ⇒ Promise
- .write(path, callback, payload, type) ⇒ Promise
- .execute(path, callback, payload, type) ⇒ Promise
- .observe(path, callback) ⇒ Promise
- .cancelObserve(path) ⇒ Promise

new Device(service, id)

Constructor initiliazes given service object, device's id and starts listening for events emited by service (when device registers, updates, deregisters, sends data), handles "async responses" and emits "register", "update", "deregister" events.

Param	Type	Description
service	`object`	Service object
id	`string`	Endpoint id

Example

const restAPI = require('restserver-api');

const service = new restAPI.Service(serviceOptions);
const device = new restAPI.Device(service, 'deviceId');

device.getObjects() ⇒ `Promise`

Sends request to get all device's objects.

Kind: instance method of Device
Returns: Promise - Promise object with device's objects
Example

device.getObjects().then((resp) => {
  // resp = [ { uri: '/1/0' }, { uri: '/2/0' }, ... ]
}).catch((err) => {
  // err - exception message object or status code
});

device.read(path, callback) ⇒ `Promise`

Sends request to read device's resource data.

Kind: instance method of Device
Returns: Promise - Promise with async response id

Param	Type	Description
path	`string`	Resource path
callback	`function`	Callback which will be called when async response is received

Example

device.read(path, (status, payload) => {
  // status = 200
  // payload = 4RbaAA==
}).then((asyncResponseId) => {
  // asyncResponseId = 1533889157#42f26784-1a8d-4861-36aa-d88f
}).catch((err) => {
  // err - exception object or status code
});

device.write(path, callback, payload, type) ⇒ `Promise`

Sends request to write a value into device's resource.

Kind: instance method of Device
Returns: Promise - Promise with async response id

Param	Type	Default	Description
path	`string`		Resource path
callback	`function`		Callback which will be called when async response is received
payload	`buffer`		Data (optional)
type	`string`	`"application/vnd.oma.lwm2m+tlv"`	Content type (optional)

Example

device.write(path, (status) => {
  // status = 202
}, payload).then((asyncResponseId) => {
  // asyncResponseId = 1533889926#870a3f17-3e21-b6ad-f63d-5cfe
}).catch((err) => {
  // err - exception object or status code
});

device.execute(path, callback, payload, type) ⇒ `Promise`

Sends request to execute device's resource.

Kind: instance method of Device
Returns: Promise - Promise with async response id

Param	Type	Default	Description
path	`string`		Resource path
callback	`function`		Callback which will be called when async response is received
payload	`buffer`		Data (optional)
type	`string`	`"text/plain"`	Content type (optional)

Example

device.execute(path, (status) => {
  // status = 202
}).then((asyncResponseId) => {
  // asyncResponseId = 1533889926#870a3f17-3e21-b6ad-f63d-5cfe
}).catch((err) => {
  // err - exception object or status code
});

device.observe(path, callback) ⇒ `Promise`

Sends request to subscribe to resource.

Kind: instance method of Device
Returns: Promise - Promise with async response id

Param	Type	Description
path	`string`	Resource path
callback	`function`	Callback which will be called when async response is received

Example

device.observe(path, (status, payload) => {
  // status = 200
  // payload = 4RbaAA==
}).then((asyncResponseId) => {
  // asyncResponseId = 1533889157#42f26784-1a8d-4861-36aa-d88f
}).catch((err) => {
  // err - exception object or status code
});

device.cancelObserve(path) ⇒ `Promise`

Sends request to cancel subscriptions.

Kind: instance method of Device
Returns: Promise - Promise with HTTP status code

Param	Type	Description
path	`string`	Resource path

Example

device.cancelObserve(path).then((status) => {
  // status - status code
}).catch((err) => {
  // err - exception object
});

Service

This class represents REST API service.

Kind: global class

Service
- new Service(opts)
- .start(opts) ⇒ Promise
- .stop() ⇒ Promise
- .authenticate() ⇒ Promise
- .registerNotificationCallback() ⇒ Promise
- .deleteNotificationCallback() ⇒ Promise
- .checkNotificationCallback() ⇒ Promise
- .pullNotification() ⇒ Promise
- .getDevices() ⇒ Promise
- .getVersion() ⇒ Promise
- .get(path) ⇒ Promise
- .put(path, argument, type) ⇒ Promise
- .delete(path) ⇒ Promise
- .post(path, argument, type) ⇒ Promise

new Service(opts)

Initializes default configurations. Reconfigures with given options.

Param	Type	Description
opts	`object`	Options object (optional)

Example

const options = {
  // REST server's address
  host: 'http://localhost:8888',
  // CA certificate
  ca: '',
  // authentication (true or false)
  authentication: false,
  username: '',
  password: '',
  // notification polling (true or false)
  polling: false,
  // time between each poll in miliseconds
  interval: 1234,
  // port for socket listener (not relevant if polling is enabled)
  port: 5728,
};
new Service(options);

service.start(opts) ⇒ `Promise`

(Re)starts authentication, socket listener creation and notification callback registration or notification polling processes.

Kind: instance method of Service
Returns: Promise - Promise which fulfills when service is started

Param	Type	Description
opts	`object`	Options object (optional)

Example

service.start().then(() => {
  // started service
}).catch((err) => {
  // err - exception object
});

Example (Passing options object)

const options = {
  // REST server's address
  host: 'http://localhost:8888',
  // CA certificate
  ca: '',
  // authentication (true or false)
  authentication: false,
  username: '',
  password: '',
  // notification polling (true or false)
  polling: false,
  // time between each poll in miliseconds
  interval: 1234,
  // port for socket listener (not relevant if polling is enabled)
  port: 5728,
};
service.start(options);

service.stop() ⇒ `Promise`

Stops receiving and processing events Stops this service and all it's subservices that were started in start(). Cleans up resources

Kind: instance method of Service
Returns: Promise - Promise which fulfills when service is stopped
Example

service.stop().then(() => {
  // stopped service
});

service.authenticate() ⇒ `Promise`

Sends request to authenticate user.

Kind: instance method of Service
Returns: Promise - Promise with authentication data (token and after what time it expires)
Example

service.authenticate().then((resp) => {
  // resp = { access_token: 'token-value', expires_in: 3600 }
}).catch((err) => {
  // err - exception message object or status code
});

service.registerNotificationCallback() ⇒ `Promise`

Sends request to register notification callback.

Kind: instance method of Service
Returns: Promise - Promise which fulfills when notification callback is registered
Example

service.registerNotificationCallback().then(() => {
  // notification callback has been registered
}).catch((err) => {
  // err - exception object or status code
});

service.deleteNotificationCallback() ⇒ `Promise`

Sends request to delete notification callback.

Kind: instance method of Service
Returns: Promise - Promise with HTTP status code
Example

service.deleteNotificationCallback().then((status) => {
  // status - status code
}).catch((err) => {
  // err - exception object
});

service.checkNotificationCallback() ⇒ `Promise`

Sends request to check whether or not notification callback is registered.

Kind: instance method of Service
Returns: Promise - Promise with notification callback data
Example

service.checkNotificationCallback().then((resp) => {
  // resp = { url: 'http://localhost:5728/notification', headers: {} }
}).catch((err) => {
  // err - exception message object or status code
});

service.pullNotification() ⇒ `Promise`

Sends request to get pending/queued notifications.

Kind: instance method of Service
Returns: Promise - Promise with notification data (registrations, deregistrations, updates, async responses)
Example

service.pullNotification().then((resp) => {
  // resp = { registrations: [...], 'reg-updates': [...], ... }
}).catch((err) => {
  // err - exception object
});

service.getDevices() ⇒ `Promise`

Sends request to get all registered endpoints.

Kind: instance method of Service
Returns: Promise - Promise with a list of endpoints
Example

service.getDevices().then((resp) => {
  // resp = [ { name: 'uuid-4567', type: '8dev_3700', ... }, ... ]
}).catch((err) => {
  // err - exception message object or status code
});

service.getVersion() ⇒ `Promise`

Sends request to get REST server version.

Kind: instance method of Service
Returns: Promise - Promise with REST server's version
Example

service.getVersion().then((resp) => {
  // resp = '1.0.0'
}).catch((err) => {
  // err - exception object
});

service.get(path) ⇒ `Promise`

Performs GET requests with given path.

Kind: instance method of Service
Returns: Promise - Promise with data and response object

Param	Type	Description
path	`string`	Request path

Example

service.get(path).then((dataAndResponse) => {
  // dataAndResponse.data - data object
  // dataAndResponse.resp - response object
}).catch((err) => {
  // err - exception object
});

service.put(path, argument, type) ⇒ `Promise`

Performs PUT requests with given path, data and data type.

Kind: instance method of Service
Returns: Promise - Promise with data and response object

Param	Type	Default	Description
path	`string`		Request path
argument	`object`		Data which will be sent (optional)
type	`string`	`"application/vnd.oma.lwm2m+tlv"`	Data type (optional)

service.delete(path) ⇒ `Promise`

Performs DELETE requests with given path.

Kind: instance method of Service
Returns: Promise - Promise with data and response object

Param	Type	Description
path	`string`	Request path

service.post(path, argument, type) ⇒ `Promise`

Performs POST requests with given path, data and data type.

Kind: instance method of Service
Returns: Promise - Promise with data and response object

Param	Type	Default	Description
path	`string`		Request path
argument	`object`		Data which will be sent (optional)
type	`string`	`"application/vnd.oma.lwm2m+tlv"`	Data type (optional)

TYPE

Represents LwM2M variable (identifier) types (OBJECT_INSTANCE, MULTIPLE_RESOURCE, RESOURCE_INSTANCE, RESOURCE).

Kind: global constant

RESOURCE_TYPE

Represents resource type (NONE, BOOLEAN, INTEGER, FLOAT, STRING, OPAQUE).

Kind: global constant

getDictionaryByValue(dictionaryList, keyName, value) ⇒ `Object` | `string` | `number`

Gets dictionary by given name of the key and value.

Kind: global function
Returns: Object | string | number - dictionary

Param	Type	Description
dictionaryList	`object`	Dictionary list.
keyName	`Object` \| `string`	Name of the key
value	`Object` \| `string` \| `number`	Value

encodeResourceValue(resource) ⇒ `object`

Encodes value of the resource.

Kind: global function
Returns: object - buffer - Buffer of encoded value.

Param	Type	Description
resource	`object`	Object which stores resource value and value's type.

Example

const resource = {
 type: TLV.RESOURCE_TYPE.INTEGER,
 value: 1
};

const encodedValue = encodeResourceValue(resource);
// encodedValue = <Buffer 01>

decodeResourceValue(buffer, resource) ⇒ `Object` | `string` | `number` | `boolean`

Decodes value of the resource.

Kind: global function
Returns: Object | string | number | boolean - value - Decoded value in specified type

Param	Type	Description
buffer	`object`	Buffer which will be decoded.
resource	`object`	Object which stores resource value's type.

Example

const buffer = Buffer.from([0x01]);
const resource = {
  type: TLV.RESOURCE_TYPE.INTEGER,
};

const decodedValue = decodeResourceValue(buffer, resource);
// decodedValue = 1

encode(object) ⇒ `object`

Encodes ant type of instance (Object instance, multiple resources, resources instance, resource).

Kind: global function
Returns: object - buffer - encoded TLV buffer.

Param	Type	Description
object	`object`	object which stores type, identifier and value.

Example

const resource = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: true
};

const encoded = encode({
  type: TYPE.RESOURCE,
  identifier: resource.identifier,
  value: encodeResourceValue(resource),
});
// encoded = <Buffer e1 16 da 01>

encodeResourceInstance(resourceInstance) ⇒ `object`

Encodes resource instance to TLV buffer.

Kind: global function
Returns: object - buffer - Buffer in TLV format

Param	Type	Description
resourceInstance	`object`	Object which stores resource identifier, value and it's type.

Example

const resourceInstance = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: true
};

const encoded = encodeResourceInstance(resourceInstance);
// encoded = <Buffer e1 16 da 01>

encodeMultipleResourcesTLV(resources) ⇒ `object`

Encodes multiple resource values to TLV buffer.

Kind: global function
Returns: object - buffer - TLV buffer.

Param	Type	Description
resources	`object`	Object which stores identifier, resource type, and multiple values.

Example

const resources = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: [true, false]
};

const encoded = encodeMultipleResources(resources);
// encoded = <Buffer a6 16 da 41 00 01 41 01 00>

encodeResource(resource) ⇒ `object`

Encodes resource to TLV buffer.

Kind: global function
Returns: object - buffer - TLV buffer.

Param	Type	Description
resource	`object`	Object which stores resource identifier, type and value.

Example

const resource = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
  value: true
};

const encoded = encodeResourcez(resource);
// encoded = <Buffer e1 16 da 01>

encodeObjectInstance(objectInstance) ⇒ `object`

Encodes LwM2M object instance to TLV buffer.

Kind: global function
Returns: object - buffer - TLV buffer.

Param	Type	Description
objectInstance	`object`	LwM2M object.

Example

const objectInstance = {
  identifier: 0,
  resources: [
    {
      identifier: 5815,
      type: TLV.RESOURCE_TYPE.FLOAT,
      value: 999.99
    }
  ]
};

const encoded = encodeObjectInstanceTLV(objectInstance);
// encoded = <Buffer 07 00 e4 16 b7 44 79 ff 5c>

encodeObject(object) ⇒ `object`

Encodes LwM2M object to TLV buffer.

Kind: global function
Returns: object - buffer - TLV buffer.

Param	Type	Description
object	`object`	LwM2M object.

Example

const object = {
  identifier: 3305,
  objectInstances: [{
    identifier: 0,
    resources: [
      {
        identifier: 5815,
        type: TLV.RESOURCE_TYPE.FLOAT,
        value: 999.99
      }
    ]
  }]
};

const encoded = encodeObject(object);
// encoded = <Buffer 07 00 e4 16 b7 44 79 ff 5c>

decode(buffer) ⇒ `object`

Decodes any TLV buffer.

Kind: global function
Returns: object - object - Decoded object.

Param	Type	Description
buffer	`object`	encoded TLV buffer.

Example

const buffer = Buffer.from([0xe1, 0x16, 0xda, 0x01]);

const decoded = TLV.decode(buffer);
// decoded = { type: 3, identifier: 5850, value: <Buffer 01>, tlvSize: 4 }

decodeResourceInstance(buffer, resources) ⇒ `object`

Decodes resource instance.

Kind: global function
Returns: object - decodedResource - Object which stores resource identifier, tlvSize resource type and value.

Param	Type	Description
buffer	`object`	Resource instance TLV buffer.
resources	`object`	Object which stores resource identifier and resource type.

Example

const buffer = Buffer.from([0x61, 0x16, 0xda, 0x01]);
const resources = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
};

const decoded = decodeResourceInstance(buffer, resources);
// decoded = { identifier: 5850, tlvSize: 4, type: TLV.RESOURCE_TYPE.BOOLEAN, value: true }

decodeResourceInstanceValue(buffer, resourceInstance) ⇒ `object`

Decodes resource instance value

Kind: global function
Returns: object - decodedResourceValue - Decoded resource value

Param	Type	Description
buffer	`object`	Resource instance value TLV buffer
resourceInstance	`object`	Object which stores resource type

Example

const buffer = Buffer.from([0x01]);
const resourceInstance = {
  type: TLV.RESOURCE_TYPE.INTEGER,
};

const decoded = decodeResourceInstance(buffer, resources);
// decoded = 1

decodeResource(buffer, resource) ⇒ `object`

Decodes resource.

Kind: global function
Returns: object - buffer - Decoded resource.

Param	Type	Description
buffer	`object`	Resource TLV buffer
resource	`object`	Object which stores identifier and resource type.

Example

const buffer = Buffer.from([0xe1, 0x16, 0xda, 0x01]);
const resource = {
  identifier: 5850,
  type: TLV.RESOURCE_TYPE.BOOLEAN,
};

const decoded = decodeResource(buffer, resource);
// decoded = { identifier: 5850, type: 1, value: true, tlvSize: 4 }

decodeObjectInstance(buffer, objectInstance) ⇒ `object`

Decodes object instance from TLV buffer.

Kind: global function
Returns: object - object - Decoded object instance.

Param	Type	Description
buffer	`object`	TLV buffer.
objectInstance	`object`	Object which stores object instance identifier and resources.

Example

const buffer = Buffer.from([0x07, 0x00, 0xe4, 0x16, 0xb7, 0x44, 0x79, 0xff, 0x5c]);
const objectInstance: {
  identifier: 0,
  resources: [
    {
      identifier: 5815,
      type: TLV.RESOURCE_TYPE.FLOAT,
    },
  ]
};

const decoded = decodeObjectInstance(buffer, objectInstance);
// decoded = { identifier: 0, resources: [ { identifier: 5815, type: 3 } ] }

decodeObject(buffer, object) ⇒ `object`

Decodes LwM2M object to TLV buffer.

Kind: global function
Returns: object - object - Decoded object.

Param	Type	Description
buffer	`object`	TLV buffer.
object	`object`	Object which stores object instances with their resources.

Example

const buffer = Buffer.from([0x07, 0x00, 0xe4, 0x16, 0xb7, 0x44, 0x79, 0xff, 0x5c]);
const object = {
  identifier: 3305,
  objectInstances: [{
    identifier: 0,
    resources: [
      {
        identifier: 5815,
        type: TLV.RESOURCE_TYPE.FLOAT,
      },
    ]
  }]
};

const decoded = decodeObject(buffer, object);
/*
decoded = {
  identifier: 3305,
  objectInstances: [
    {
      identifier: 0,
      resources: [
        {
          identifier: 5815,
          type: 3,
          value: 999.989990234375,
          tlvSize: 7
        }
      ]
    }
  ]
}
*/

Files

README.md

Latest commit

History

README.md

File metadata and controls

restserver-api

Classes

Constants

Functions

Device

new Device(service, id)

device.getObjects() ⇒ Promise

device.read(path, callback) ⇒ Promise

device.write(path, callback, payload, type) ⇒ Promise

device.execute(path, callback, payload, type) ⇒ Promise

device.observe(path, callback) ⇒ Promise

device.cancelObserve(path) ⇒ Promise

Service

new Service(opts)

service.start(opts) ⇒ Promise

service.stop() ⇒ Promise

service.authenticate() ⇒ Promise

service.registerNotificationCallback() ⇒ Promise

service.deleteNotificationCallback() ⇒ Promise

service.checkNotificationCallback() ⇒ Promise

service.pullNotification() ⇒ Promise

service.getDevices() ⇒ Promise

service.getVersion() ⇒ Promise

service.get(path) ⇒ Promise

service.put(path, argument, type) ⇒ Promise

service.delete(path) ⇒ Promise

service.post(path, argument, type) ⇒ Promise

TYPE

RESOURCE_TYPE

getDictionaryByValue(dictionaryList, keyName, value) ⇒ Object | string | number

encodeResourceValue(resource) ⇒ object

decodeResourceValue(buffer, resource) ⇒ Object | string | number | boolean

encode(object) ⇒ object

encodeResourceInstance(resourceInstance) ⇒ object

encodeMultipleResourcesTLV(resources) ⇒ object

encodeResource(resource) ⇒ object

encodeObjectInstance(objectInstance) ⇒ object

encodeObject(object) ⇒ object

decode(buffer) ⇒ object

decodeResourceInstance(buffer, resources) ⇒ object

decodeResourceInstanceValue(buffer, resourceInstance) ⇒ object

decodeResource(buffer, resource) ⇒ object

decodeObjectInstance(buffer, objectInstance) ⇒ object

decodeObject(buffer, object) ⇒ object

device.getObjects() ⇒ `Promise`

device.read(path, callback) ⇒ `Promise`

device.write(path, callback, payload, type) ⇒ `Promise`

device.execute(path, callback, payload, type) ⇒ `Promise`

device.observe(path, callback) ⇒ `Promise`

device.cancelObserve(path) ⇒ `Promise`

service.start(opts) ⇒ `Promise`

service.stop() ⇒ `Promise`

service.authenticate() ⇒ `Promise`

service.registerNotificationCallback() ⇒ `Promise`

service.deleteNotificationCallback() ⇒ `Promise`

service.checkNotificationCallback() ⇒ `Promise`

service.pullNotification() ⇒ `Promise`

service.getDevices() ⇒ `Promise`

service.getVersion() ⇒ `Promise`

service.get(path) ⇒ `Promise`

service.put(path, argument, type) ⇒ `Promise`

service.delete(path) ⇒ `Promise`

service.post(path, argument, type) ⇒ `Promise`

getDictionaryByValue(dictionaryList, keyName, value) ⇒ `Object` | `string` | `number`

encodeResourceValue(resource) ⇒ `object`

decodeResourceValue(buffer, resource) ⇒ `Object` | `string` | `number` | `boolean`

encode(object) ⇒ `object`

encodeResourceInstance(resourceInstance) ⇒ `object`

encodeMultipleResourcesTLV(resources) ⇒ `object`

encodeResource(resource) ⇒ `object`

encodeObjectInstance(objectInstance) ⇒ `object`

encodeObject(object) ⇒ `object`

decode(buffer) ⇒ `object`

decodeResourceInstance(buffer, resources) ⇒ `object`

decodeResourceInstanceValue(buffer, resourceInstance) ⇒ `object`

decodeResource(buffer, resource) ⇒ `object`

decodeObjectInstance(buffer, objectInstance) ⇒ `object`

decodeObject(buffer, object) ⇒ `object`