Filter results by

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.

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 services and will send periodic registration updates to ARTIK cloud services.

LWM2M Operations

LWM2M Core operations

ARTIK cloud services support 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 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.

ARTIK cloud services automatically initiate the Observe operation during the device registration workflow.

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 pmin and pmax values 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
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 services 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 services support 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 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
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 services support 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 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:

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.

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.

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 services 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 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:

ARTIK Cloud LWM2M registration flow

There are four phases:

Handshake

ARTIK cloud services require 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 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 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 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.

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