LwM2M Demo

Table of Contents

  1. Introduction
  2. Resources
  3. Prerequisites
  4. Setup
  5. Using the Demo
    Auto Commissioning
    Manual Commissioning to Leshan Server
    View Leshan Cloud Data
  6. Using the Demo with Software AG Cumulocity
  7. User Defined Server
  8. LED Behavior
  9. Building the Firmware
  10. Development

Introduction

In this demo, the Pinnacle 100/BL5340 device is configured to use LwM2M and DTLS with pre-shared keys. LightweightM2M (LwM2M) is a protocol that runs on top of CoAP. The demo is configured to leave the Pinnacle 100 device in its current mode (Cat-M1 or NB-IoT). The mobile app can be used to change the radio mode if desired. LwM2M is an ideal protocol for NB-IoT or Cat-M1 (Applies to Pinnacle 100/MG100 only) because it is UDP based. When using NB-IoT on the Pinnacle 100/MG100, we do not recommend using the TCP protocol due to the network latencies inherent to NB-IoT.

A LwM2M Server (Leshan or Cumulocity) is used to display information about the Pinnacle 100/BL5340 device and discovered sensors. Supported sensors are:

  1. BL654 BME280 Sensor / ESS BLE sensor
  2. BT510 sensors
  3. BT610 sensors
  4. MG100 only: onboard temperature sensor (LIS3DH)

The software version, model, manufacturer, serial number, and current time can be read. If a BL654 Sensor Board/ESS sample module is detected and can be connected to, then temperature, humidity, and pressure can be read. If BT510 and/or BT610 sensor advertisements are detected, then their sensor readings will be interpreted and sent to the server as well.

                                     XXXXX
                                   XXX   XXX
                         XXXXX   XX        XX
                      XXX    XX XX          X XXXXXXX
                      X        XX            X       XX
                     X                                X
                      X         LwM2M Server           X
                      XX                              X
                       XXXXXXX                       XX
                             XX          XXXX    XXXX
                              XXX      XXX   XXXX
                                XXXXXXX
                                    ^
                                    |
                         Cat-M1/NB-IoT or Ethernet
                            (LwM2M with DTLS)
                                    |
                                    |
                                    v
                          +---------+----------+
                          |                    |
                          |     DVK/MG100      |
                          |                    |
                          +---------+----------+
                                    ^
                                    |
           +-----------------------BLE-------------------+
           |                        |                    |
           v                        v                    v
+----------+------------+  +------------------+  +----------------+
|                       |  |                  |  |                |
|  BL654/ESS Sensor     |  |      BT510       |  |     BT610      |
|                       |  |                  |  |                |
+-----------------------+  +------------------+  +----------------+

Resources

Prerequisites

The following are required to fully exercise this demo firmware:

  • An activated SIM card. The Truphone SIM card that comes with the DVK does not currently support NB-IoT. If you have purchased a DVK in Europe, then please contact sales to obtain a SIM card that is NB-IoT capable (Pinnacle 100/MG100 only).
  • Pinnacle 100/BL5340 device programmed with LwM2M demo firmware.
    • Connect to the FTDI UART on the development kit to view firmware logs
  • Laird Pinnacle Connect app installed on a mobile device

Setup

To set up the device, follow these steps:

  1. Ensure an activated SIM card is inserted into the Pinnacle 100 SIM slot (Pinnacle 100/MG100 only).
  2. On your phone, launch the Pinnacle mobile app and follow the on-screen prompts.

Using the Demo

If the Laird Connectivity Leshan server is used, then the device should be configured to something other than its default settings. This allows multiple devices to connect to the same server.

Auto Commissioning

  1. Open the mobile app, connect to your device and go to the LwM2M Settings page.
  2. Click the Auto-commission device button. This will automatically add the device with a unique ID to the Laird Connect Leshan LwM2M server.

Note: Ensure the Cumulocity toggle is turned off

Auto-commission device
Auto-commission device

  1. Skip to View Cloud Data for instructions on interacting with your device.

Manual Commissioning to Leshan Server

  1. Open Laird Connectivity Leshan web page.
  2. Go to the Security page.
  3. Press “Add Security Information”.

Leshan add device
Leshan add device

  1. Using the Pinnacle Connect mobile app, read the model number from the Device Information page.

Model number
Model number

  1. With the mobile app, make note of the Gateway ID from the home page.

Gateway ID
Gateway ID

  1. Enter <model number>_<id> into the Client endpoint field on the webpage. For example, pinnacle_100_dvk_354616090287629 or bl5340_dvk_cpuapp_ebc25ce12ffd.
  2. Generate a new private shared key using the LwM2M Settings page in the mobile app.
  3. Copy the value into the Key field on the webpage.
  4. Set and save the Client ID using the mobile app (don’t reuse a name that is already present on the server).
  5. Put the same name into the Identity field on the web page.

LwM2M settings
LwM2M settings

Leshan device config
Leshan device config

  1. Ensure bootstrap is disabled in the mobile app.

  2. Reset the modem using the mobile app (Power Settings page) or reset button (SW5 NRF_RESET).

View Leshan Cloud Data

From the clients page, click on your device once it is connected to interact with it.

  • Make sure to set the Response Timeout to something greater than 5s at the top of the page.

Leshan response timeout
Leshan response timeout

  • Click on an object and select R at the top to read all child values. In some cases, not all child values are supported.

Leshan read object
Leshan read object

Using the Demo with Software AG Cumulocity

Commission Your Device

To configure your device, the Peer URL, Client ID/PSK ID, PSK and bootstrap enable must be set. This can be done using the UART console or the mobile app.

Mobile App Auto-Commission

Commissioning the device with the mobile app is the quickest and easiest when using the auto-commission.

Note: When clicking the Auto-commission button a new PSK will be generated.

Cumulocity Auto-Commission
Cumulocity Auto-Commission

Note: You can also use the mobile app to manually set any of the LwM2M settings.

Manual Commission via UART

Using the UART console, set the lwm2mPeerUrl attribute:

attr set 215 lwm2m.us.cumulocity.com:5684

set the lwm2mClientId attribute (replace <ID> with unique ID of your device). For example, on an MG100:

attr set 214 MG100_<ID>

Set the lwm2mPsk attribute:

attr mod 213 <PSK value as hexadecimal digits>

Enable bootstrap support:

attr set 264 1

To reboot the device and it will attempt the LwM2M bootstrap connection when the firmware runs again:

kernel reboot cold

Register Device

First fill out this template for each of your devices, one per row.

  • Columns A,B,C,E,F, and H should all be the same. Pick a unique ID for your device. For MG100/Pinnacle 100, include the IMEI. For BL5340, include the Ethernet MAC address. This unique ID should match the client ID that was set when commissioning your device.
  • Column D is not used, leave the value alone.
  • Column G and I should be different PSK values for better security but can be set to the same value if desired. They can be different by one bit or completely randomized. Column G needs to match the PSK value used when commissioning your device. The format for the PSK in the spreadsheet is a 16 byte value written as hex, for example 5b30484ec1539bed3c99e45b082b2159. Be careful to not include any leading or trailing whitespace.

Navigate to Device Management

Device Management
Device Management

Click Registration on leftmost sidebar, then click the Register device button

Register Device
Register Device

Select Bulk device registration (even if registering a single device)

Bulk Registration
Bulk Registration

Click Select file to upload and select your filled out template file (.CSV)

Upload File
Upload File

After the file uploads, click Reload now to finish the process

Reload Now
Reload Now

Adding LwM2M Object Support

Select Device Protocols from the far-left sidebar.

Device Protocols
Device Protocols

The list of device protocols configured on your tenant are listed.

If the desired protocols for your device are already loaded, you do not need to add them again.

Click Add device protocol, select LWM2M, then drag and drop the XML Schema file for the LwM2M object you would like to support. See the LwM2M Registry for examples.

Note: Once a protocol has been uploaded for a Cumulocity tenant, it is available for any future device registrations. Upload of the XML schema only needs to be performed once per tenant.

Verifying Connectivity

Watch UART console output for the Registration Done message

[00:00:15.756,835] <inf> net_lwm2m_rd_client: Registration Done (EP='29JjiRLgGU’)

On the Cumulocity Device Management site, navigate to the Info page for your device. The Last communication timestamp is listed in the DEVICE STATUS section.

Connectivity Status
Connectivity Status

Viewing LwM2M Object Data

Once connected, you can view the LwM2M data supported by the device using the Objects menu.

Click Objects, then select an LwM2M object you’d like to view the data from.

Click Read Object to send the LwM2M read request for the desired LwM2M object. After a few seconds, this will refresh the contents of the page.

From here, you can read/write values or execute operations related to the connected device.

Read/Write Objects
Read/Write Objects

Setting Up and Viewing a Measurement

To view data on a graph, it must be setup as a data point. Select Device types, then Device protocols from the left-most sidebar.

Expand the Object you wish to make a data point from. Click the Resource to expand the view.

Click Send measurement to enable measurement and specify a Type, Series and Unit.

To setup the device to automatically report the value upon connection, click Auto observe.

Specify the parameters such as minimum and maximum period or “less than/greater than” threshold for the observe to specify conditions for the value to update.

WARNING: Setting the observe rate to report data often can result in very high data usage.

Click Save to save your settings

For a quick verification that data points are being captured, use the Measurement view.

Select your device, then click Measurement.

Each data point series setup for your device will be plotted.

Device Measurement
Device Measurement

User Defined Server

In addition to the steps in the Using the Demo section, the Peer URL must be set using the mobile app.

Depending on the servers support for bootstrap, enable or disable bootstrap with the mobile app or use the following command via the UART console:

# disable bootstrap
attr set 264 0

# enable bootstrap
attr set 264 1

LED Behavior

Pinnacle 100/MG100

The Blue LED blinks when the module is advertising and allowing another device to connect to and configure it. When a central device connects, the LED remains on. When advertising stops, the LED remains off. Button 1 (SW1) can be pressed to restart advertising.

The Green LED turns on when connected to the LwM2M server. When disconnected from the server, the LED remains off.

The Red LED blinks when the Pinnacle 100 device is searching for a cellular network. It remains on and does not blink when connected to a network. If there is an error with the SIM card or network registration, then the LED remains off.

BL5340

LED 1 blinks when the module is advertising and allowing another device to connect to and configure it. When a central device connects, the LED remains on. When advertising stops, the LED remains off. Button 1 can be pressed to restart advertising.

LED 2 blinks once a second when the module is searching for a BL654 Sensor Board/ESS service device. When it finds a sensor and successfully connects to it, the LED remains on.

LED 3 is on when network connectivity is established, it remains off when there is no network connection.

LED 4 turns on when connected to the LwM2M server. When disconnected from the server, the LED remains off.

Building the Firmware

Note: If using VS Code for development the build lwm2m task can be used to easily build the firmware.

Issue these commands from the ble_gateway_firmware directory.

WARNING: If using windows, checkout code to a path of 12 characters or less to avoid build issues related to path length limits.

Build commands:

Note: [board] should be replaced with mg100, pinnacle_100_dvk or bl5340_dvk_cpuapp

# Linux and macOS

west build -b [board] -d ${PWD}/build/[board]/lwm2m ${PWD}/app -- -DOVERLAY_CONFIG="${PWD}/app/overlay_lwm2m_dtls.conf"

# Windows

west build -b [board] -d %CD%\build\[board]\lwm2m %CD%\app -- -DOVERLAY_CONFIG="%CD%\app\overlay_lwm2m_dtls.conf"

After building the firmware, it can be flashed with the following command:

Note: [board] should be replaced with mg100, pinnacle_100_dvk or bl5340_dvk_cpuapp

west flash -d build/[board]/lwm2m

west flash will program all images (mcuboot, app, network core) required to run the app.

Development

See here for help on getting started with custom development.

Cellular Network Information

See here for instructions on how to get details about the cell network (Pinnacle 100/MG100 only).