node-lwm2m

node-lwm2m is an implementation of the Open Mobile Alliance's Lightweight M2M protocol (LWM2M).

LWM2M is a profile for device services based on CoAP (RFC 7252). LWM2M defines a simple object model and a number of interfaces and operations for device management. See an overview of the protocol here.

Object Model

The OMA LWM2M object model is based on a simple 2 level class hierarchy consisting of Objects and Resources:

• A Resource is a REST endpoint, allowed to be a single value or an array of values of the same data type.

• An Object is a resource template and container type that encapsulates a set of related resources. An LWM2M Object represents a specific type of information source; for example, there is a LWM2M Device Management object that represents a network connection, containing resources that represent individual properties like radio signal strength.

Source: https://tools.ietf.org/html/draft-ietf-core-resource-directory

Object Registry

See IPSO Registry or OMNA Registry for Object and Resource definitions.

Install

npm install --save lwm2m

Synopsis

var server = require('lwm2m').createServer();

server.on('register', function(params, accept) {
  setImmediate(function() {
    server
    .read(params.ep, '3/0')
    .then(function(device) {
      console.log(JSON.stringify(device, null, 4));
    })
  });
  accept();
});

server.listen(5683);

Contribute

Please report bugs via the github issue tracker.

API

Table of Contents

• schemas
• createServer
• bootstrap#createServer
• Resource
• Schema
  • validate
• Server
  • read
  • write
  • execute
  • discover
  • writeAttributes
  • create
  • delete
  • observe
  • cancel
• bootstrap#Server
  • write
  • delete
  • finish
• Registry
  • _find
  • _get
  • _save
  • _update
  • _delete

schemas

Schemas for OMA-defined objects. See oma.

createServer

Returns Server object

bootstrap#createServer

Returns bootstrap#Server object

Resource

Schema resource type definition

Type: Object

Properties

• type ("String" | "Integer" | "Float" | "Boolean" | "Opaque" | "Time" | ["type"])
• id number Resource ID
• required boolean? resource is mandatory. Defaults to false
• enum Array?
• range object?
  • range.min number
  • range.max number

Schema

Schema constructor.

An Schema describes the shape of an LwM2M Object and the type of its resources. Schemas are used throghout the API for generating/parsing payloads from/to JavaScript values.

See oma directory for default definitions. See also thermostat.js for an example of a composite schema.

Note

LwM2M types will be coerced to JavaScript types and viceversa, e.g. Time will return a Date(), Opaque a Buffer(), and Integer/Float a number.

Parameters

• resources Object<string, Resource>

Examples

// IPSO light controller
var lightControlSchema = new Schema({
  onOff: {
    type: 'Boolean',
    id : 5850,
    required: true
  },
  dimmer: {
    type: 'Integer',
    id: 5851,
    range: { min: 0, max: 100 }
  },
  units: {
    type: 'String',
    id: 5701,
  }
});

// an object literal matching the schema above
var lightControl = {
  onOff: true,
  dimmer: 40,
}

// Bad schema
var schema = new Schema({
  a: { type: 'String', id: 0 },
  b: { type: 'Error', id: 1 },
}); // throws TypeError

• Throws any Will throw an error if fails to validate

validate

validates obj with schema.

Parameters

• obj Object

Examples

var schema = new Schema({
  a: { type: String, id: 0 },
  b: { type: Buffer, id: 1 },
});

schema.validate({
  a: 'foo',
  b: Buffer.from('bar'),
}); // OK

schema.validate({
  a: 'foo',
  b: 'bar',
}); // Throws error

• Throws any Will throw an error if fails to validate

Server

Extends EventEmitter

Server constructor.

Events:

• register: device registration request.
• update: device registration update.
• unregister: device unregistration.

Parameters

• options Object?
  • options.type string IPv4 (udp4) or IPv6 (udp6) connections (optional, default 'upd6')
  • options.piggybackReplyMs number milliseconds to wait for a piggyback response (optional, default 50)
  • options.registry Registry impl. of CoRE Resource Directory (optional, default Registry)

read

Read path on device with endpoint name endpoint. The optional callback is given the two arguments (err, res), where res is parsed using schema.

Note:

If no schema is provided will return a Buffer if the payload is TLV-encoded or opaque, or an String otherwise.

Parameters

• endpoint String client endpoint name
• path String either an LWM2M Object instance or resource
• options Object?
  • options.format string media type. (optional, default 'text')
  • options.schema Schema defining resources.
• callback Function?

Examples

var schema = Schema({
  test: { id: 1, type: Number }
});

var options = { 
  schema: schema, 
  format: 'json',
};

server.read('test', '/1024/11', options, function(err, res) {
  assert(res.hasOwnProperty('test'));
  assert(typeof res.test == 'number');
});

Returns Promise<(Object | string | Buffer | number)> a promise of the eventual value

write

Write value into path of device with endpoint name endpoint. For writing Object Instances, an schema is required.

Note:

schemas can be globally added to lwm2m.schemas.

Parameters

• endpoint String client endpoint name
• path String
• value (Object | String | Number | Buffer)
• options Object
  • options.format string media type. (optional, default 'tlv')
  • options.schema Schema? schema to serialize value.
• callback Function?

Examples

var schema = Schema({
  foo : { 
    id: 5, 
    type: 'String' 
  },
  bar : { 
    id: 6, 
    type: 'Number' 
  },
});

var options = { 
  schema: schema, 
  format: 'json',
};

var value = {
  foo: 'test',
  bar: 42,
};

var promise = server.write('test', '/42/0', value, options)
var promise = server.write('test', '/42/0/5', 'test')
var promise = server.write('test', '/42/0/6', 42)

// add schema for Object ID 42 globally.
lwm2m.schemas[42] = schema;

var promise = server.write('test', '/42/0', value)

Returns Promise

execute

Makes an Execute operation over the designed resource ID of the selected device.

Parameters

• endpoint String client endpoint name
• path String
• value String
• callback Function

Returns Promise

discover

Execute a discover operation for the selected resource.

Parameters

• endpoint String client endpoint name
• path String
• callback Function

Returns Promise<string> a promise with an strng in link-format

writeAttributes

Write attributes into path of endpoint endpoint.

Parameters

• endpoint String client endpoint name
• path String
• attributes Object
• callback Function?

Examples

var attr = {
  "pmin": 5,
  "pmax": 10
};

server.writeAttributes('dev0', '3303/0/5700', attr, function(err, res) {
   assert.ifError(err);
});

Returns Promise

create

Create a new LWM2M Object for path, where path is an Object ID.

Parameters

• endpoint String client endpoint name
• path String
• value (Object | String | Number | Buffer)
• options Object?
• callback Function?

Returns Promise

delete

Deletes the LWM2M Object instance in path of endpoint endpoint

Parameters

• endpoint String client endpoint name
• path String
• callback Function?

Returns Promise

observe

Observe changes in path of device with endpoint name endpoint. The notification behaviour, e.g. periodic or event-triggered reporting, is configured with the writeAttributes method. The callback is given the two arguments (err, stream), where stream is a Readable Stream. To stop receiving notifications close() the stream and (optionally) call cancel() on the same endpoint and path and .

Parameters

• endpoint String client endpoint name
• path String
• options
  • options.format string media type. (optional, default 'text')
  • options.schema Schema defining resources.
• callback Function?

Examples

server.observe('dev0', '/1024/10/1', function(err, stream) {
  stream.on('data', function(value) {
    console.log('new value %s', value);
  });

  stream.on('end', function() {
    console.log('stopped observing');
  });
});

Returns Promise

cancel

Cancel an observation for path of device endpoint.

Parameters

• endpoint String client endpoint name
• path String
• callback Function?

Returns Promise

bootstrap#Server

Extends EventEmitter

Server constructor.

Events

• bootstrapRequest: device bootstrap request.

Parameters

• options Object?
  • options.type string IPv4 (udp4) or IPv6 (udp6) connections (optional, default 'upd6')
  • options.piggybackReplyMs number milliseconds to wait for a piggyback response (optional, default 50)

Examples

var bootstrap = require('lwm2m').bootstrap;
var server = bootstrap.createServer();

server.on('error', function(err) {
  throw err;
});

server.on('close', function() {
  console.log('server is done');
});

server.on('bootstrapRequest', function(params, accept) {
  console.log('endpoint %s contains %s', params.ep, params.payload);
  accept();
});

// the default CoAP port is 5683
server.listen();

write

Makes a Write operation over the designed resource ID of the selected device.

Parameters

• endpoint String client endpoint name
• path String
• value (Object | String | Number | Buffer)
• options Object?
  • options.format string media type.
  • options.schema Schema schema to serialize value when an object.
• callback Function?

Examples

var schema = Schema({
  foo : { 
    id: 5, 
    type: 'String' 
  },
  bar : { 
    id: 6, 
    type: 'Number' 
  },
});

var options = { 
  schema: schema, 
  format: 'json',
};

var value = {
  foo: 'test',
  bar: 42,
};

var promise = server.write('test', '/42/3', value, options)

Returns Promise

delete

Deletes the LWM2M Object instance in path of endpoint endpoint

Parameters

• endpoint String client endpoint name
• path String
• callback Function?

Returns Promise

finish

Terminate the Bootstrap Sequence previously initiated

Parameters

• endpoint String client endpoint name
• callback Function?

Returns Promise

Registry

Extends EventEmitter

Registry for clients. Default implementation is in-memory.

For production use, extend Registry class and give new implementations to _get, _find, _save, _update and _delete.

See examples for a MongoDB-backed registry.

_find

get client by endpoint name

Parameters

• endpoint string
• callback Function callback is given the two arguments (err, client)

_get

get client by location in the registry

Parameters

• location string
• callback Function callback is given the two arguments (err, client)

_save

store a new client in the registry

Parameters

• client Object
• callback Function callback is given the two arguments (err, location)

_update

update a client in the registry

Parameters

• location string
• params Object
• callback Function callback is given the two arguments (err, location)

_delete

delete client from the registry

Parameters

• location string
• callback Function callback is given the two arguments (err, client)