Manage devices using LWM2M
ARTIK cloud services use the LWM2M protocol to manage Device Properties for device types. Device Properties are one of three types of properties ARTIK cloud services recognize 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 services are 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 services support a subset of LWM2M objects and resources. A device sends its LWM2M resources to ARTIK cloud services, which in turn stores and represents them as Device Properties in the Device Mirror.
ARTIK cloud services recognize two other types of properties for device management: Server Properties and System Properties, which are discussed in Device Mirror.
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 services and will send periodic registration updates to ARTIK cloud services.
LWM2M Core operations
ARTIK cloud services support 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 services.
A device type owner can initiate Read, Write, and Execute operations for their devices by creating device management tasks. ARTIK cloud services then communicate to the device to perform LWM2M operations.
LWM2M Administrative operations
ARTIK cloud services support the following administrative operations to manage devices through LWM2M:
- Registration: A device must first register with ARTIK cloud services before any of the above core operations can be performed on it. If a device is not registered, ARTIK cloud services 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 services can write attributes to a device for objects or resources. For example, ARTIK cloud services write the
pmaxvalues used in observation (see below).
Objects and resources
ARTIK cloud services support 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 services 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 services 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 services support only one instance of an object, which will always be instance 0.
Data type conversion
LWM2M objects are translated as collections in the properties Manifest. Every LWM2M resource has a data type. The following table lists the LWM2M resource data types and their corresponding Device Property data type on ARTIK cloud services.
|LWM2M Data Type||Device Property Data Type|
|Time||Long (milliseconds since epoch)|
TCP is preferred over UDP, since devices communicate with ARTIK cloud services 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.
Client X.509 certificates
Client certificates can be used to establish the secure connection and verify authenticity of the device. A device uses the client certificate that is generated for secure device registration. Client certificates are supported for both UDP and TCP protocols.
A device whose device type is securely registered must use client certificates to connect via LWM2M.
When using client certificates over UDP, the device token is not required. When using client certificates over TCP, the device token is still required.
Certificates must use ECDHE_ECDSA key exchange mechanism as described in the LWM2M specification.
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 services 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 services over LWM2M, you must register it with ARTIK cloud services before you can manage its Device Properties. Below is the high-level registration flow:
There are four phases:
ARTIK cloud services require 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 services send 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 services 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 services set
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 services send an Observe request on /3/0 (object 3, instance 0). The device must immediately send back the resource values as the response. ARTIK cloud services update 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 services continually receive updates of resource values from the device and then updates the corresponding Device Mirror.
- ARTIK cloud services send a Read request to read the value of a resource.
- ARTIK cloud services send a Write request to write a new value to a resource.
- ARTIK cloud services send 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 services.