/
ADM Transactions

ADM Transactions

The OMA SpecWorks LightweightM2M (LwM2M) protocol SHALL be used as the interoperable management protocol for the following GEISA functions:

  • Application Management

  • Device Management

  • Network Management

To facilitate the broadest interoperability, GEISA-compliant LwM2M Management Servers (MS) and Edge Environments (EE) SHALL at minimum support LwM2M version 1.1 and DTLS version 1.2, and MUST support the Mandatory resources of the most recent version of the following LwM2M objects and operations:

Screen Shot 2025-08-05 at 4.17.38 PM.png
LwM2M Interfaces

To enable scalable and interoperable management, GEISA-compliant MS and EE MUST support the following LwM2M Interfaces:

  1. Bootstrap

  2. Registration

  3. Device Management

  4. Information Reporting

Bootstrap Interface

GEISA EE MUST support one or more of the following LwM2M Bootstrap methods:

  • Factory Bootstrap – Devices are provisioned during manufacturing with Security credentials and Management Server information. Upon field installation, devices connect directly to their Management Server to perform Registration.

  • Client-Initiated Bootstrap – Devices are provisioned during manufacturing with Bootstrap Server (BS) information. Upon field installation, devices initiate connection to the Bootstrap Server for the provisioning of Security credentials (object 0) and Management Server information.

Screen Shot 2025-08-05 at 3.54.06 PM.png
Client-Initiated Bootstrap

A GEISA compliant MS MUST provide a BS capability and support Client-Initiated Bootstrap.

Registration Interface

  • Registration – The LwM2M Registration process allows the GEISA EE to inform the MS of the device’s configuration and capabilities, and to request management by the MS. During Registration, the LwM2M Client in the EE reports to the Management Server the list of LwM2M Objects supported by the EE and its currently instantiated Object Instances.

  • Registration Update – Registration Update is a lightweight, empty Registration packet sent to the MS for the following reasons:

    • A periodic heartbeat from Client to Server to maintain the existing management session.

    • If any previous Registration information changes, for example:

      • EE IP Address changes

      • The objects supported by the EE changes after a firmware upgrade

image-20250818-185420.png
LwM2M Registration and Registration Update

Device Management Interface

The LwM2M Device Management and Service Enablement interface exposes the facility to perform device, application, and network management operations on a GEISA EE:

  • Discover – Used by a LwM2M Management Server to retrieve the list of Resources instantiated in each Object instance. Data (Resource Values) is not returned.

  • Read – Used by a MS to retrieve Resource data values (e.g., sensor reading). Reading may be performed at various levels: Resource Instance, entire Resource, Object Instance, entire Object

  • Read-Composite – Used by a MS to retrieve multiple Resources/Objects in single CoAP request.

  • Write – Used by a MS to modify Device configuration.

    • CoAP PUT is used to Replace the Object Instance or Resource(s) with the new values provided.

    • CoAP POST is used for Partial Update to update the Resources with the new values provided, leaving other existing Resources unchanged.

  • Write-Composite Used by a MS to update multiple Resources/Objects in single CoAP request.

  • Execute – Used by a MS to invoke commands on the EE (e.g., Factory Reset, Activate Edge App).

  • Create – Used by a MS to create new Object Instances on the LwM2M Client of the EE.

  • Delete – Used by a MS to delete Object Instances on the LwM2M Client of the EE.

  • Write-Attributes – Used by a MS to set Notification triggers for an Observe of a Resource/Object (e.g., Only send a Notification every two hours, only send a Notification if the observed value has changed by more than X).

Operation

CoAP Method

Path

Success

Failure

Read

GET

Accept: Content Format ID

/{Object ID}/{Object Instance ID}/{Resource ID}

2.05 Content

4.00 Bad Request, 4.01 Unauthorized, 4.04 Not Found, 4.05 Method Not Allowed,

4.06 Not Acceptable

Discover

GET

Accept: application/link-format

/{Object ID}/{Object Instance ID}/{Resource ID}

2.05 Content

4.00 Bad Request, 4.04 Not Found, 4.01 Unauthorized, 4.05 Method Not Allowed

Write

PUT

Content Format:

/{Object ID}/{Object Instance ID}/{Resource ID}

2.04 Changed

2.31* Continue

4.00 Bad Request, 4.04 Not Found, 4.01 Unauthorized, 4.05 Method Not Allowed,

4.06 Not Acceptable

4.08 Request Entity Incomplete

4.13 Request entity too large

POST

Content Format:

/{Object ID}/{Object Instance ID}

Write-Attributes

PUT

/{Object ID}/{Object Instance ID}/{Resource ID}?pmin={minimum period}&pmax={maximum period}&gt={greater than}&lt={less than}&st={step}

2.04 Changed

4.00 Bad Request, 4.04 Not Found, 4.01 Unauthorized, 4.05 Method Not Allowed

Execute

POST

/{Object ID}/{Object Instance ID}/{Resource ID}

2.04 Changed

4.00 Bad Request, 4.01 Unauthorized, 4.04 Not Found, 4.05 Method Not Allowed

Create

POST Content Format:

/{Object ID}

2.01 Created

4.00 Bad Request, 4.01 Unauthorized, 4.04 Not Found, 4.05 Method Not Allowed,

4.06 Not Acceptable

Delete

DELETE

/{Object ID}/{Object Instance ID}

2.02 Deleted

4.00 Bad Request, 4.01 Unauthorized, 4.04 Not Found, 4.05 Method Not Allowed

 

image-20250818-232637.png
Device Management Operations

 

image-20250818-232729.png
Object Creation and Deletion

The following two specific LwM2M Device Management operations of importance to GEISA involve complex multi-step transactions between the EE and MS and require further specification to promote interoperability:

  • Firmware Update - used to manage the GEISA EE firmware

  • Software Update - used to manage containerized edge applications hosted in the GEISA EE

Firmware Update

The LwM2M singleton object /5/0 Firmware Update represents the Firmware Update process, not simply the firmware image stored on the device. Object /5/0 is advertised during initial Registration, and object /5/0 is not deleted by the EE client after an upgrade; only the /5/0/3 State and /5/0/5 Update Result resources are reset after an upgrade to reflect the new baseline.

The multi-step Firmware Update transaction typically involves the MS Observe /5/0/3 State so that the EE client will provide asynchronous updates of client state changes to the MS, after which the MS will proceed with subsequent steps in the transaction. Although it is technically possible to Observe resources /5/0/3 and /5/0/5 following initiation of the update transaction, in order to avoid transaction dead locks or inconsistent state due to race conditions, and to provide optional support for resource /5/0/14 Automatic Upgrade at Download, a GEISA compliant MS SHALL perform the following:

  1. Observe /5/0/3 State when object /5/0 is advertised during EE Registration

  2. Read /5/0/5 Update Result after Notification that /5/0/3 State = Idle

Depending on MS capabilities, LwM2M allows either of the following methods for firmware image distribution to the EE:

  • PUSH (CoAP block-wise transfer) via WRITE of the opaque binary image to /5/0/0 Package

  • PULL via WRITE to resource /5/0/1 Package URI for the EE to download via CoAP/HTTP as soon as practical

The following sequence diagrams provide two examples of GEISA compliant upgrades of the EE firmware. The first example demonstrates the following:

  1. PUSH of the firmware image to /5/0/0 Package

  2. The MS performing a manual Execute /5/0/2 to trigger the upgrade

Firmware Push.png
PUSH image with Manual Update

The next example demonstrates the following:

  1. PULL of the firmware image from the URL set by the MS into /5/0/1 Package URI

  2. The EE automatically executing the upgrade after download per the MS setting /5/0/14 Automatic Upgrade = True

fota pull.png
PULL image with Automatic Update

 

Software Update

The LwM2M /9/x Software Management object SHALL be used to manage the Installation and Activation of containerized edge applications running in the GEISA EE. In contrast to the Firmware Update object, each instance of the multi-instance Software Management object represents a distinct edge application Package installed in the EE. The format of the edge application Package is defined <here> and SHALL be composed of the following components:

  • X.509 Public Key Certificate used to verify the digital signature in the Package

  • Digital Signature across the Edge Application Manifest and Edge Application Binary

  • Edge Application Manifest <link to definition>

  • Edge Application Binary

To minimize edge app container sizes, applications are encouraged to dynamically link against the libraries provided by the base GEISA environment rather than providing their own. Consideration for the management of the base libraries and/or package dependencies will be deferred to a future release; at this time, no consideration is made for the use of LwM2M object 14 Software Component.

Similar to Firmware Update, the LwM2M spec permits edge app packages can be transferred to the EE via either of the following methods:

  • PUSH via WRITE of the opaque package to /9/x/2 Package

  • PULL via WRITE to resource /9/x/3 Package URI for the EE to download via CoAP/HTTP as soon as practical

In contrast to Firmware Update, the Software Management object 9 does not support the concept of automatic Installation or Activation. Both operations of Installation and Activation are manually executed by the MS, following successful package download/verification and successful package install, respectively.

The following example demonstrates GEISA compliant edge app installation and activation:

  1. PULL download of the edge app package from the URL set by the MS into /9/x/3 Package URI

  2. The MS performing a manual Execute /9/x/4 to trigger app Installation following successful app download and verification

  3. The MS performing a manual Execute /9/x/10 to trigger edge app Activation following successful app installation

  4. The MS performing a manual Execute /9/x/6 to trigger Uninstall of the edge app

 

Software Update.png
PULL Software with Manual Install and Activate

 

Information Reporting Interface