Library for developing servers and client of OMA Lightweight M2M
npm install lwm2m[![build status][travis-image]][travis-url]
[![coverage status][coveralls-image]][coveralls-url]

[travis-image]: https://img.shields.io/travis/moleike/node-lwm2m/develop.svg
[travis-url]: https://travis-ci.org/moleike/node-lwm2m
[appveyor-image]: https://img.shields.io/appveyor/ci/moleike/node-lwm2m/develop.svg
[appveyor-url]: https://ci.appveyor.com/project/moleike/node-lwm2m
[coveralls-url]: https://coveralls.io/github/moleike/node-lwm2m?branch=develop
[coveralls-image]: https://img.shields.io/coveralls/moleike/node-lwm2m/develop.svg
[node-lwm2m][self] 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][coap]). LWM2M defines a simple object model and a number of interfaces and operations for device management. See an overview of the protocol [here][lwm2m].
[self]: https://github.com/moleike/node-lwm2m.git
[coap]: https://tools.ietf.org/html/rfc7252
[lwm2m]: http://www.openmobilealliance.org/wp/overviews/lightweightm2m_overview.html
#### 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:
#### Object Registry
See [IPSO Registry][ipso] or [OMNA Registry][omna] for Object and Resource definitions.
[ipso]: https://github.com/IPSO-Alliance/pub/tree/master/reg/xml
[omna]: http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html
npm install --save lwm2m
``js
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);
`
Please report bugs via the
github issue tracker.
#### 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 for OMA-defined objects.
See oma.
Returns Server object
Returns bootstrap#Server object
Schema resource type definition
Type: Object
Properties
- type ("String" \| "Integer" \| "Float" \| "Boolean" \| "Opaque" \| "Time" | \["type"]) id
- number Resource IDrequired
- boolean? resource is mandatory. Defaults to falseenum
- Array? range
- object? range.min
- number range.max
- number
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
`javascript
// 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
`javascript
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
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(err, res)
the two arguments , where res is parsed using schema.
Note:
_If no schema is provided will return a Buffer if the payload is TLV-encodedString
or opaque, or an otherwise._
Parameters
- endpoint String client endpoint namepath
- String either an LWM2M Object instance or resourceoptions
- Object? options.format
- string media type. (optional, default 'text')options.schema
- Schema defining resources.callback
- Function?
Examples
`javascript
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 namepath
- 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
`javascript
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 namepath
- String value
- String callback
- Function
Returns Promise
#### discover
Execute a discover operation for the selected resource.
Parameters
- endpoint String client endpoint namepath
- 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 namepath
- String attributes
- Object callback
- Function?
Examples
`javascript
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 namepath
- 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 namepath
- String callback
- Function?
Returns Promise
#### observe
Observe changes in path of device with endpoint name endpoint. writeAttributes
The notification behaviour, e.g. periodic or event-triggered reporting, is configured with the method. The callback is given the two arguments (err, stream), stream
where is a Readable Stream. To stop receiving notifications close() the streamcancel()
and (optionally) call on the same endpoint and path and .
Parameters
- endpoint String client endpoint namepath
- String options
- options.format
- string media type. (optional, default 'text')options.schema
- Schema defining resources.callback
- Function?
Examples
`javascript
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 namepath
- String callback
- Function?
Returns Promise
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
`javascript
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 namepath
- 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
`javascript
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 namepath
- String callback
- Function?
Returns Promise
#### finish
Terminate the Bootstrap Sequence previously initiated
Parameters
- endpoint String client endpoint namecallback
- Function?
Returns Promise
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(err, client)
the two arguments
#### \_get
get client by location in the registry
Parameters
- location string callback
- Function callback is given(err, client)
the two arguments
#### \_save
store a new client in the registry
Parameters
- client Object callback
- Function callback is given(err, location)
the two arguments
#### \_update
update a client in the registry
Parameters
- location string params
- Object callback
- Function callback is given(err, location)
the two arguments
#### \_delete
delete client from the registry
Parameters
- location string callback
- Function callback is given(err, client)`
the two arguments