hello.nrfcloud.com/map Protocols

Documents the communication protocol between devices, the hello.nrfcloud.com/map backend and 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 to fully qualified LwM2M object representations which can then be processed further, e.g. stored in a database.

This allows the hello.nrfcloud.com/map 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. Time is a signed integer representing the number of seconds since Jan 1 st, 1970 in the UTC time zone.
• Objects must be Multiple instance.
• Objects must be Optional.
• 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.
• SenML records may be a Time only, in case it is sufficient to express the object as a combination of InstanceID and timestamp, for example in case of the Button Press (14220) object.

Model definition rules

• device models are identified using a model name, for example kartverket-vasstandsdata
• a README.md must be provided that describes the model

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

Usage

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

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