Filter results by

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.

LWM2M Client

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 Operations

LWM2M Core operations

ARTIK Cloud supports the following core operations performed on a device:

  1. Read objects and resources from a device
  2. Write resources to a device
  3. Execute resources on a device
  4. 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.

ARTIK Cloud automatically initiates the Observe operation during the device registration workflow.

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 pmin and pmax values 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
0 Manufacturer manufacturer String String Single R
1 Model Number modelNumber String String Single R
2 Serial Number serialNumber String String Single R
3 Firmware Version firmwareVersion String String Single R
4 Reboot reboot     Single E
5 Factory Reset factoryReset     Single E
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
9 Battery Level batteryLevel Integer Long Single R
10 Memory Free memoryFree Integer Long Single R
11 Error Code errorCode Integer Long Multiple R
12 Reset Error Code resetErrorCode     Single E
13 Current Time currentTime Time Long Single RW
14 UTC Offset utcOffset String String Single RW
15 Timezone timezone String String Single RW
16 Supported Binding and Modes supported Binding AndModes String String Single R
17 Device Type deviceType String String Single R
18 Hardware Version hardwareVersion String String Single R
19 Software Version softwareVersion String String Single R
20 Battery Status batteryStatus Integer Long Single R
21 Memory Total memoryTotal Integer Long Single R
22 ExtDevInfo not supported        

Object 5: Firmware Update (ARTIK Cloud name: firmwareUpdate)

RESO URCE ID Name ARTIK Cloud name Type ARTIK Cloud type INST ANCES OPE RAT IONS
0 Package not supported        
1 Package URI not available; must be supported by device        
2 Update not available; must be supported by device     Single  
3 State state Integer Long Single R
4 Update Supported Objects update Supported Objects Boolean Boolean Single RW
5 Update Result updateResult Integer Long Single R
6 PkgName pkgName String String Single R
7 PkgVersion pkgVersion String String Single R

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.

This table lists the LWM2M resources that must be implemented by your client to perform OTA updates.

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
Object Group
Resource Field Descriptor
String String
Integer Long
Float Double
Boolean Boolean
Opaque Not supported
Time Long (milliseconds since epoch)
Objlnk Not supported
Collection Collection

Security

ARTIK Cloud supports LWM2M over TCP secured with TLS (Transport Layer Security), and over UDP secured with DTLS (Datagram Transport Layer Security).

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:

PSK Parameter Value
Identity Device ID
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.

Workflow

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".

ARTIK Cloud enable device property

Connect a device

Connect a device to the ARTIK Cloud LWM2M server using the following information:

Parameter Value
Host coaps-api.artik.cloud
Port 5686
Endpoint name Device ID
PSK identity Device ID
PSK key Device token represented as hex string

Register

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:

ARTIK Cloud LWM2M registration flow

There are four phases:

Handshake

ARTIK Cloud requires a secure connection. This is the first step that must happen.

Send registration

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 pmin and pmax values. To do so, it sends a Write Attributes request on /3/0 (object 3, instance 0).

pmin and 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 pmin.

Observe object 3

After pmin and 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.

Post-registration

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.

Task execution

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

REST APIs for managing tasks are documented in the API reference. Also see the possible task statuses, device task statuses, and device task error codes.

Task expiration

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.

Task lifetime

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

Code Error message Condition
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