11.8. Application Messaging and Configuration¶
GEISA LwM2M Object /3600 provides messaging between the EMS and Edge
Applications through separate Server to Client and Client to Server resources.
Each Object Instance represents one application messaging scope identified by
resource 4050 AppID and, where applicable, a managed application instance.
Object /3600 carries application-message payloads, configuration, and
transport metadata.
Server to Client messages are written to resource 0 Server Message. They
typically carry app-facing configuration, commands, or other application
payloads from an authorized Vendor Application Server, EMS, or operator
workflow to the Edge Application. An ADM-conformant Platform receiving a
Server Message SHALL route the message payload and associated message metadata
to the application or application instance identified by resource 4050 AppID
through the corresponding GEISA Server to Client application-message API,
subject to authorization, routing policy, application lifecycle state, and
platform policy.
Client to Server messages are exposed through resource 1 Client Message
and are typically consumed by the EMS or other authorized endpoints. They
typically carry command results, status, events, alarms, application data,
telemetry, or effective configuration state sent by the Edge Application.
An ADM-conformant EMS MUST obtain these messages and their associated metadata
using the applicable LwM2M mechanisms.
11.8.1. Application-Message ReST Interface¶
An ADM-conformant EMS MUST provide a ReST API that authorized Vendor Application
Servers and Utility Operations clients can use, where permitted by System Operator
policy, to submit a message for delivery to an Edge Application. These authorized
clients may also use the API for latest-message and historical GET operations under
that policy.
All EMS ReST APIs, including the required application-message POST endpoint and
any additional operations, MUST use HTTPS.
The request MUST identify the target using its provisioned
operator-identifier
and AppID. The EMS obtains or maps operator-identifier from its
managed-device and provisioning context; the Edge Application does not need to
include this identifier in the application message.
An ADM-conformant EMS MUST accept POST requests at:
POST /geisa/adm/v1/devices/{operator-identifier}/apps/{appid}/messages
Requests MUST use HTTP Content-Type: application/json. The request body
MUST conform to schemas/geisa-app-message-req-schema.json and carry the
GEISA application-message envelope, including payload-base64 for the opaque
application payload. The envelope’s content-type describes the application
payload; the HTTP Content-Type describes the JSON request.
The EMS MUST preserve request-id for correlation and synchronously indicate
whether it accepted or rejected the message for delivery. Acceptance does not
mean the Edge Application received, processed, accepted, or acted on the
message. Any response generated by the Edge Application is returned through
application messaging or direct connection, according to the application’s
approved configuration.
Note
How the EMS reports a delivery failure to the originating Vendor Application Server after accepting a message remains undefined in this version of the specification.
The EMS MUST return the following HTTP response codes as applicable:
Status |
Name |
Meaning |
|---|---|---|
|
Accepted |
The EMS accepted responsibility for delivery |
|
Bad Request |
The request is malformed or its JSON body does not conform to the message schema |
|
Unauthorized |
Authentication is missing or invalid |
|
Forbidden |
The authenticated caller lacks permission |
|
Not Found |
The target Edge Device or application was not found |
|
Method Not Allowed |
The HTTP method is unsupported for the requested endpoint; the EMS MUST
include an |
|
Content Too Large |
The request exceeds the applicable size limit |
|
Unsupported Media Type |
The HTTP request media type is unsupported |
|
Too Many Requests |
An applicable request rate or request quota limit was exceeded |
|
Internal Server Error |
An unexpected EMS failure prevents request processing |
|
Service Unavailable |
The EMS is temporarily unable to accept the message |
For resources whose existence is sensitive, the EMS MUST NOT distinguish
unauthorized access from nonexistence and MAY return 404 for either.
EMS implementations MAY provide additional ReST operations.
Application-message GET operations
An ADM-conformant EMS MUST support latest-message and historical GET operations. The following examples illustrate possible request forms:
GET /geisa/adm/v1/devices/{operator-identifier}/apps/{appid}/messages/latest?message-type=ALARM
GET /geisa/adm/v1/devices/{operator-identifier}/apps/{appid}/messages?message-type=ALARM&from=...&to=...
The path identifies the Edge Device and application. The latest endpoint
MUST return the latest available message matching the target and Message Type.
The historical endpoint MUST return available messages matching the target and
Message Type within the requested time range. GET requests MAY include
request-id as an additional selection criterion. The EMS MUST support
filtering by request-id when provided.
Message Priority values are:
Value |
Priority |
Description |
|---|---|---|
|
Unspecified |
|
|
Urgent |
highest priority; send immediately when possible |
|
Immediate |
high priority; send as soon as possible |
|
BestEffort |
normal priority; send when resources are available |
|
Latest |
lowest priority; retain/send only the latest applicable message. When a “Latest” message is received, older messages of the same type for the same AppID may be superseded/dropped. |
|
Reserved |
Reserved for future GEISA use |
|
Reserved |
Reserved for proprietary use |
|
Reserved |
Message Type values are:
Value |
Type |
Description |
|---|---|---|
|
|
message type is not specified or not yet classified |
|
|
app-facing desired or effective configuration state |
|
|
action request to perform work now or soon |
|
|
result of a |
|
|
current state, lifecycle, readiness, mode, or policy/quota state |
|
|
operationally meaningful occurrence worth recording or routing |
|
|
actionable, high-severity, security, safety, or policy condition requiring prompt attention or special handling |
|
|
supplemental application-specific data that intentionally does not fit
|
|
|
measurement-oriented numeric or structured observations, usually time-series, snapshot, interval, or resource metrics |
|
Reserved |
Reserved for future GEISA use |
|
Reserved |
Reserved for proprietary use |
|
Reserved |
Each app message is associated with Message Priority, Message Type, Message
TTL, Content Type, Request ID, and Message Timestamp metadata. These resources
describe the current application message; they do not provide durable message
history. The Platform and EMS use this metadata to classify, schedule, route,
retain, expire, correlate, and interpret app-message payloads exchanged through
resource 0 or resource 1.
For the GEISA application-message envelope, request_id, priority,
message_type, timestamp_us, ttl_seconds, and content_type map to
resources 6, 2, 3, 7, 4, and 5, respectively. The
payload bytes appear once in resource 0 for Server to Client or resource
1 for Client to Server; the complete envelope is not encoded inside the
opaque message Resource.
Object /3600 carries Edge Application configuration between the Edge
Application and authorized Vendor Application Servers or operator systems. A
Server to Client message with Message Type CONFIG may carry desired
application configuration, or request current configuration. A Client to
Server message with Message Type CONFIG or
STATUS may carry application-reported effective configuration,
configuration status, or configuration-related state.
Object /3600 does not define the internal schema of an application
configuration payload. The payload format is identified by Content Type and is
interpreted according to the application, operator, or deployment contract.
Acceptance of a Server Message by the ADM path does not by itself prove that
the application accepted or applied the configuration. Application-level
acceptance, rejection, effective state, or error detail should be reported
through an appropriate app message, status, event, alarm, or durable record.
Manifest and deployment policy define what an application is allowed to do;
Object /3600 carries app-facing configuration payloads within those
permissions and platform policies.
Resource ID |
Name |
Operation |
Data Type |
Description |
|---|---|---|---|---|
|
AppID |
ReadWrite |
Unsigned Integer |
System-unique identifier for the logical application within the applicable management domain. |
|
Software Instance |
Read |
Objlnk |
Link to the corresponding LwM2M Software Management |
|
Server Message |
Write |
Opaque |
Server to Client app-message payload. |
|
Client Message |
Read |
Opaque |
Client to Server app-message payload. |
|
Message Priority |
ReadWrite |
Unsigned Integer |
Per-message priority for ordering, scheduling, throttling, or delivery. |
|
Message Type |
ReadWrite |
Unsigned Integer |
Per-message payload classification. |
|
Message TTL |
ReadWrite |
Unsigned Integer |
Per-message time-to-live, in seconds. |
|
Content Type |
ReadWrite |
String |
Media type for the app-message payload encoding. |
|
Request ID |
ReadWrite |
String |
Sender-assigned identifier preserved across application-message transport. |
|
Message Timestamp |
ReadWrite |
Unsigned Integer |
UTC epoch timestamp, in microseconds, when the sender created the message. |
Figure 11.11 Edge App Message Reporting¶
Figure 11.12 Edge App Message Delivery¶