SORACOM Developers

SORACOM Inventory Getting Started

Managing devices with SORACOM Inventory

Introduction

SORACOM Inventory is a service for device management using LwM2M which is an open standard. LwM2M is a lightweight M2M protocol defined by OMA (Open Mobile Alliance), SORACOM Inventory (hereinafter referred to as Inventory) uses this protocol to communicate with devices and SORACOM platform, and API and user console You can remotely read / write (Read, Write) the device data, execute the command (Execute), or receive an update notice of the device information (Observe, Unobserve).

In this guide, I will explain the procedure of registering a device to account using Inventory and remotely managing devices according to the following steps. As an example of the remote device management procedure, read (Read) data on the device and execute command (Execute) to the device.

The premise of this guide is as follows.

Step 1: Understand the overall of SORACOM Inventory

New terms and concepts are used in Inventory, and the overall configuration is as shown below. Before actually using the service, lets organize the whole picture.

Inventory Overview

Inventory structure and organization

Inventory realizes remote device management by installing an agent corresponding to LwM2M on the device side and running it.

In using Inventory, the first process is device registration and key exchange (bootstrap) to the SORACOM platform. Communicate with Air SIM to authenticate, and bootstrap with agent on the device. At this time, the agent communicates with the Bootstrap Server (*), registers device information on SORACOM platform and exchanges keys for future communication. When bootstrapping is complete, the device is registered in Inventory and appears in the device list of the user console.
* Bootstrap Server is a component of Inventory, which is responsible for device registration and key exchange.

Devices registered in Inventory can read / write data (Read / Write) on the device using the user console or API, receive notification when there is a change on the device side (Observe), execute the command (Execute) In order to communicate with the component called Device Management Server through the agent. Device authentication and key exchange have been completed at the first bootstrapping stage, so registered devices can use communication means other than Air SIM. You can remotely manage devices using Inventory even when you are communicating over Wi-Fi etc.

(*) Observe is a function that can receive notification when there is a change in value on the device side. Please note that asynchronous notification from the device is the basis, not periodic loading.

Resource model

Inventory manages information on the device in the form of “Rosource Model”. The resource model is specified by LwM2M, and it has a tree structure of an object (Object), an object instance (Object Instance), and a resource (Resource). Elements are numbered and can be expressed as /3/0/0.

For example, /3/0/0 is a resource representing the manufacturer of the device (Manufacturer), and the agent returns its manufacturer information in response to a Read request from the server. Also, /3/0/4 represents (Reboot). When this Execute request is sent from the Device Management Server, the device itself is restarted.

As for the protocol of LwM 2 M, operation calls to resources and responses are only defined. Please keep in mind that the actual operation part is left to the agent side. For example, how to acquire manufacturer information for Read to /3/0/0 (manufacturer information) of the above example is left to the implementation of the agent.

Step 2: Install agent on device and check operation

Inventory provides device management functions according to LwM 2 M standards. Eclipse Wakaama and Eclipse Leshan are representative examples of libraries for implementing agents supporting LwM 2 M. When agents are created using these, agents can be managed from Inventory.

In this guide, we use agent (Wakaama C client) for Linux implemented in C using Eclipse Wakaama provided by Soracom as a sample, Linux agent implemented in Java using Eclipse Leshan (SORACOM Inventory Agent for Java) and check the operation.

Attention
  • The agent introduced in this guide is a sample for confirming the operation to the last. Please implement the agent yourself in full-scale operation.
  • Eclipse Wakaama, Leshan and other libraries are not covered by our technical support for usage and implementation. Please understand beforehand that we can not accept questions about implementation. Please refer to the official document of each library for technical information.

Step2-1: Sample agent for Linux (Wakaama C client)

Here, we will explain the procedure from installing Wakaama C client to checking the operation by taking the Linux distribution Raspbian Jessie Lite (June 2017) for Raspberry Pi as an example. Commands may be different on other distributions.

Install

A build script build_wakaama.sh is prepared. Download this shell and run the build. Execute the following command.

Make sure you are connected with Air SIM.

 $ curl soracom-files.s3.amazonaws.com/build_wakaama.sh | bash
 $ sudo cp inventory / build / lwm2mclient / usr / local / bin

 $ lwm 2 mclient - n $ (hostname) - b - h bootstrap.soracom.io - p 5683 - 4 - c> dump / 0/1

Since the device is also registered in the user console, reload the “device list” screen and check it. If it is not successfully registered, check the command options and network connection status.

When this command is executed, bootstrap is executed and the replaced key is displayed. After that, using deviceId and secretKey, you can connect without using AirSIM by the following command.

$ lwm2mclient -n $ (hostname) -i <deviceId> -s <secretKey> -h jp.inventory.soracom.io -p 5684 -4-c

For details of command options, see wakaama README.

Device registration(bootstrap)

After the installation is completed, next, register the device (bootstrap). First, connect Raspberry Pi to the network with Air SIM.

Then execute the following command and registration is successful if the character string “State: STATE_READY” is displayed. Since the device should also be registered in the user console, please reload the “device list” screen. If you can not successfully register, check the command options and network connection status.

$ cd ~/wakaama/build
$ ./lwm2mclient -b -n{endpoint}-h bootstrap.soracom.io

Step2-2: Sample agent for Linux (SORACOM Inventory Agent for Java)

Here, we will explain the procedure from the installation of the SORACOM Inventory Agent for Java to the operation check by taking the Linux distribution Raspbian Jessie Lite (June 2017) for Raspberry Pi as an example. Commands may be different on other distributions.

The pre-built sample agent is implemented with “device registration”, “read data such as date” and “command (ping / shutdown) only, and based on the sample agent of the source code to be distributed By increasing the number of implementations for each device, expansion according to the device is possible.

Installed build agent

Download soracom-inventory-agent-example-xxx.zip (xxx is the version number) from SORACOM Inventory Agent for Java please.

$ sudo apt-get install default-jre
$ java -version

Next, install the zip file of the already-built agent in the appropriate directory and installation is completed.

Device registration (bootstrap)

After the installation is completed, next, register the device (bootstrap). First, connect Raspberry Pi to the network with Air SIM.

execute the following command and execute bootstrap.

$ cd ~/soracom-inventory-agent-example-0.0.1/bin/
$ ./soracom-inventory-agent-example-start

The endpoint name at device registration is automatically set, but you can set any endpoint name by using the -e option.

When the bootstrap is completed, the device displays on the console as the endpoint name output as 2017-06-28 11: 15: 31,270 INFO SORACOMInventoryAgentExample - using endpoint [My - Device.local - ACDE99999999] in the log It will be.

Also, a file .soracom-inventory-credentials.dat is created in the same location as the agent. After bootstrap, you can use this file to communicate with SORACOM Inventory without bootstrap, so you can communicate via non-SIM such as wifi. If you want to bootstrap again, erase this file and re-execute, or add the -b option at runtime.

Extended sample implementation

We also distribute the source code of SORACOM Inventory Agent for Java to customers who applied for Limited Preview. Soracom-inventory-agent-for-java-release-xxx.zip (where xxx is the version number) is the set of projects including the source code. By implementing this code based on this code, it is possible to implement an agent corresponding to the device.

The source code zip file contains sources containing two folders, "soracom-inventory-agent-for-java-core” and “soracom-inventory-agent-for-java-example” It is a core library and sample library.

The extension of the agent is basically a form of modifying the file in “soracom-inventory-agent-for-java-example” or implementing the agent with reference. For details on the extension method, please refer to the README attached with the source code.

You can build a project with the following command.

./gradlew build

After execution, the zip / tar file of the already-built agent is generated in the soracom-inventory-agent-for-java-example / build / distributions folder, so you can install it on the device by the above procedure.

Step3: Agent operation check

Step3-1: Reading device information

When the agent bootstrapping is completed, click “SORACOM Inventory” from the menu button on the upper left of the user console and go to the device list screen.

Please confirm that the device registered in Step 2 is displayed in the registered device list. Click the device from the list to display the device details screen. Inventory uses this page to perform remote management.

device detail

Step3-2: Observe the data on the device

After bootstrapping is completed and you can confirm that registration of the device is completed at the user console, let’s get the data of the device remotely. As an example, here we will Observe the current time on the device and notify you if there is a change in the value on the device side on the device. Let’s check the operation of Observe following the procedure below.

Step3-3: Execute on device

As an example of executing commands to the device (Execute), we will show the procedure to restart the device remotely using wakaama C client. If the device is located in a remote location, this operation is dangerous, so be sure to read the following notes.

Attention
  • Performing the operation described in this section will actually restart the device. Please be sure to check beforehand that the agent automatically starts up at device startup and has a function to automatically reconnect the network. If there is no such function and there is a device in a remote place, there is a possibility that a recovery work may be needed in the place of the device installation place.
  • In this section, we will only describe the procedure to Execute on agent for Linux.

The above is the introduction of Inventory’s basic functions.

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop