Manage devices using LWM2M
ARTIK Cloud uses the LWM2M protocol to manage Device Properties for device types. Device Properties are one of three types of properties ARTIK Cloud recognizes for device management. They are enabled for a device type via the Developer Dashboard. To use Device Properties, the LWM2M client must be installed on the device.
LWM2M stands for Lightweight Machine to Machine. It is a protocol built on top of CoAP. For details, refer to the LWM2M technical specification. In the context of LWM2M, ARTIK Cloud is the LWM2M server and a managed device is the LWM2M client.
LWM2M defines sets of objects and resources. A resource is a field that has a type. Objects are logical groups of resources. ARTIK Cloud supports a subset of LWM2M objects and resources. A device sends its LWM2M resources to ARTIK Cloud, which in turn stores and represents them as Device Properties in the Device Mirror.
ARTIK Cloud recognizes two other types of properties for device management: Server Properties and System Properties, which will also be discussed in this document.
For instructions on performing a firmware update with LWM2M, see OTA updates.
In order to access Device Properties and perform tasks, a client must be installed on the device. Our SDKs for LWM2M hide the complexity of connecting to the server with a secure connection. The connection can happen with CoAP over UDP or CoAP over TCP.
You will need to extend the SDK to hook into the Device Properties or to customize it to your needs (e.g., changing the timezone). Once the SDK is installed, the device will be able to register with ARTIK Cloud and will send periodic registration updates to ARTIK Cloud.
LWM2M Core operations
ARTIK Cloud supports the following core operations performed on a device:
- Read objects and resources from a device
- Write resources to a device
- Execute resources on a device
- Observe objects and resources on a device. Observations are long-running requests. During observation time, the device periodically sends the current values of the observed resources back to ARTIK Cloud.
A device type owner can initiate Read, Write, and Execute operations for their devices by creating device management tasks. ARTIK Cloud then communicates to the device to perform LWM2M operations.
LWM2M Administrative operations
ARTIK Cloud supports the following administrative operations to manage devices through LWM2M:
- Registration: A device must first register with ARTIK Cloud before any of the above core operations can be performed on it. If a device is not registered, ARTIK Cloud will have no knowledge of the device and cannot perform any operation on it.
- Registration update: When a device registers, it sets a lifetime during which the registration is valid. A registration update must be made by the device before this lifetime is reached. Otherwise the device will be de-registered. When a registration update is sent, the lifetime gets extended.
- De-registration: A device can explicitly de-register if it no longer wants to be managed through LWM2M.
- Write attributes: ARTIK Cloud can write attributes to a device for objects or resources. For example, ARTIK Cloud writes the
pmaxvalues used in observation (see below).
Objects and resources
ARTIK Cloud supports the majority of the resources of the LWM2M Device and Firmware objects (3 and 5, listed in the LWM2M Object & Resource Registry). See below for a list of supported resourcesfor objects 3 and 5. A device type owner chooses which resources to support from the list.
Supported objects and resources
Object 3: Device (ARTIK Cloud name: device)
|RESO URCE ID||Name||ARTIK Cloud name||Type||ARTIK Cloud type||INST ANCES||OPE RAT IONS|
|6||Available Power Sources||availablePower Sources||Integer||Long||Multiple||R|
|7||Power Source Voltage||powerSource Voltage||Integer||Long||Multiple||R|
|8||Power Source Current||powerSource Current||Integer||Long||Multiple||R|
|12||Reset Error Code||resetErrorCode||Single||E|
|16||Supported Binding and Modes||supported Binding AndModes||String||String||Single||R|
Object 5: Firmware Update (ARTIK Cloud name: firmwareUpdate)
|RESO URCE ID||Name||ARTIK Cloud name||Type||ARTIK Cloud type||INST ANCES||OPE RAT IONS|
|1||Package URI||not available; must be supported by device|
|2||Update||not available; must be supported by device||Single|
|4||Update Supported Objects||update Supported Objects||Boolean||Boolean||Single||RW|
Although LWM2M allows more than one instance of an object, ARTIK Cloud supports only one instance of an object, which will always be instance 0.
Data type conversion
LWM2M objects are translated as collections in the ARTIK Cloud properties Manifest. Every LWM2M resource has a data type. The following table lists the LWM2M resource data types and their corresponding ARTIK Cloud Device Property data type.
|LWM2M Data Type||Device Property Data Type|
|Time||Long (milliseconds since epoch)|
TCP is preferred over UDP, since devices communciate with ARTIK Cloud over a WAN. TCP provides reliable delivery and persistent connections, which are better suited for WAN environments.
DTLS uses the pre-shared key (PSK) mechanism, where the server and client encrypt the communication using the secrets shared in advance.
PSK requires an identity and a key with the following values:
|Key||Device token represented as hex string|
The client will validate the server certificate. Because the server does not require a client certificate, there is no certificate needed on the device itself. Both methods use a device token as part of the secure validation.
If a device token is revoked, subsequent registrations and registration updates for the device will fail.
Enable Device Properties
Before you can manage Device Properties, you must first enable them for the device type. Go to the Developer Dashboard, select the Device Management tab under your device type, and click on "ENABLE DEVICE PROPERTIES".
Connect a device
Connect a device to the ARTIK Cloud LWM2M server using the following information:
|Endpoint name||Device ID|
|PSK identity||Device ID|
|PSK key||Device token represented as hex string|
After you connect a device to ARTIK Cloud over LWM2M, you must register it with ARTIK Cloud before you can manage its Device Properties. Below is the high-level registration flow:
There are four phases:
ARTIK Cloud requires a secure connection. This is the first step that must happen.
After the handshake has successfully finished, the device registers by passing the device ID as the endpoint name. At the same time, the device also provides the registration lifetime. ARTIK Cloud sends a unique registration ID back to the device.
The lifetime tells the server how long the registration stays active. When the lifetime expires, the device is de-registered. The device can extend its registration lifetime by sending a registration update.
If the device registers again while the registration is still valid, ARTIK Cloud will void the old registration ID and send a new ID back to the device.
Set pmin and pmax
After the device has successfully registered, ARTIK Cloud sets
pmax values. To do so, it sends a Write Attributes request on /3/0 (object 3, instance 0).
pmax specify the frequency that notifications can be sent by the device. They are attributes of observations and are defined in the LWM2M specfication.
pmin is the Minimum Period Attribute. It indicates the minimum time (in seconds) the LWM2M client must wait between two notifications. If a resource value has to be notified during the specified quiet period, the notification must be sent as soon as this period expires. In the absence of
pmin, the Minimum Period is defined by the Default Minimum Period set in the LWM2M Server Account.
pmax is the Maximum Period Attribute. It indicates the maximum time in seconds the LWM2M Client may wait between two notifications. When this “Maximun Period” expires after the last notification, a new notification must be sent.
pmax must not be smaller than
Observe object 3
pmax are set, ARTIK Cloud sends an Observe request on /3/0 (object 3, instance 0). The device must immediately send back the resource values as the response. ARTIK Cloud updates the Device Mirror with these values.
After a device completes the registration flow, its registration is valid until the registration lifetime expires. The following events can occur while the registration is valid:
- The device updates the registration to extend the registration lifetime.
- The device de-registers. The Device Property management ends until the device registers again.
- The device re-registers. The registration is extended with a new lifetime and ID.
- The device sends a Notify request to update values for object /3/0. Via observe/notify, ARTIK Cloud continually receives updates of resource values from the device and then updates the corresponding Device Mirror.
- ARTIK Cloud sends a Read request to read the value of a resource.
- ARTIK Cloud sends a Write request to write a new value to a resource.
- ARTIK Cloud sends an Execute request to execute a resource.
A device type owner initiates the last three LWM2M operations (Read, Write, Execute) by creating device management tasks on ARTIK Cloud.
Device management tasks
Device management tasks can be performed only when the corresponding physical device is online and has a valid registration status.
A device type owner can create tasks to Read, Write, and Execute to their devices via ARTIK Cloud. Tasks are asynchronous jobs which can run across multiple devices for a given device type. The following are the supported tasks:
- Deep read of a Device Property. This sends a Read operation directly to the device(s) using LWM2M. Upon successful completion, the Device Mirror will be updated with new values.
- Deep write of a Device Property. This sends a Write operation directly to the device(s) using LWM2M. Upon successful completion, the Device Mirror will also be updated with new values.
- Execution of a Device Property. This sends an Execute operation directly to the device(s) using LWM2M.
- Bulk write of a Server Property. This will update the value of a Server Property for one or more devices in a single task.
Deep read/write of a property means that the tasks are performed directly on the device, not on the Device Mirror. The properties on the Device Mirror are updated as the result of deep read/write.
ARTIK Cloud uses an OTA Update task to handle OTA updates.
Tasks are asynchronous, meaning that the API to create a task will return immediately before the task begins to run. To get the current state of a task, the task status must be retrieved by calling the REST API.
Tasks will attempt to issue the operation to a device if the device is currently registered with and connected to ARTIK Cloud via LWM2M. Otherwise the task will be queued until the device registers with ARTIK Cloud. Also, any failed attempts to communicate with the device will requeue the task and retry when the device re-registers or updates registration.
Tasks API reference
Tasks have an active period during which ARTIK Cloud will try to issue the task to the devices. When this active period ends, the task expires and any remaining pending devices will be marked as
FAILED with error code 4004.
The default expiration time for tasks is 7 days. This default can be overriden per task or per device type. If
taskParameters.expiresAfter is set when creating the task, this value will be used. Otherwise, if
taskExpiresAfter has been set in the device type configuration, then this value will be used.
Tasks will remain accessible through the APIs for 30 days from when the task was created, after which they will be removed from ARTIK Cloud.
Device task errors
|4001||Device is not registered||Error indicating that the device is not registered - currently used for firmware update only|
|4004||Device task expired||The device task expired|
|4010||Unauthorized - access right permission denied||CoAP 4.01 error code returned from client|
|4000||Invalid value||CoAP 4.04 error code returned from client. The specific error message originates from the client response.|
|4050||Method is not allowed||CoAP 4.05 error code returned from client|
|4030||Forbidden - duplicate endpoint client name||CoAP 4.03 error code returned from client|
|4040||Resource is not found||CoAP 4.03 error code returned from client|
|4150||Unsupported content format||CoAP 4.15 error code returned from client|
|4060||Not acceptable - specified format is not supported||CoAP 4.15 error code returned from client|
|5000||Internal server error||AKC internal error|