@hello.nrfcloud.com/proto-lwm2m

hello.nrfcloud.com LwM2M Protocols

Documents the LwM2M communication protocol between devices, the hello.nrfcloud.com backend and the web application.

The lwm2m folder contains the LwM2M objects that devices publish.

LwM2M object definitions are shared between models and can be re-used. Some objects provide special behavior (for example object 14201 (Geolocation) will place the device's location on the map).

Devices publish LwM2M objects using SenML directly, which needs to map to the defined LwM2M objects (example).

The SenML payload will be [expanded](./senml/senMLtoLwM2M.spec.ts] to fully qualified LwM2M object representations which can then be processed further, e.g. stored in a database.

This allows the hello.nrfcloud.com web application to visualize this data in a meaningful way to users without the need for custom implementation.

LwM2M rules

• LWM2MVersion must be 1.1
• LwM2M objects are defined in the ID range from 14200 to 15000 (non-inclusively).
• The URN must have the prefix urn:oma:lwm2m:x:.
• The ObjectVersion must be appended if it is not 1.0, which is the default.
• All objects must define one Time property.
• Objects must be Multiple instance.
• Objects must be Optional.
• Resources must be Single instance. Multiple could be useful in some cases, e.g. IP addresses, but until it is really needed, we do not support it.
• Resources should only be marked as mandatory in case they must be published together (e.g. latitude and longitude). This allows devices to only update the values that have changed.
• RangeEnumeration is only supported for Float and Integer and must be specified as <min>..<max>, where min must be smaller than max and both must be a number.
• Objlnk resource type is not supported

The conformity to the rules is checked using the script ./lwm2m/check-lwm2m-rules.ts.

SenML rules

• The implementation follows the recommendation outline in section 7.4.5. of the LwM2M v1.1.1 Technical Specification: bn and n fields are combined to form the unique identifier for a resource in the form of /<object ID>/<object instance ID>/<resource ID>/0. The resource instance ID 0 is always appended, because multiple resource instances are not supported right now.
• Use the custom property blv to specify the object version, 1.0 is the default and should not be specified.
• Timestamps are to be expressed in the base time property bt and are mapped to the LwM2M object's timestamp property and must not be send as a property.

Model transform definitions

Optionally, a set of JSONata expression can be defined per model which allows to convert from the data format that is published by the devices to the SenML data format used to describe LwM2M objects (example mapping.

Model definition rules

• device models are identified using a model name, for example PCA20035+solar
• a README.md must be provided that describes the model
• transforms may define transforms that convert the data sent by the device using JSONata for JSON payloads in one or more Markdown files (Example):
  • The Match Expression the must evaluate to true for the Transform Expression to be applied to the input message
  • an Input Example and a Result Example must be supplied to validate the expression
  • The result of the Transform Expression must be SenML according to the rules outlined below.

The conformity to the rules is checked using the script ./models/check-model-rules.ts.

Usage

npm i --save-exact @hello.nrfcloud.com/proto-lwm2m

Setup

Install the dependencies:

npm ci

Install xmllint.

Run tests

npm test

Update generated code

npx tsx generator/lwm2m.ts
npx tsx generator/models.ts
npx tsx generator/types.ts