CANDY-LINE
Node-RED node for OMA LwM2M
This node offers OMA LwM2M client functionalities and allows you to create your own OMA LwM2M client applications on top of Node-RED.
This node internally spawns a wakatiwaiclient process, which is a revised version of Eclipse Wakaama executable, and starts inter-process communication (IPC) over stdin and stdout. The wakatiwaiclient executable is slightly different from Wakaama's implementation, some of management objects are stripped. This node allows you to describe your own management objects as well.
When the parent process (i.e. Node-RED) exits, this node tries to emit a De-registration message to LwM2M server so that the server knows the client is gone.
This node restarts a new process when the child process exits after a given interval time passes.
CoAP over DTLS is supported but disabled by default. Users are able to enable DTLS if necessary. However, supported security mechanism is only pre-shared key(PSK). RPK and X.509 are not supported.
The supported message format is TLV rather than JSON
Security Notice:
Keep in mind that the inter-process communication over stdin/stdio is NOT encrypted and does NOT have any authentication mechanism.
Features
Installed Nodes
lwm2m client... a LwM2M client configuration node, having LwM2M server host, port and other connection settings as well as custom management objectslwm2m client in... a Node-RED node emitting LwM2M server events and/or internal object query resultslwm2m client out... a Node-RED node accepting a Write/Execute operation message from the input port
All errors are propagated to Catch-all node.
The input and output nodes show the following connection status.
- bootstrap required
- bootstrapping
- register required
- registering
- connected
- disconnected
- error
- timeout
- subscribed - only for
lwm2m client innode withSubscribe LwM2M Object Eventschecked
Supported LwM2M operations
readwriteexecuteobservediscovercreatedelete
Bundled Objects
The following objects are implemented in Javascript. They can be overlaid with user defined object JSON (see below).
Security ObjectServer ObjectAccess Control ObjectDevice Object
Security Notice) The project depends on systeminformation package to collect system information. This package is excellent but it can expose sensitive information like serial number, device model and OS version to a LwM2M server. In order to avoid unexpected exposure to a public sandbox server, Hide sensitive device info. property is checked by default. So you need to uncheck it prior to sending entire device information from the node.
User's Custom Objects and Object Overlay
This node allows you to create new objects and overlay bundled objects (not predefined objects).
With the powerful Node-RED JSON editor, you can easily manipulate your own management objects.
Management Object JSON format
† Not compatible with LwM2M JSON data format
{
"0": { => Object ID (M)
"0": { => Instance ID (M)
"0": { => Resource ID (M)
"type": "...", => Resource Type (see below) (M)
"acl": "...", => Resource ACL (see below) (O)
"sensitive": true, => true if the value is sensitive (O)
"value": "..." => Resource Value (O)
}
}
}
}Resource Types
Supported resource types are as follows:
STRING... StringOPAQUE... Buffer (byte array)INTEGER... 64bit integerFLOAT... doubleBOOLEAN... boolean (STRINGvalue1,INTEGERvalue1, andOPAQUE1st byte1are all translated intotrue)OBJECT_LINK... Object LinkMULTIPLE_RESOURCE... Resource ArrayFUNCTION... This is NOT a LwM2M Resource Type. Used for definingexecuteoperation Resource
Resource Type JSON format
STRING
{
"type": "STRING",
"value": "Lorem ipsum"
}or
"Lorem ipsum"OPAQUE
{
"type": "OPAQUE",
"value": "Lorem ipsum"
}or
{
"type": "OPAQUE",
"value": "base64:TG9yZW0gaXBzdW0="
}or
{
"type": "OPAQUE",
"value": "hex:4c6f72656d20697073756d"
}or
{
"type": "OPAQUE",
"value": [76,111,114,101,109,32,105,112,115,117,109]
}or
{
"type": "OPAQUE",
"value": {
"type": "Buffer",
"data": [76,111,114,101,109,32,105,112,115,117,109]
}
}INTEGER
{
"type": "INTEGER",
"value": 1234567890
}or
1234567890- The
"value"property value is assumed as an empty packet by default when the property is missing.
FLOAT
{
"type": "FLOAT",
"value": 987654.321
}or
987654.321- The
"value"property value is assumed as an empty packet by default when the property is missing.
BOOLEAN
{
"type": "BOOLEAN",
"value": false
}or
true- The
"value"property value is assumed as an empty packet by default when the property is missing.
OBJECT_LINK
{
"type": "OBJECT_LINK",
"value": {
"objectId": 999,
"objectInstanceId": 0
}
}MULTIPLE_RESOURCE
The type is a collection having Resource Instance ID and Resource value pairs.
{
"type": "MULTIPLE_RESOURCE",
"value": {
"100": 999,
"101": true,
"999": {
"type": "FLOAT",
"value": 987654.321
}
}
}If the Resource Instance ID starts with "0" and its following IDs are 1,2,3... (increases by 1), you can provide a JSON Array like this.
{
"type": "MULTIPLE_RESOURCE",
"value": [
123,
false,
{
"type": "FLOAT",
"value": 1234.567
}
]
}This is equivalent to:
{
"type": "MULTIPLE_RESOURCE",
"value": {
"0": 123,
"1": false,
"2": {
"type": "FLOAT",
"value": 1234.567
}
}
}FUNCTION
This type is out of OMA LwM2M specification scope. Used for defining an executable resource data. value property is always ignored and acl is always assumed as E(other values are silently ignored).
{
"type": "FUNCTION"
}ACL
ACL characters and allowed operations are shown below.
R... Read, Observe, Discover, Write-AttributesW... WriteE... ExecuteD... DeleteC... Create
Note that LwM2M Bootstrap server will try to remove all predefined objects during bootstrapping process. Set ACL properly if you'd like to preserve your objects.
Global predefined objects and object definitions
You can add your own systemwide custom objects by describing them in your settings.js or RED.settings objects.
You can also add your own object definition to objectDefinitions property.
With objectDefinitions property, you can provide a collection of a template resource object, which will be copied to a new resource object when creating it.
Here's an example for providing the predefined manufacturer name.
settings.js
{
lwm2m: {
objects : {
'3': {
'0': {
'0': 'ACME Corporation'
}
}
},
objectDefinitions: {
'123456': {
'0': 'My String',
'1': 9876
}
}
}
}Empty string/null resource value handling for numeric and boolean types
You can choose the way to handle an empty string/null resource value by describing them in your settings.js or RED.settings objects.
- Empty string/null is translated into am empty string (
'') and transmitted it to LwM2M server as an empty byte array (0-size packet). This is default. Set''toemptyValueproperty or omit the property. - Empty string/null is translated into
0forINTEGERandFLOATtypes andfalseforBOOLEANtype. SetautotoemptyValueproperty.
Here's an example for providing the predefined manufacturer name.
settings.js
{
lwm2m: {
emptyValue: 'auto'
}
}Block1 Transfer (CoAP Block-Wise trasnfer) support
The Block1 Transfer works only for downlink communication, e.g. Write operation from a LwM2M server.
The Block1 Transfer parameters used in the underlying lwm2m client are as follows.
- The maximum Block1 Transfer receivable resource size: 1MiB
- The maximum Block1 Transfer acceptable chunk size: 16KiB
The both values are larger than Wakaama's default ones but they offer more efficient data transfer on non-narrow network with a linux single board computer.
Relating this function, the entire receivable packet size at once is increased as well.
- The maximum receivable UDP packet size (including CoAP headers): 16.1KiB
The value is user-configurable but it's usually not necessary to do so unless a LwM2M server sends larger size of CoAP headers than expected.
Debug output
You can enable Observe, Read and Write command debug log (stdout or /var/log/syslog) by setting logging level to debug at logging.console.logging in settings.js. For CANDY RED users, modify CANDY_RED_LOG_LEVEL in $(npm -g root)/services/systemd/environment file.
The example output is shown below.
Jul 24 03:13:38 raspberrypi start_systemd.sh[8524]: 24 Jul 03:13:38 - [debug] [lwm2m client:67a2f34a.15b424] [Observe] # of updated uris:3
Jul 24 03:13:38 raspberrypi start_systemd.sh[8524]: 24 Jul 03:13:38 - [debug] [lwm2m client:67a2f34a.15b424] <Read> uris=>^/3304/0/5700$, response=>[{"uri":"/3304/0/5700","value":{"type":"FLOAT","acl":"R","value":45.97}}]
Jul 24 03:13:38 raspberrypi start_systemd.sh[8524]: 24 Jul 03:13:38 - [debug] [lwm2m client:67a2f34a.15b424] <Read> uris=>^/3303/0/5700$, response=>[{"uri":"/3303/0/5700","value":{"type":"FLOAT","acl":"R","value":38.67}}]LwM2M Message Dump
With a new option Dump LwM2M messages, message hex dump is now available.
All messages between client and server are displayed in console (not the debug tab) as shown below when Dump LwM2M messages is checked.
Sending 51 bytes to [127.0.0.1]:5684
17 FE FD 00 01 00 00 00 00 00 10 00 26 00 01 00 ............&...
00 00 00 00 10 5C 30 F4 0D 78 00 25 1D 5D D5 AD .....\0..x.%.]..
E8 64 32 F9 F0 7B A4 61 3A 15 AE C9 9B 2F CA 1C .d2..{.a:..../..
D9 F4 3F ..?
37 bytes received from [127.0.0.1]:5684
17 FE FD 00 01 00 00 00 00 00 10 00 18 00 01 00 ................
00 00 00 00 10 AC 42 8B 93 D2 E1 4E 40 6B F8 7F ......B....N@k..
76 E5 AA 9E 85 v....Registration lifetime behavior
The lwm2m server is able to modify this client's lifetime with Write command to Lifetime resource in Server Object.
When the client detects the lifetime change, the interval between the registration update requests is updated as well at the coming registration update request. The client appends the lifetime query (lt=<new lifetime>) in the registration update request in order to notify the latest lifetime to the server.
Embedded Mode Extensions
This node offers extra features for embedded mode, which allows the host application to interact with this node via EventEmitter object named internalEventBus defined in RED.settings object.
However, this feature is disabled by default (opt-in). In order to enable it, ask users to check Allow internal event propagation property in lwm2m config node.
Pseudo code:
const EventEmitter = require('events').EventEmitter;
const RED = ...;
const server = ...;
const bus = new EventEmitter();
bus.on('object-event', (ev) => {
// You can receive LwM2M object events here
if (ev.eventType === 'updated') {
...
}
});
// Create the settings object - see default settings.js file for other options
const settings = {
...
lwm2m: {
internalEventBus: bus, // set your own EventEmitter object
objects : {
'3': {
'0': {
'0': "ACME Corporation"
}
},
'99999': {
'0': {
'0': 'ABCD'
}
}
}
},
...
};
RED.init(server, settings);
...
bus.emit('object-read', { id: '022eb56240784b43', topic: '/3/0/0' }); // 'Read' operation for retrieving Manufacturer
// Use a one-time listener (once)
bus.once('object-read-022eb56240784b43', (msg) => {
if (/* boolean */ msg.error) {
console.error(msg.payload); // error info
} else {
let man = msg.payload[0].value; // '/3/0/0' resource object
...
}
});Supported OS
This node should work on Unix and Linux OS. Windows is not supported.
Supported Node.js version
Node.js v10/12
How to install
Prebuilt Binaries
The prebuilt binaries are available for the following OS and architectures:
- ARM(armv6+) Linux with Node.js v10/12 (For Raspberry Pi, ASUS tinker board and other ARMv6+ CPU computers)
- x64 Linux with Node.js v10/12
- macOS with Node.js v10/12
Other users need to install the following software manually:
- GCC (4.8+)
- make
Node-RED users
Use Manage palette menu to install this node.
Or run the following commands in a terminal:
cd ~/.node-red
npm install --production node-red-contrib-lwm2mThen restart Node-RED process.
CANDY RED users
Use Manage palette menu to install this node.
Or run the following commands in a terminal:
cd /opt/candy-red/.node-red
sudo npm install --unsafe-perm --production node-red-contrib-lwm2mThen restart candy-red service.
sudo systemctl restart candy-redExample Flows
You can import example flows available under examples folder on Node-RED UI.
Appendix
How to build from source
Install dependencies.
$ npm installThen run the following commands to build source code.
# make configure # Configure the build
$ make debugbuild # Build for Debug
$ make build # Build for Release
$ make debug # Rebuild for Debug
$ make verbose # Rebuild with verbose logs for ReleaseIn order to build JS code, run the following commands.
$ npm run buildEclipse Wakaama LwM2M Server
With Wakaama LwM2M Server, you can test this node on your localhost. The instruction for building the executable file is described here.
- Server Host:
localhost - Server Port:
5683(DTLS is NOT supported)
Run the following command to start LwM2M Server to accept localhost address.
lwm2mserver -4Enter help on the lwm2mserver console for supported commands.
Eclipse Leshan Public Sandbox LwM2M Server with Web UI
Provide the following host and port for your lwm2m client config node to connect to Public Leshan Server.
- Server Host:
leshan.eclipseprojects.io - Server Port:
5683for plain UDP or5684for DTLS with checkingEnable DTLS
You can manage your client info from the following URL.
https://leshan.eclipseprojects.io/#/clients
For Bootstrapping:
- Server Host:
leshan.eclipseprojects.io - Server Port:
5783for plain UDP or5784for DTLS with checkingEnable DTLS
You can create your bootstrapping info from the following URL.
https://leshan.eclipseprojects.io/bs/
License
Source Code License
Copyright (c) 2019 CANDY LINE INC.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
How to Release
- Test all:
npm run test - Publish NPM package:
npm publish - Tag Release and Push
- Checkout master:
git checkout master - Publish binaries:
git commit --allow-empty -m "[publish binary]" - Publish local binary (optional):
export NODE_PRE_GYP_GITHUB_TOKEN=... && make clean && make configure && make && make package && make publish