https://github.com/hello-nrfcloud/proto-map
Documents the communication protocol between devices, the hello.nrfcloud.com/map backend and web application
https://github.com/hello-nrfcloud/proto-map
cellular-iot hello-nrfcloud hello-nrfcloud-map iot lwm2m nordicsemiconductor nrf-asset-tracker
Last synced: about 1 month ago
JSON representation
Documents the communication protocol between devices, the hello.nrfcloud.com/map backend and web application
- Host: GitHub
- URL: https://github.com/hello-nrfcloud/proto-map
- Owner: hello-nrfcloud
- License: bsd-3-clause
- Created: 2023-11-03T09:57:48.000Z (over 2 years ago)
- Default Branch: saga
- Last Pushed: 2026-05-03T01:55:50.000Z (about 2 months ago)
- Last Synced: 2026-05-03T03:35:44.584Z (about 2 months ago)
- Topics: cellular-iot, hello-nrfcloud, hello-nrfcloud-map, iot, lwm2m, nordicsemiconductor, nrf-asset-tracker
- Language: TypeScript
- Homepage: https://hello.nrfcloud.com
- Size: 2.78 MB
- Stars: 0
- Watchers: 1
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# `hello.nrfcloud.com/map` Protocols [](https://www.npmjs.com/package/@hello.nrfcloud.com/proto-map)
[](https://github.com/hello-nrfcloud/proto-map/actions/workflows/build-and-publish.yaml)
[](https://github.com/semantic-release/semantic-release)
[](https://renovatebot.com)
[](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional)
[](https://github.com/prettier/prettier/)
[](https://github.com/typescript-eslint/typescript-eslint)
Documents the communication protocol between devices, the
`hello.nrfcloud.com/map` backend and web application.
The [`lwm2m`](./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)](./lwm2m/14201.xml) will place the device's location on
the map).
Devices publish LwM2M objects using
[SenML](https://datatracker.ietf.org/doc/html/rfc8428) directly, which needs to
map to the defined LwM2M objects ([example](./senml/SenMLSchema.spec.ts)).
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/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 `..`, 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`](./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](https://openmobilealliance.org/release/LightweightM2M/V1_1_1-20190617-A/OMA-TS-LightweightM2M_Core-V1_1_1-20190617-A.pdf):
`bn` and `n` fields are combined to form the unique identifier for a resource
in the form of `////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](./lwm2m/14220.xml).
### Model definition rules
- **device models** are identified using a model name, for example
`kartverket-vasstandsdata`
- a [`README.md`](./models/kartverket-vasstandsdata/README.md) must be provided
that describes the model
The conformity to the rules is checked using the script
[`./models/check-model-rules.ts`](./models/check-model-rules.ts).
## Usage
```bash
npm i --save-exact @hello.nrfcloud.com/proto-map
```
## Setup
Install the dependencies:
```bash
npm ci
```
Install [xmllint](https://github.com/GNOME/libxml2).
## Run tests
```bash
npm test
```
## Update generated code
```bash
npx tsx generator/lwm2m.ts
npx tsx generator/models.ts
npx tsx generator/types.ts
```