node-lwm2m

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

What is 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

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)

lwm2m Release 0.13.0

Release 0.13.0 Toggle Dropdown 0.13.0 0.12.0 0.11.0 0.10.0 0.9.1 0.9.0 0.8.2 0.8.1 0.8.0 0.7.0

Documentation

node-lwm2m

Object Model

Object Registry

Install

Synopsis

Contribute

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

Stats

Development practices

Releases

Contributors

lwm2m
Release 0.13.0

Release 0.13.0

0.13.0

0.12.0

0.11.0

0.10.0

0.9.1

0.9.0

0.8.2

0.8.1

0.8.0

0.7.0