LwM2M device Twin

Principle

The DeviceTwin is a Live Objects service that can collect, update and display the device resources information whether the device is connected to Live Objects or not.The device twin is created when the LwM2M device is created in Live Objects.Because the device twin representation is stored by Live Objects, the service can be collect and report device resources and state from apps and other services.

DeviceTwin feature is a way to define, retrieve or interact with a Twin representation of a device.

LiveObjectsTwin OperationsoperationsTwin ModelsTwin DevicesDevice twinreportedinstantiatedsupportedLWM2M DeviceREAD /3/0WRITE /3/0/1/3 Definition/1 Definition/0 Definition/3/0/0/3/0/9/3/0/0/3supported and instantiated objects,reported valuesOperations
Figure 1. Device twin features overview.

The way to define entities supported and instantiated by a device is called a TwinModel, it’s a list of ObjectsDefinitions where each object includes a list of AttributesDefinitions.

Note: LiveObjects TwinModel is compatible with OMA LWM2M model.

Each twin-capable physical device (LWM2M) connected to LiveObjects has an associated DeviceTwin:

  • a DeviceTwin is a list of supportedObjects, instantiatedObjects, and reportedValues.

  • it is possible to send orders (downlink) to a DeviceTwin using commands representation called TwinOperation.

And when a device reports value changes, LiveObjects could produce an associated data message under certain conditions. This condition are handled by a tenant DataRule entry.

Use cases

DeviceTwin use cases are

From Customer API

From Device to LiveObjects

  • a device uses Coap + LwM2M to talk to LiveObjects,

  • a device reports the supported and instantiated objects,

  • a device reports the attribute values.

  • a device respond to a twin operation. == Model

LiveObjects Twin Model is a specification of object definitions.

A Twin Model is a tree of objectDefinitions where each objectDefinition includes attributeDefinitions.

Twin Model is compatible with the OMA LWM2M Specifications.

ObjectDefinitionowner:StringobjectDefinitionId:String pathSegment:Stringname:stringdescription:StringminOccurs:IntegermaxOccurs:Integertype:ObjectTypeoperations:List<ObjectOperation>attributes:List<AttributeDefinition>parent:Stringchildren:List<String>ObjectTypeOBJECT,OBJECT_MAPObjectOperationREAD,WRITEAttributeDefinitionpathSegment:Stringname:Stringdescription:StringminOccurs:IntegermaxOccurs:Integertype:AttributeTypeoperations:List<AttributeOperation>AttributeTypeSTRING,INTEGER,UNSIGNED_INTEGER,BOOLEAN,FLOAT,BASE_64,DATE_TIMEAttributeOperationREAD,WRITE,EXECUTEparentchildren*111*1*111*
Figure 2. Overview of Twin Model

  • an ObjectDefinition can have 0, 1 or more children,

  • a root ObjectDefinition has no parent,

  • there is one root Object definition for LwM2M model (objectDefinitionId=urn:oma:lwm2m)

  • direct children of urn:oma:lwm2m are normalized.

Children ObjectDefinition of urn:oma:lwm2m represents LwM2M Objects, where a Twin Model AttributeDefinition represents a LwM2M Object Resource.

For example the Firmware Update LwM2M Object (Object Id=5) has a Resource called PkgName (Id=6):

Firmware Update LwM2M Object 5

landing

Model - ObjectDefinition

Firmware Update Object is represented by the following ObjectDefinition:

Field Value Comment

owner

A public definition has no owner.

objectDefinitionId

urn:oma:lwm2m:5:1.1

Object-definition unique identifier.

For example, objectDefinitionId urn:oma:lwm2m:5:1.1 refers to Object Id 5 in version 1.1 of the oma lwm2m

pathSegment

5

Current segment of the path

name

Firmware Update

Original name

description

…​

Description of the object

minoccurs

0

Minimal occurrence (0 means optional, 1 means mandatory and at least 1 is required)

maxoccurs

1

Maximal occurrence (0 means infinite instances are allowed (unbounded), 1 means maximum 1 instance is allowed

type

OBJECT_MAP

Type of object. possible values are OBJECT, OBJECT_MAP.

- OBJECT means that this is a single object

- OBJECT_MAP means that this object is a map of objects, and that a path of such an object instance is always using a map index.

In LwM2M, every object is of type OBJECT_MAP (except the root node)

operations

[ "READ", "WRITE" ]

Array of possible operations on the object. Possible values are READ, WRITE.

- READ : when applied on an Object, it means a READ operation for all the available Attributes of the Object.

- WRITE when applied on an Object, it means a WRITE operation on all the Attributes of the Object

parent

urn:oma:lwm2m

The objectDefinitionId of the parent object. All LwM2M objects are direct children of urn:oma:lwm2m.

attributes

[…​, {"pathSegment" : "6", "name" : "PkgName", "minoccurs" : 0, "maxoccurs" : 1, "type" : "STRING", "operations" : [ "READ"] } ]

A list of AttributeDefinition. For example, list of Firmware Update attributes.

Model - AttributeDefinition

PkgName Resource is represented by the following AttributeDefinition:

Field Value Comment

pathSegment

6

Current segment of the path

name

PkgName

Original name

description

…​

Description of the attribute

minoccurs

0

Minimal occurrence (0 means optional, 1 means mandatory and at least 1 is required)

maxoccurs

1

Maximal occurrence (0 means infinite instances are allowed (unbounded), 1 means maximum 1 instance is allowed

type

STRING

Type of attribute. Supported values are : STRING, INTEGER, UNSIGNED_INTEGER, BOOLEAN, FLOAT, BASE64, DATETIME.

- STRING : represented as UTF-8 string.

- INTEGER : represented as ASCII signed integer 1, 2,4 or 8 bytes

- UNSIGNED_INTEGER : represented as ASCII unsigned integer 1, 2,4 or 8 bytes

- BOOLEAN : represented as ASCII value 0 or 1

- FLOAT : represented as a 32 or 64-bit floating point values

- BASE64 : represented as a sequence of binary octets

- DATETIME : represented as a Unix Time. A signed integer representing the number of seconds since Jan 1st, 1970 in the UTC time zone

operations

[ "READ", "WRITE", "EXECUTE" ]

Array of possible operations on the attribute. Possible values are READ, WRITE, EXECUTE.

- EXECUTE, only on an attribute, it means a EXECUTE operation on the Attribute of the Object

Model management

In the Twin Model, we distinguish two types of models:

  • public models that are defined for the entire LiveObjects platform. For LwM2M, the ObjectIDs can range from 0 to 32768.

  • custom models that are defined per LiveObjects account. For LwM2M, the ObjectIDs are restricted to the 10241 - 42800 range.

For a given ID, the custom model takes precedence over the public model if both exist.
For the LwM2M protocol, models with IDs between 10241 and 32768 are published by the OMA, so care should be taken when defining a custom model in this range as it may override a public model for the account.

More details on the different ObjectID classes defined by the OMA for LwM2M can be found in the LwM2M Registry.

Public model

Objects from public range are managed by LiveObjects.

A (managed) public object definition :

  • has an empty owner attribute.

Public object definitions can’t be removed.

Custom model

A customer can extend the model by importing new Custom Object definitions.

This extension is called "Customer defined twin model". This model will apply for all twin devices of the customer account.

Using Twin Model Management API you can import a custom LWM2M OMA compatible XML Files, or delete a given customer model.

See this chapter for examples of Twin Model Management API usage which give you how to manage your custom objects.

Custom model limits

Some limits on custom models apply :

  • The number of custom model per tenant is limited.

Model API

Get Object-Definitions

Read TwinModels by giving an objectDefinitionId :

  • use urn:oma:lwm2m root element to list as children all LwM2M ObjectDefinitions.

  • use a urn:oma:lwm2m:oma:<Id>:<Version> format, and replace Id, Version to get a given LwM2M Object.

For example, urn:oma:lwm2m:oma:5:1.1 will get the Object Id=5 in Version=1.1.

Request

Endpoint:

GET /api/v1/deviceMgt/twin/model/object-definitions/{objectDefinitionId}

The usage is described here : Swagger API documentation.

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Example:

GET /api/v1/deviceMgt/twin/model/object-definitions/urn:oma:lwm2m:oma:5:1.1

Response

HTTP Code:

200 OK

Body:

{
  "objectDefinitionId": "urn:oma:lwm2m:oma:5:1.1",
  "pathSegment": "5",
  "name": "Firmware Update",
  "description": "Firmware Update Object",
  "minOccurs": 0,
  "maxOccurs": 1,
  "type": "OBJECT_MAP",
  "operations": [
    "READ",
    "WRITE"
  ],
  "attributes": [
    [.../...]
    {
      "pathSegment": "6",
      "name": "PkgName",
      "description": "Package name",
      "minOccurs": 0,
      "maxOccurs": 1,
      "type": "STRING",
      "operations": [
        "READ"
      ]
    },
    [.../...]
  ],
  "parent": "urn:oma:lwm2m"
}

Post Object-Definitions

Import an ObjectDefinition (a custom Twin Model) :

  • set LWM2M format,

  • provide an OMA Compatible XML File,

  • decide whether the definition should be overwritten or not if it already exists.

Request

Endpoint:

POST /api/v1/deviceMgt/twin/model/object-definitions?inputFormat=lwm2m&override=true

The usage is described here : Swagger API documentation.

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Body (form-data):

file: <XML File>

Response

HTTP Code:

201 Created

Body:

{
    "objectDefinitionId": "urn:oma:lwm2m:ext:33442",
    "pathSegment": "33442",
    "name": "LwM2M v1.1 Test Object CUSTOM CUSTOM",
    "description": "This object is created by the customer.",
    "minOccurs": 0,
    "maxOccurs": 0,
    [.../...],
    "parent": "urn:oma:lwm2m",
    "owner": "6139d13394f6b376e447ff9d"
}
Notice that the imported model owner attribute is the customer id.

Delete Object-Definitions

Remove an ObjectDefinition (a custom Twin Model) :

  • provide an ObjectDefinitionId.

Request

Endpoint:

DELETE /api/v1/deviceMgt/twin/model/object-definitions/{objectDefinitionId}

The usage is described here : Swagger API documentation.

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Response

HTTP Code:

204 No content == DeviceTwin

LiveObjects DeviceTwin is a Twin representation of the real device:

  • which objects are supported

  • which objects are instantiated

  • which are the instantiated objects last reported attributes values

TwinDeviceString deviceIdSet<String> supportedObjectsSet<InstantiatedObject> instantiatedObjectsSet<ReportedValue> reportedValuesInstantiatedObjectString pathString objectDefinitionIdReportedValueString pathString valueOffsetDateTime timestampinstantiatedObjects1*reportedValues1*
Figure 3. DeviceTwin overview

A DeviceTwin includes :

  • supportedObjects as a list of objectDefinitionId : list Object definitions supported by the device.

  • instantiatedObjects as a list of Object : list of Object implemented by the device.

  • reportedValues as a list of AttributeValue : list of Attributes values reported by the device

In addition, LiveObjects provides three ways to represents a given DeviceTwin :

RootObject

RootObject is represented by the following :

Field Value Comment

objectDefinitionId

urn:oma:lwm2m

Parent of the ObjectDefinition identifier.

path

/

Root path

children

[]

Children Object

Object

Object is represented by the following :

Field Value Comment

objectDefinitionId

urn:oma:lwm2m:5:1.1

ObjectDefinition identifier.

path

/5

Object path : object (OBJECT_MAP) 5

instances

[]

List of ObjectInstance

ObjectInstance

ObjectInstance is represented by the following :

Field Value Comment

objectDefinitionId

urn:oma:lwm2m:5:1.1

ObjectDefinition identifier.

path

/5/0

Object path : object (OBJECT_MAP) 5 instance 0

attributes

[]

List of Attribute

Attribute

Attribute is represented by the following :

Field Value Comment

path

/5/0/3

Attribute path : object 5 instance 0 attribute 3. A root Object has an empty path.

/1/4/25/0

Attribute path : object 1 instance 4 multi-instances attribute 25 instance 0.

content

AttributeValue

Single instance attribute

contents

List<AttributeValue>

Multi-instances attributes

When an attribute is a single-instance attribute, his value is reported as content, whereas a multi-instances attribute is reported as contents. == DeviceTwin API

Get supported objects

Read DeviceTwin supported objects.

Request

Endpoint:

GET /api/v1/deviceMgt/devices/{deviceId}/twin/supported-objects

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/supported-objects

Response

HTTP Code:

200 OK

Body:

["urn:oma:lwm2m:oma:1", "urn:oma:lwm2m:oma:2", "urn:oma:lwm2m:oma:3", "urn:oma:lwm2m:oma:4", "urn:oma:lwm2m:oma:5:1.1"]

This response is the list of supported object definition identifiers for a DeviceTwin.

Get instantiated objects

Read DeviceTwin instantiated objects.

Request

Endpoint:

GET /api/v1/deviceMgt/devices/{deviceId}/twin/objects

Query parameters:

Name Description

expand

Optional. If 1 then children objects are expanded with their instances. 0 by default

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/objects?expand=1

Response

HTTP Code:

200 OK

Body:

{
    "objectDefinitionId": "urn:oma:lwm2m",
    "path": "/",
    "children": [
        {
            "objectDefinitionId": "urn:oma:lwm2m:oma:1",
            "path": "/1",
            "instances": [
                {
                    "objectDefinitionId": "urn:oma:lwm2m:oma:1",
                    "path": "/1/0"
                },
                {
                    "objectDefinitionId": "urn:oma:lwm2m:oma:1",
                    "path": "/1/1"
                }
            ]
        },
        {
            "objectDefinitionId": "urn:oma:lwm2m:oma:2",
            "path": "/2",
            "instances": [
                {
                    "objectDefinitionId": "urn:oma:lwm2m:oma:2",
                    "path": "/2/0"
                },
                {
                    "objectDefinitionId": "urn:oma:lwm2m:oma:2",
                    "path": "/2/1"
                }
            ]
        },
        {
            "objectDefinitionId": "urn:oma:lwm2m:oma:3",
            "path": "/3",
            "instances": [
                {
                    "objectDefinitionId": "urn:oma:lwm2m:oma:3",
                    "path": "/3/0"
                }
            ]
        }
    ]
}

This response is a RootObject with the list of children objects (instantiated objects) for a DeviceTwin.

Get detailed object

Read DeviceTwin detailed object.

Request

Endpoint:

GET /api/v1/deviceMgt/devices/{deviceId}/twin/objects/{objectId}

Query parameters:

Name Description

expand

Optional. If 1 then instances are expanded with their attributes having reported values. 0 by default

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/objects/1?expand=1

Response

HTTP Code:

200 OK

Body:

{
    "objectDefinitionId": "urn:oma:lwm2m:oma:1",
    "path": "/1",
    "instances": [
        {
            "objectDefinitionId": "urn:oma:lwm2m:oma:1",
            "path": "/1/0",
            "attributes": [
                {
                    "pathSegment": "5",
                    "path": "/1/0/5",
                    "content": {
                        "reportedValue": "1",
                        "timestamp": "2021-09-30T09:25:06.687Z"
                    }
                },
                {
                    "pathSegment": "25",
                    "path": "/1/0/25",
                    "contents": [
                        {
                            "reportedValue": "v1/1.1.2",
                            "timestamp": "2021-11-15T17:14:06.687Z",
                            "path": "/1/0/25/0"
                        },
                        {
                            "reportedValue": "v1/1.BIS",
                            "timestamp": "2021-11-15T17:14:06.687Z",
                            "path": "/1/0/25/1"
                        }
                    ]
                }
            ]
        },
        {
            "objectDefinitionId": "urn:oma:lwm2m:oma:1",
            "path": "/1/1",
            "attributes": [
                {
                    "pathSegment": "3",
                    "path": "/1/1/3",
                    "content": {
                        "reportedValue": "1",
                        "timestamp": "2021-09-30T09:25:06.687Z"
                    }
                }
            ]
        }
    ]
}

This response is an Object (instantiated objects and reported values) for a DeviceTwin.

Get detailed object instance

Read DeviceTwin detailed object instance.

Request

Endpoint:

GET /api/v1/deviceMgt/devices/{deviceId}/twin/objects/{objectId}/{instanceId}

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/objects/1/0

Response

HTTP Code:

200 OK

Body:

{
    "objectDefinitionId": "urn:oma:lwm2m:oma:1",
    "path": "/1/0",
    "attributes": [
        {
            "pathSegment": "5",
            "path": "/1/0/5",
            "content": {
                "reportedValue": "1",
                "timestamp": "2021-09-30T09:25:06.687Z"
            }
        },
        {
            "pathSegment": "25",
            "path": "/1/0/25",
            "contents": [
                {
                    "reportedValue": "v1/1.1.2",
                    "timestamp": "2021-11-15T17:14:06.687Z",
                    "path": "/1/0/25/0"
                },
                {
                    "reportedValue": "v1/1.BIS",
                    "timestamp": "2021-11-15T17:14:06.687Z",
                    "path": "/1/0/25/1"
                }
            ]
        }
    ]
}

This response is an ObjectInstance (instantiated object and reported values) for a DeviceTwin. == Operations

LiveObjects Twin operation is a representation of a real operation on a device:

  • READ - order the device to report some attributes,

  • WRITE - update or replace some object attributes values,

  • EXECUTE - execute some attributes.

  • WRITE-METADATA - update metadata (set, update, reset).

Operation definition

A Twin operation applies to a given device, includes a given type (read,write,execute, write-metadata), with some operation attributes (paths, values, options) and has a unique id (generated by LiveObjects).

Each operation orders a given action (or composite action) on a target device and the result of this action is visible within operation status and operation error attributes.

Example of Twin Operation:

    {
        "id": "b50d094e520a4d58ad367f2fb9afdf6f",
        "type": "READ",
        "paths": [
            "/1/0/0"
        ],
        "status": "OK",
        "created": "2022-03-07T16:03:51.609Z",
        "updated": "2022-03-07T16:04:09.263Z"
    }

This is a success and done READ operation.

Field Value Comment

id

b50d094e520a4d58ad367f2fb9afdf6f

Operation unique id, generated by LiveObjects

type

READ

Type of the operation.

paths

['/1/0/0', '/5/1/3']

Target paths of related device objects or attributes

values

 
[{"path":"/1/0/3", "value":"x"},
 {"path":"/5/0/3", "value":"y"}]

for WRITE and WRITE-METADATA: Values to set.

writeMode

REPLACE

for WRITE: mode to set. Possible values : UPDATE, REPLACE

contextToken

OPBIS123

Free custom tag on the operation

status

OK

Current status of Twin Operation

options

 
{"lwm2m": {"contentFormat": {"response": "SENML_JSON"} } }

Options of Twin Operation, cf. Operation options section.

policy.attempts

1

Number of attempts allowed for this operation (default value is 1 that means there is no retry).

error.code

OPERATION_INVALID

status FAILED only: Error code of Twin Operation.

error.details

details here

status FAILED only: Error details of Twin Operation.

error.deviceCode.value

404

status FAILED, error.code DEVICE_ERROR only: Device error value.

error.deviceCode.reason

404 not found

status FAILED, error.code DEVICE_ERROR only: Device error reason.

created

2022-02-24T16:30:06.687Z

When the operation were created.

updated

2022-02-24T17:01:00.122Z

When the operation were updated. In case of status OK, this is when the device responds.

WRITE-METADATA Operation details

Live Objects supports all LwM2M 1.1 notification attributes (named metadata in current chapter).

Those metadata define the conditions when notification on an objet or attribute is sent.

metadata Description

pmin

The Minimum Period metadata indicates the minimum time in seconds the LwM2M Client MUST wait between two notifications

pmax

The Maximum Period metadata indicates the maximum time in seconds the LwM2M Client MAY wait between two notifications

gt

This Greater Than metadata defines a threshold high value. When this metadata is present, the LwM2M Client MUST notify the Server each time the Observed Attribute value crosses this threshold

lt

This Less Than metadata defines a threshold low value. When this metadata is present, the LwM2M Client MUST notify the Server each time the Observed Attibute value crosses this threshold

st

This Step metadata defines a minimum change value between two notifications

epmin

The Minimum Evaluation Period metadata indicates the minimum time in seconds the LwM2M Client MUST wait between two evaluations of reporting criteria

epmax

The Maximum Evaluation Period metadata indicates the maximum time in seconds the LwM2M Client MAY wait between two evaluations of reporting criteria

Operation options

Operation options apply on the following use-cases:

Scope Key Possible values Comment

Lwm2m operation

lwm2m.contentFormat

TLV, JSON, SENML_JSON, SENML_CBOR, TEXT, OPAQUE, CBOR

content format requested by the customer for the operation (request, response)

Operation examples

Name Operation extract Details

READ all objects

 
{
   "type":"READ",
   "paths":["/"]
}

Read all objects

READ one object

 
{
   "type":"READ",
   "paths":["/5"]
}

Read object 5

READ one object instance

 
{
   "type":"READ",
   "paths":["/5/0"]
}

Read object 5 instance 0

READ one attribute

 
{
   "type":"READ",
   "paths":["/5/0/3"]
}

Read object 5 instance 0 attribute 3

READ one multi-instances attribute instance

 
{
  "type":"READ",
  "paths":["/1/4/11/4"]
}

Read object 1 instance 4 attribute 11 attribute instance 4

READ composite two objects, and one multi-instances attribute instance

 
{
   "type":"READ",
   "paths":["/3","/5","/1/4/11/4"]
}

Read objects 3, 5 and an attribute instance /1/4/11/4

WRITE one attribute in update mode

 
{
   "type":"WRITE",
   "writeMode":"UPDATE",
   "paths":["/1/0"],
   "values":[
       {"path":"/1/0/7", "value":"sample1"}
   ]
}

Write sample1 into object 1 instance 0 attribute 7. An WRITE operation requires one and only one path value in paths.

WRITE one multi-instances attribute instance in update mode

 
{
   "type":"WRITE",
   "writeMode":"UPDATE",
   "paths":["/1/4"],
   "values":[
       {"path":"/1/4/11/4", "value":"sample2"}
   ]
}

Write sample2 into attribute instance /1/4/11/4

WRITE two multi-instances attribute instances in update mode

 
{
   "type":"WRITE",
   "writeMode":"UPDATE",
   "paths":["/1/0/11"],
    "values":[
      {"path":"/1/0/11/0", "value":"sampleA"},
      {"path":"/1/0/11/2", "value":"sampleB"}]
}

Write sampleA into attribute instance /1/0/11/0, and sampleB into attribute instance /1/0/11/2

WRITE two multi-instances attribute instances in replace mode

 
{
   "type" : "WRITE",
   "writeMode":"REPLACE",
   "paths":["/1/0/11"],
   "values" : [
      { "path": "/1/0/11/0", "value":"sampleA" },
      { "path": "/1/0/11/2", "value":"sampleB" }
   ]
}

Write target /1/0/11 in replace mode : write sampleA into attribute instance /1/0/11/0, and write sampleB into attribute instance /1/0/11/2, and remove other /1/0/11 attributes.

WRITE multiple attributes on object instance in update mode

 
{
  "type":"WRITE",
  "writeMode":"UPDATE",
  "paths":["/1/0"],
  "values":[
     { "path": "/1/0/7", "value":"sampleD" },
     { "path": "/1/0/11/2", "value":"sampleE" },
     { "path": "/1/0/11/0", "value":"sampleF" }
  ]
 }

Write in update mode /1/0/7, /1/0/11/2, /1/0/11/0 values, and only them.

WRITE multiple attributes on object instance in replace mode

 
{
  "type": "WRITE",
  "writeMode":"REPLACE",
  "paths": [ "/1/0" ],
  "values":[
     { "path": "/1/0/7", "value":"sampleD" },
     { "path": "/1/0/11/2", "value":"sampleE" },
     { "path": "/1/0/11/0", "value":"sampleF" }
  ]
}

Write /1/0 in replace mode : set /1/0/7, /1/0/11/2, /1/0/11/0 values, and remove other /1/0 attributes.

WRITE composite multiple attributes on different objects in update mode

 
{
  "type": "WRITE",
  "writeMode":"UPDATE",
  "paths": [ "/" ],
  "values":[
      { "path": "/2/1/6", "value":"sampleX" },
      { "path": "/1/0/7", "value":"sampleY" },
      { "path": "/1/0/4/1", "value":"sampleZ" }
  ]
}

Write in update mode /2/1/6, /1/0/7, /1/0/4/1 values, and only them. It’s a composite WRITE because target paths scope different objects instances : /2/1 and /1/0

WRITE composite multiple attributes on different object instances

 
{
  "type": "WRITE",
  "writeMode":"UPDATE",
  "paths": [ "/" ],
  "values":[
     { "path": "/1/0/7", "value":"sampleV" },
     { "path": "/1/1/7", "value":"sampleW" }
  ]
}

Write in update mode /1/0/7, /1/1/7 values, and only them. It’s a composite WRITE because target paths scope different objects instances : /1/0 and /1/1

EXECUTE execute a given attribute

 
{
  "type": "EXECUTE",
  "paths" : [ "/1/0/8" ]
}

Execute /1/0/8 attribute. An EXECUTE operation requires one and only one path value in paths.

WRITE-METADATA update metadata

 
{
  "type": "WRITE-METADATA",
  "values": [
    {
      "path": "/1/0/7",
      "metadata": [
        {
          "name": "pmin",
          "value": "20"
        },
        {
          "name": "gt",
          "value": "50"
        },
        {
          "name": "lt"
        }
      ]
    }
  ]
}

Update metadata on /1/0/7 (set or update pmin and gt and reset lt metadata)

A WRITE-METADATA operation requires one and only one path that could identify an object, an object instance, an attribute or an attribute instance.

Operation lifecycle

A Twin operation is created using API and the result of an operation will be available via API too.

Once created, the operation is executed asynchronous as soon as the device become twin capable (ex. the device connect and his interface become online).

LiveObjectsDeviceCUSTOMERLiveObjectsDeviceCUSTOMERLiveObjectsDeviceLiveObjectsDeviceCreate a new operationPOST/api/v1/deviceMgt/devices/{deviceId}/twin/operationsValidate and storePENDINGoperation<operation created>Device is now herelwm2m: registerupdatePENDINGdevice operation(s) toSENTsend operation(s)Op1 responseupdate Op1 toOKOp2 response FAILED event (not retryable case or max attempts reached))update Op2 toFAILEDOp3 response FAILED event (retryable case)update Op3 toRETRYINGGET/api/v1/deviceMgt/devices/{deviceId}/twin/operations<operations>
Figure 4. TwinOperation sequence diagram

API allow to monitor the status of the operation waiting for a final state by using a given operation id, and polling the GET API.

Twin Operations StatusPENDINGDevice is not listening yetWaiting for Capability=TRUESENTConnector is processingthe operationCANCELLEDEXPIREDFAILEDOKRETRYINGuser creation (north API)timeout (x days)user cancellationTwin Capability goes TRUESuccessful responseError responsetimeout (y minutes)retryable andmax attempts not reachedelsemax attemptsnot reachedelseTwin Capabilitygoes TRUEtimeout (x days)
Figure 5. TwinOperation status and state machine
status Comment

PENDING

Operation is created and ready to be sent.

SENT

Operation has been emitted from Twin Service to the connector then the device.

RETRYING

Operation didn’t succeed but the reason of the error allows a retry.

CANCELLED

A pending operation has been cancelled by user (via API). It is a final state.

EXPIRED

A pending or sent operation has remained in the same state for too long. It is a final state.

FAILED

For some reason, the operation didn’t succeed. The reason why it failed is described by error fields. It is a final state.

OK

Operation succeed. It is a final state.

The following expiration delay applies:

origin status Schema reference Comment

from PENDING

x

If a device never registers, a PENDING operation moves to EXPIRED after 3 days.

from SENT

y

If a response is not received after 25 minutes, a SENT operation moves to RETRYING if max attempt is not reached else the SENT operation moves to EXPIRED.

from RETRYING

x

If a device never registers, a RETRYING operation moves to EXPIRED after 3 days.

Operation retry policy

For errors that are considered as unrecoverable (e.g device rejected the request), there will be only one attempt to send an operation.

For other errors there will be additional attempts limited to the number of attempts provided by the end user. For instance, we can mention a 5xx response or a time-out.

The operation is executed asynchronously as soon as the device becomes twin capable (ex. the device connects and its interface becomes online).

DeviceTwin ServiceDM Inventory ServiceLWM2M ServiceCUSTOMERDeviceTwin ServiceDM Inventory ServiceLWM2M ServiceCUSTOMERDeviceTwin ServiceDM Inventory ServiceLWM2M ServiceDeviceTwin ServiceDM Inventory ServiceLWM2M ServiceOperation(s) has been previously inRETRYINGstatusDevice is now herenode status ONLINEtwin capability=trueonCapabilityUpdatedupdateRETRYINGdevice operation(s) toSENTsend operation(s)operation Op1 response OK eventupdate Op1 toOKoperation Op2 response FAILED event (not retryable case or max attempts reached)update Op2 toFAILEDoperation Op3 response FAILED event (retryable case) and max attempts not reached)update Op3 toRETRYING
Figure 6. TwinOperation retrying sequence diagram

Operation limits

Some limits apply in terms of :

  • actives operations per device : operations having PENDING, SENT, RETRYING status. Other this limit, an operation creation attempt will fail (with 403 status).

  • final operations per device : operations having UNKNOWN, CANCELLED, EXPIRED, FAILED or OK status. Other this limit, at creation of new operation time, older operations will be removed. == Operations API

This section includes API call examples for the Twin Operations management.

Create an operation

Create a new DeviceTwin operation.

According to the operation lifecycle, this will create a PENDING operation.

Different kinds of Twin operation are described by twin operation definition and twin operation examples.

Example:

POST /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/operations
{
"type":"READ",
"paths":["/1/0"],
"contextToken" : "this is a simple READ"
}

Response

201 CREATED
{
    "id": "f9b9877c7679454ea56e568b31ee7c48",
    "type": "READ",
    "paths": [
        "/1/0"
    ],
    "contextToken": "this is a simple READ",
    "status": "PENDING",
    "created": "2022-02-25T09:32:55.248Z",
    "updated": "2022-02-25T09:32:55.248Z"
}

A pending DeviceTwin READ instance /1/0 operation has been created.

Cancel a pending operation

Cancel a PENDING DeviceTwin operation.

Example:

PUT /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/operations/f2ed1637ec10466089064804ed68e351/status
"CANCELED"

Response

200 OK

This response confirm that Twin Operation status has been set to CANCELED.

Get an operation

Get one DeviceTwin operation.

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/operations/a1ca9551754d48d09e31fd30d36b88d1

Response

200 OK
{
    "id": "a1ca9551754d48d09e31fd30d36b88d1",
    "type": "READ",
    "paths": [
        "/1/0"
    ],
    "contextToken": "ABC123",
    "status": "OK",
    "created": "2022-02-11T16:16:05.073Z",
    "updated": "2022-02-11T16:16:23.492Z"
}

This is a Twin Operation details.

List operations

List DeviceTwin operations.

Some filter could apply to restrict the results :

parameter description

status

<list> restrict to operations having this status

contextToken

restrict to operations having this contextToken (exact match)

type

<list> restrict to operations having this type

path

restrict to operations having at least one time this path in his definition (exact match)

Number of result is constraint by Twin operations limits.

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/operations?status=OK&status=FAILED&status=EXPIRED&type=READ

Response

200 OK
[
    {
        "id": "f2ed1637ec10466089064804ed68e351",
        "type": "READ",
        "paths": [
            "/1/0"
        ],
        "contextToken": "ABC123",
        "status": "OK",
        "created": "2022-02-11T16:16:05.073Z",
        "updated": "2022-02-11T16:16:23.492Z"
    },
    {
        "id": "25a65010ab9b4c38a925c2dc7f16a7c8",
        "type": "READ",
        "paths": [
            "/1/0/200",
            "/1/0/7"
        ],
        "status": "FAILED",
        "error": {
            "code": "OPERATION_INVALID",
            "details": "The details here"
        },
        "created": "2022-02-16T15:20:24.142Z",
        "updated": "2022-02-16T15:20:34.252Z"
    }
 ]

This response is the list of Twin Operations of a DeviceTwin

  • having status in [OK, FAILED, EXPIRED],

  • having type in [READ]. == Observations

Observation definition

An Observation allows Live Objects to be notified when some Attributes change on the device. It can target:

  • a specific Attribute

  • an Object Instance

  • all Object Instances of an Object

  • several Attributes (Observation Composite)

Example of an Observation targeting an Object Instance:

{
    "id": "631f1190d4135d0066541e8b",
    "paths": [
        "/6/0"
    ],
    "status": "PENDING",
    "name": "Observation on the location Object",
    "created": "2022-09-12T11:02:29.811Z"
}
Field Example Comment

id

631f1190d4135d0066541e8b

Observation unique id, generated by Live Objects

paths

['/6/0']

Target paths of related device objects or attributes to observe

status

PENDING

Current status of the Observation among PENDING, OBSERVING and FAILED

name

Observation on the location Object

User-defined name for the Observation

created

2022-09-12T11:02:29.811Z

Observation creation date

Observation Lifecycle

An Observation is created using the API and its status will be available via the API too.
Once created, the Observation is sent immediately if the device is ONLINE or the next time the device sends an Update or Register otherwise.
Depending on the type of error, Observations that have failed can be automatically re-sent at the next Update. The number of attempts is nevertheless limited.
When a LwM2M device goes offline (de-registration or the lifetime of the registration expires), the Observations on Live Objects for this device go back to the PENDING state. They will be automatically re-sent when the device sends a Register, regardless of their status.
An Observation can be cancelled. Upon the user cancellation request, a Cancel Observation operation is sent to the device if it is ONLINE. Otherwise, the cancellation occurs at the next Notify.

LiveObjectsDeviceCUSTOMERLiveObjectsDeviceCUSTOMERLiveObjectsDeviceLiveObjectsDeviceCreate a new ObservationPOST/api/v1/deviceMgt/devices/{deviceId}/twin/observationsValidate and store the Observation<Observation created>The observation is in statusPENDINGalt[the device is ONLINE]send the Observation[the device is SLEEPING]lwm2m: updatesend the Observation[the device is OFFLINE]lwm2m: registersend the Observationalt[the Observation succeeds]response successthe Observation is activeGET/api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}<observation>The observation is in statusOBSERVINGnotifystore the new values[the Observation fails]response errorGET/api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}<observation>The observation is in statusPENDINGopt[the error can be recovered]lwm2m: updatesend the Observationopt[the maximum number of attempts has been reached]GET/api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}<observation>The observation is in statusFAILEDOn new Registerlwm2m: registersend all ObservationsCancellationDELETE/api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}OKalt[the device is ONLINE]cancel the ObservationOKnotifycancel the Observation
Figure 7. Observation sequence diagram
Twin Observations StatusPENDINGThe observation is not active yetOBSERVINGThe observation is activeFAILEDuser creation (north API)Observation successDe-registrationor Registration expirationor new RegistrationObservation failuremaximum number ofattempts reachedDe-registrationor Registration expirationor new Registrationuser cancellationuser cancellationuser cancellation
Figure 8. Observation state machine
status Comment

PENDING

The Observation has been created and is ready to be sent.

FAILED

The Observation has not succeeded after the maximum number of attempts.

OBSERVING

The Observation is active on the device.

Observation retry policy

For errors that are considered as unrecoverable, there will be only one attempt to send an Observation. The following errors fall in this category:

  • The device responded with a 4xx code

  • The device rejected the request

For other errors there will be 5 attempts. For instance, we can mention a 5xx response or a time-out.

Observation configuration

The parameters related to an Observation can be configured by the Write-Metadata operation.

Observation limits

The number of Observations per device is limited regardless of their status. == Observations API

This section includes API call examples for the Observations management.

Create an Observation

Create a new Observation.

According to the Observation lifecycle, this will create a PENDING Observation.

Example:

POST /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/observations
{
    "paths": [
        "/6/0"
    ],
    "name": "Observation on the location Object"
}

Response

201 CREATED
{
    "id": "631f1190d4135d0066541e8b",
    "paths": [
        "/6/0"
    ],
    "status": "PENDING",
    "name": "Observation on the location Object",
    "created": "2022-09-12T11:02:29.811Z"
}

A pending Observation has been created.

Cancel an Observation

Cancel an Observation.

Example:

DELETE /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/observations/631f1190d4135d0066541e8b

Response

204 NO CONTENT

This response confirm that the Observation has been removed and will be cancelled on the device.

Get an Observation

Get one Observation.

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/observations/631f1190d4135d0066541e8b

Response

200 OK
{
    "id": "631f1190d4135d0066541e8b",
    "paths": [
        "/6/0"
    ],
    "status": "OBSERVING",
    "name": "Observation on the location Object",
    "created": "2022-09-12T11:02:29.811Z"
}

This is an Observation details.

List Observations

List Observations.

The number of result is constraint by Twin Observations limits.

Example:

GET /api/v1/deviceMgt/devices/urn:lo:nsid:lwm2m:mydevice/twin/observations

Response

200 OK
[
    {
        "id": "62d6c3230d0685589727902e",
        "paths": [
            "/3303/0"
        ],
        "status": "FAILED",
        "name": "Observation on the temperature Object",
        "created": "2022-07-19T14:43:47.023Z"
    },
    {
        "id": "631f1190d4135d0066541e8b",
        "paths": [
            "/6/0"
        ],
        "status": "OBSERVING",
        "name": "Observation on the location Object",
        "created": "2022-09-12T11:02:29.811Z"
    }
]

This response is the list of Observations of a DeviceTwin == DataRules

LiveObjects Twin data rule is a representation of a rule that can be used to trigger a new data message from device reported values.

DataRule definition

A Twin data rule applies to a given tenant, includes a given type, with some rule attributes (paths) and has a unique id (generated by LiveObjects).

A tenant data rule presence drives the way twin message will be generated.

Twin data rule type are:

  • PASSTHROUGH - order twin to forward all values that match paths as new data message.

Example of Twin data rule:

    {
        "id": "6250072f5297c340e68f7bad",
        "name": "my passthrough",
        "type": "PASSTHROUGH",
        "paths": [
            "/"
        ],
        "created": "2022-04-08T09:58:07.843Z"
    }

This is a PASSTHROUGH data rule that triggers all values (having path starting with /).

Field Value Comment

id

6250072f5297c340e68f7bad

Data rule unique id, generated by LiveObjects

type

PASSTHROUGH

Type of the rule.

paths

['/']

Target paths of related rule

created

2022-04-08T09:58:07.843Z

When the rule were created.

Data rules limits

For now, you can only create one PASSTHROUGH rule for your tenant.

Data rules API

Data rules management API are available at following endpoint: /api/v1/deviceMgt/twin/data/rules and are documented on Swagger. == Data Message

When a LWM2M device reports value changes, a data message that includes this change is generated by LiveObjects under certain conditions:

  • the report must be at the device initiative (send, or notify but not read response),

  • the report must match a given data rule of the tenant.

When all these conditions are met, a message is generated.

Today the generation model used for the message is twin_json.

DataMessage common attributes

A Twin data message as other LiveObjects messages, will embed some common attributes: id, streamId, etc.

The value part of the message will embed the device reported values representation, depending on the model used.

Example of a fill Twin data message having twin_json model:

{
  "id": "6254192e1a52727da422dfdf",
  "streamId": "urn:lo:nsid:lwm2m:simulator",
  "timestamp": "2022-04-11T12:03:58.695Z",
  "model": "twin_json",
  "value": {
    "device": {
      "0": {
        "deviceType": "Demo",
        "utcOffset": "Z",
        "serialNumber": "LT-500-000-0001",
        "timezone": "Etc/UTC",
        "memoryFree": 6278,
        "errorCode": {
          "0": 0
        },
        "supportedBindingAndModes": "U",
        "manufacturer": "Leshan Demo Device",
        "currentTime": "2022-04-11T12:03:58Z",
        "batteryStatus": 6,
        "memoryTotal": 19400,
        "modelNumber": "Model 500",
        "hardwareVersion": "1.0.1",
        "firmwareVersion": "1.0.0",
        "softwareVersion": "1.0.2",
        "batteryLevel": 44
      }
    }
  },
  "tags": [
    "lwm2m-simulator",
  ],
  "extra": {},
  "metadata": {
    "source": "urn:lo:nsid:lwm2m:simulator",
    "group": {
      "id": "root",
      "path": "/"
    },
    "connector": "lwm2m",
    "network": {
      "lwm2m": {
        "ep": "urn:lo:nsid:lwm2m:simulator"
      }
    }
  },
  "created": "2022-04-11T12:03:58.725Z"
}

This message is generated by the urn:lo:nsid:lwm2m:simulator lwm2m endpoint and embed a twin_json representation of some device instance 0 attributes (reported values).

DataMessage TWIN_JSON format

A TWIN_JSON data message is a JSON representation of reported values that include camel case human-readable entity names.

In a TWIN_JSON data message, each value is embedded in an object, plus an attribute container.

Reminder: Object, Attribute definitions are part of the TwinModel.

For a simple attribute the JSON message will be generated according the following design:

  • camel case name of the object,

  • pathSegment id of the object,

  • camel case name of the attribute,

  • reported raw value of the attribute.

For example, for a given [/3/0/1, /3/0/9] reported values, associated twin model definitions are:

  • Object 3 : Device - Instance 0

  • Attribute 1: Model Number.

  • Attribute 9: Battery Value.

Related TWIN_JSON of these values will be:

{
  "device": {
    "0": {
      "modelNumber": "Model 500",
      "batteryLevel": 44
    }
  }
}

DataMessage metadata enrichment

A Twin data message as other LiveObjects messages, may embed some metadata.

They are extracted from reported values.

Currently, extracted metadata are:

Metadata Description Source Target

location

location of the device

\6\0\0 to \6\0\3

Object 6 : Location - Instance 0

  • Attribute 0: Latitude

  • Attribute 1: Longitude

  • Attribute 2: Altitude

  • Attribute 3: Radius (Accuracy)

see location provided by the device chapter
Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC