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 |
|
Observation unique id, generated by Live Objects |
paths |
|
Target paths of related device objects or attributes to observe |
status |
|
Current status of the Observation among |
name |
|
User-defined name for the Observation |
created |
|
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.
@startuml UC1
skinparam style strictuml
scale 0.7
participant CUSTOMER #LightGreen
participant "LiveObjects" as LO
participant "Device" as DEV
activate LO
note over CUSTOMER
Create a new Observation
end note
CUSTOMER -> LO : POST /api/v1/deviceMgt/devices/{deviceId}/twin/observations
note over LO
Validate and store the Observation
end note
LO -> CUSTOMER :
note left
The observation is in status PENDING
end note
activate DEV
alt the device is ONLINE
LO -> DEV : send the Observation
else the device is SLEEPING
DEV -> LO : lwm2m: update
LO -> DEV : send the Observation
else the device is OFFLINE
DEV -> LO : lwm2m: register
LO -> DEV : send the Observation
end
alt the Observation succeeds
DEV -> LO : response success
note over LO
the Observation is active
end note
CUSTOMER -> LO : GET /api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}
LO -> CUSTOMER :
note left
The observation is in status OBSERVING
end note
DEV -> LO : notify
note over LO
store the new values
end note
else the Observation fails
DEV -> LO : response error
CUSTOMER -> LO : GET /api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}
LO -> CUSTOMER :
note left
The observation is in status PENDING
end note
opt the error can be recovered
DEV -> LO : lwm2m: update
LO -> DEV : send the Observation
end
opt the maximum number of attempts has been reached
CUSTOMER -> LO : GET /api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}
LO -> CUSTOMER :
note left
The observation is in status FAILED
end note
end
end
== On new Register ==
DEV -> LO : lwm2m: register
LO -> DEV : send all Observations
== Cancellation ==
CUSTOMER -> LO : DELETE /api/v1/deviceMgt/devices/{deviceId}/twin/observations/{observationId}
LO -> CUSTOMER : OK
alt the device is ONLINE
LO -> DEV : cancel the Observation
DEV -> LO : OK
else
DEV -> LO : notify
LO -> DEV : cancel the Observation
end
@enduml
@startuml TwinObservationsStatus scale 0.8 title Twin Observations Status state PENDING : The observation is not active yet state OBSERVING #PaleGreen : The observation is active state FAILED #Pink [*] --> PENDING : user creation (north API) PENDING -[#green,bold]-> OBSERVING : Observation success PENDING -[#red,bold]-> PENDING : Observation failure PENDING -[#red,bold]-> FAILED : maximum number of \n attempts reached OBSERVING --> PENDING : De-registration \n or Registration expiration \n or new Registration FAILED --> PENDING : De-registration \n or Registration expiration \n or new Registration PENDING --> [*] : user cancellation OBSERVING --> [*] : user cancellation FAILED --> [*] : user cancellation @enduml
| 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.