Soracom Inventory

Configuration

Using Inventory will incur fees. Refer to the Pricing & Fee Schedule for more information.

Managing a device with Soracom Inventory simply requires installing an Agent on the device, then registering the device in Inventory and performing key exchange while the device is connected using Soracom Air.

Any LwM2M-compliant agent may be used with Inventory. This document refers to the following libraries as representative examples for implementing agents that follow the LwM2M standard:

This document refers to both libraries to demonstrate how to install an agent on a device, and how to register the device with Soracom Inventory. However, when implementing Inventory with your application, please utilize an LwM2M agent or library that is appropriate for your device.

Aside from using custom object models, no additional configuration is required on the User Console.

Installation instructions may differ according to LwM2M agent and device environment. The following examples for Eclipse Wakaama Client and Soracom Inventory Agent for Java provide a basic overview of the typical installation process. Refer to your LwM2M library documentation for information on its installation procedures.

Eclipse Wakaama Client

Agent Installation

  1. On a Linux device, download and execute the following build script:

    curl https://soracom-files.s3.amazonaws.com/build_wakaama.sh | bash

    This script will install packages required to compile a binary executable, download the latest build of the Eclipse Wakaama library, and build the lwm2mclient executable.

    When a device is registered on Soracom Inventory, a unique device ID will be automatically generated. This device ID is required to perform certain LwM2M management functions. The build script will enable the DTLS option for Wakaama in order to support specifying the device ID when required.

  2. Copy the compiled executable to /usr/local/bin so that it can be accessed by all users:

    sudo cp inventory/build/lwm2mclient /usr/local/bin

The Wakaama client is now ready for use. Refer to the Eclipse Wakaama documentation for additional information on how to use the client.

Device Registration

Bootstrap

When using Inventory with SIM cards assigned to a VPG, that VPG must have its Internet Gateway enabled to complete the bootstrap process. Otherwise, the SIMs must be unassigned from the VPG to complete the bootstrap process. After bootstrapping is completed, those SIMs can be reassigned to the VPG.

When bootstrapping is complete and the keys are available locally, the Inventory device will be able to connect to LwM2M server if it has another internet communication method such as wifi, even if the VPG it is assigned to has its Internet Gateway disabled.

Next, we will perform the bootstrap process to register our device.

  1. Connect to a cellular network using a Soracom IoT SIM card.

  2. Run the following command:

    lwm2mclient -b -h bootstrap.soracom.io -p 5683 -4 -n {CLIENT-ENDPOINT-NAME}

    The following command parameters are specified:

    • -b - Request bootstrapping.
    • -h - Specify the LwM2M server.
    • -p - Specify the LwM2M port.
    • -4 - Establish the connection using IPv4.
    • -n - Set the endpoint name of this LwM2M client (by default, lwm2mclient will use testlwm2mclient).

    You may use any unique string as the endpoint name, however when managing a large number of devices, OMA recommends one of the following:

    • UUID - Universally Unique Identifier, such as abcdef00-0000-0000-0000-000012345678.
    • OPS - Organizationally Unique Identifier, Product Class, and Serial Number, such as a MAC address.
    • OS - Organizationally Unique Identifier and Serial number.
    • IMEI - A 15-digit International Mobile Equipment Identifier number.
    • ESN - An 8-digit Electronic Serial Number.
    • MEID - A 14-digit Mobile Equipment Identifier.
    • IMEI-MSISDN - A combination of device IMEI and subscriber directory number.

Once the device has successfully registered, the command will return the following output, along with connection information:

< -> State: STATE_READY

The device will also appear on the User Console, in the Device Management screen.

Key Exchange

The lwm2mclient agent automatically performs key exchange during the bootstrapping process. However, we will need to use this key in order to connect directly to the Inventory Device Management server on subsequent connections.

While the lwm2mclient agent is still running, we can access the security object, which contains the secret key. Simply enter the dump /0/1 command:

< -> State: STATE_READY
dump /0/1

The lwm2mclient agent includes additional commands that may be useful during testing. With the agent running, enter help to view additional commands.

The agent will dump the contents of the object. Check the output for resource /5, which will look something like this:

<...
<{
<    id: 5
<    type: LWM2M_TYPE_OPAQUE
<    AB CD EF 00  00 00 00 00  00 00 12 34  56 78 99 CA   ...........4Vx..
<}
<...

Here, the hexadecimal value ABCDEF000000000000001234567899CA represents the secret key, and can be used when subsequently connecting to the Inventory Device Management server. Save this value, removing any spaces between the hex values.

While we check the output, we can also save the value of resource /3, which contains the device ID generated by Inventory:

<...
<{
<    id: 3
<    type: LWM2M_TYPE_OPAQUE
<    64 2D 61 62  63 64 65 66  30 30 30 30  30 30 31 32   d-abcdef00000012
<    33 34 35 36  37 38                                   345678
<}
<...

Here, the ASCII value d-abcdef00000012345678 represents our device ID.

You can also view the device ID from the User Console.

Connecting to Inventory

To run the agent and connect to Soracom Inventory, simply run the lwm2mclient executable, specifying the Inventory server:

lwm2mclient -h g.inventory.soracom.io -p 5684 -4 -n {CLIENT-ENDPOINT-NAME} -i {DEVICE-ID} -s {SECRET-KEY}

The lwm2mclient agent will display output while connected to Inventory. As the process will block the local session, you can configure your device to run the executable on startup, once you have confirmed that device management with Inventory works as expected.

Note that the lwm2mclient agent expects the secret key in hexadecimal format. Other agents may require the key to be specified in a different format.

Because we are establishing a connection to the Inventory Device Management server using the device's secret key, we can use this method to connect using a different network interface, such as an ethernet or Wifi connection.

Soracom Inventory Agent for Java

Soracom provides a sample reference agent based on Eclipse Leshan, which provides bootstrap, key exchange, basic read object definition, and execute ping and shutdown commands, and can be extended to support additiona LwM2M management functionality.

To run the agent, your device must have Java runtime installed.

Releases

You can use pre-compiled binaries from the Soracom Inventory Agent for Java Repository. Simply download the zip file for the latest release, extract them to your device, and navigate to the /bin folder located within the extracted directory.

Inside the /bin folder, run the soracom-inventory-agent-example-start agent to initiate bootstrapping. Ensure that your device is connected with a Soracom IoT SIM card when bootstrapping.

./soracom-inventory-agent-example-start

You can use the -e option to specify the client endpoint name.

This will automatically perform device registration and key exchange, with the device's secret key stored in a .soracom-intentory-credentials.dat file in the same directory. The agent will continue to run, displaying information about its connection with Inventory.

When running the agent again, it will use the stored credentials to authenticate with Inventory. Alternatively, you can use the -i and -p options to specify the device ID and secret key (in Base64 format):

./soracom-inventory-agent-example-start -u g.inventory.soracom.io -i {DEVICE-ID} -p {SECRET-KEY}

To bootstrap again, you can use the -b option, or simply delete the credentials file.

Source Code

The Java source code is also available from the Soracom Inventory Agent for Java Repository.

The source code contains a soracom-inventory-agent-for-java-example directory containing object and resource definition and command scripts, which can be quickly modified or extended to add management functionality as needed.

When modifying the source code, you can compile the project by running:

./gradlew build

This will generate a zip or tar file of the compiled agent, which you can then extract and run following the instructions above.

Manual Registration

In some cases, you may prefer to register devices directly on the Device Management server, rather than through the bootstrapping method.

  1. Login to the User Console. From the Menu, open the Device Management screen. Ensure that you have selected the Global coverage type.

    https://console.soracom.io

    Register device

  2. Click the Add device button.

  3. Enter a Name for the device and select an existing Group. Then click Create.

    Create device

  4. A dialog will appear with the generated device ID and Secret Key. Ensure that you save the secret key, as it will not be shown again after closing the dialog.

    Generated device key

You can then use the device ID and secret key with your LwM2M agent, configuring it to connect directly to the Inventory Device Management server.

When registering a device manually on the User Console, the generated secret key will be in Base64 format. You can convert it to hexadecimal format for use with agents like lwm2mclient, by using a converter such as the following:

echo "zasA7wAAAAAAADQSeFbKmQ==" | base64 --decode | hexdump
>0000000 abcd ef00 0000 0000 0000 1234 5678 99ca