Open Messaging Interface (O-MI), an Open Group Internet of Things (IoT) Standard – Messaging Objects

 

The XML schema “omi.xsd” in O-MI XSD Schema provides a formal specification for the O-MI. If there is any conflicting information between the chapters of this standard and the “omi” schema, then the information in the schema file is to be used. Documentation automatically generated from the schema file is included in O-MI and XML Schema.

The following units or formats SHALL be used in the O-MI to express the listed quantities. The xs namespace is defined in XML Schema Part 2: Datatypes Second Edition.

O-MI Units and Formats

Value

Unit/Format

Date

Use xs:Date

Time

Use xs:dateTime

Duration

Use xs:duration

However, it is defined in the schema where xs:duration should be used. For other durations, such as TTL, xs:double may be used and then the unit is seconds.

Other Values

SI units used by default.

Attributes of omiEnvelope defines generic information included in all O-MI requests and responses. They are defined in the omiEnvelope element, which is always the highest-level element of an O-MI message. The omiEnvelope CAN have only one of the following child elements: read, write, cancel, response.

Attributes of omiEnvelope

Attribute

Description

ttl

TTL SHALL be present. The TTL (in seconds) for the O-MI requests. The time is counted from the time the O-MI request was received by the O-MI node. The value “0” signifies that a response must be provided while the connection is active (in the case of HTTP, for instance). The value “–1” signifies “forever”. When the TTL expires, O-MI nodes SHOULD answer requests with an error response.

version

Each O-MI message SHALL have a version number defined. The version number defines the O-MI version used.

Requests

O-MI requests SHALL be read, write, or cancel requests. O-MI requests MAY define the recipient O-MI nodes for the request. If so, the receiving O-MI node SHOULD send the request to these nodes for execution. If no nodes are defined, the recipient of the request is the only intended recipient. The receiving O-MI node SHOULD include information about which node(s) provided which of the results in the response.

O-MI requests CAN be one-time, or for repeated data updates (subscriptions). One-time requests are only answered once – see One-Time Read – while subscription requests are answered several times using a callback service provided by the requesting O-MI node – see Subscription Request.

Read Request

Read requests are used to request data or to set up subscription requests for data.

An O-MI node SHALL answer each read request it receives with the requested data or with an error message.

The responding O-MI node SHOULD take care of data persistency of requests. It SHOULD buffer a subscription request with a callback response mechanism until the request is completely fulfilled.

The responding O-MI node SHALL NOT assume that the requesting O-MI node keeps track of placed requests.

The responding O-MI node SHALL answer the request with an O-MI response or with a communication error code in case the request failed on communication connection level.

The response message SHALL NOT contain any other data than requested data, or error information about the processing of the request.

Attributes of Read Request

Attribute

Description

callback

Defines a URL to an O-MI node with a callback service where O-MI responses are received. SHALL NOT be present for immediate requests. MAY be present for subscription requests. For subscription requests, if no callback address is provided, then the requested data should be stored for subsequent retrieval using a read message with the corresponding requestID.

msgformat

SHOULD be present. Text string indicating the format of the payload in “msg”; e.g., “odf”, “csv”, “obix”, or similar. For an XML schema, this SHOULD correspond to the value of the schema’s “id” attribute, if present.

targetType

MAY be present. Currently defined types are “node” or “device”. In applications dealing with physical devices, using “device” indicates that if the message “target object” is some kind of device connected to an O-MI node, then try to get the requested value directly from the device.

interval

The subscription interval. SHALL be present for subscription requests. SHALL NOT be present for all other than subscription requests.

O-MI nodes SHOULD answer positive value subscriptions with the value used as the interval between responses (in seconds). The responding O-MI node SHOULD answer the request as close to the interval as possible. Answering the request exactly on the interval may not be possible. The responding O-MI node SHOULD answer the request at every interval, even if data is not available. If data is not available, the responding O-MI node SHOULD answer the request with an error for those intervals.

O-MI nodes SHOULD answer value 0 subscriptions as often as data can be read from the target. Typically used for specific diagnostics and performance monitoring applications. (May cause unnecessary data traffic.)

O-MI nodes SHALL answer value –1 subscriptions every time the subscribed target publishes/pushes a new value.

O-MI nodes SHALL answer value –2 (minus 2) subscriptions every time the subscribed target (typically a PEID or device) connects to an O-MI node.

oldest

Retrieve the oldest available number of historical data available. MAY be present.

begin

Retrieve data from the begin date. MAY be present. If no end value is provided, then retrieve all available data after begin.

end

Retrieve data until this end date. MAY be present. If no begin value is provided, then retrieve all data available until end.

newest

Retrieve the newest available number of historical data available. MAY be present.

Child Elements of Read Request

Child Element

Description

nodeList

List of recipient O-MI nodes. MAY be present if the request is directed to predefined O-MI nodes other than the O-MI node that received the request.

requestID

List of request IDs of earlier subscriptions. MAY be present if this read request is sent for retrieving data resulting from an existing subscription(s) that was issued without a callback address.

msg

Actual payload of the request, specifying what data is being requested.

Write Request

Write requests may be used to write various data to different systems, from sensor values to information extracted from databases or other systems.

An O-MI node SHALL answer each write request that it receives with a confirmation that the write was successful or with an error message either immediately or to the provided callback address.

The responding O-MI node SHOULD take care of data persistency of requests.

The responding O-MI node SHOULD buffer a request with callback response mechanisms until the request could be completely fulfilled.

An O-MI node SHOULD NOT respond to a write request as successful before the write can be guaranteed. (It is not always possible to guarantee the write was successful, and in such a case the O-MI node SHOULD respond successfully when the request is communicated for writing successfully.) The responding O-MI node SHALL NOT assume that the requesting system keeps track of placed requests.

The responding O-MI node SHALL answer the request with an O-MI-compatible message or with an HTTP error code in case the request failed on communication connection level.

If there are any subscriptions to information affected by the write request, then the responding O-MI node SHALL generate corresponding event(s) in order to reflect the value change.

Attributes of Write Request

Attribute

Description

ttl

TTL SHALL be present.

The responding O-MI node SHOULD write the request to the targets or answer it with an error response before the TTL expires, or SHALL answer it with an error response.

The response MAY contain both error messages and confirmation messages if the write was successful for some targets and failed for others.

callback

SHALL be present for callback requests. SHALL NOT be present for immediate requests. SHALL define a URL to a callback service where O-MI responses are received.

msgformat

Same as for read request.

targetType

MAY be present. Currently defined types are “node” or “device”. In applications dealing with physical devices, using “device” indicates that if the message “target object” is some kind of device connected to a node, then try to write the requested value directly to the “device” as soon as possible.

Child Elements of Write Request

Child Element

Description

nodeList

Same as for read request.

requestID

List of request IDs of earlier request(s). MAY be present. However, the current specification does not define how that list of request IDs is to be used in write requests. Therefore, any use of this feature will be application-specific with this current specification. Future specifications may include recommendations for this feature.

msg

Actual payload of the request, specifying what data is being written and corresponding values.

Cancel Request

An O-MI node SHALL answer each cancel request that it receives with a confirmation that the cancellation of a request was successful or with an error message.

An O-MI node receiving a cancel request for an original request with a recipient list SHALL direct the cancel request to the recipients.

A cancel request SHALL define the ID of the request(s) to cancel.

An O-MI node receiving a cancel request SHALL answer it with an O-MI-compatible message or with an HTTP error code in case the request failed on communication connection level.

Attributes of Result Element

Child Element

Description

requestID

SHALL be present. List of request IDs of the request(s) to cancel.

nodeList

Same as for read request. MAY be present if the request(s) is cancelled at predefined O-MI nodes.

Response Element

Response content varies with the request type and usage of the response. This section defines the generic response structures.

A response SHALL contain at least one result. Every result object SHALL contain a return object that indicates whether the request was successful or not using HTTP status codes; i.e., “200” if successful. If there are several result objects in a response, then they typically correspond to different callback requests.

Smallest Possible Response to a Successful Request

<?xml version="1.0" encoding="UTF-8"?> <omiEnvelope version="1.0" ttl="0">     <response>         <result>             <return returnCode="200"></return>         </result>     </response> </omiEnvelope>

An O-MI node that receives a callback request SHALL send a response immediately as a return value to the request and the response SHALL contain a request ID. If the request is received correctly, this response message SHOULD NOT contain anything else.

An O-MI node that receives a callback or immediate request that is unsuccessful or that could not be received properly SHALL send to the requester an immediate response that contains error information.

All result data in a response object SHALL be in the msg element. The msgformat attribute SHOULD contain a text string that identifies the payload format used, such as “odf”, “csv”, “obix”, or similar. A responding O-MI node SHALL NOT include data that was not requested in a response.

If a request encountered problems during its execution or some data was not available, the responding O-MI node SHALL send a corresponding result that contains information about the problem.

Response objects MAY contain both successful and unsuccessful result objects.

Child Elements of Result Element

Attribute (result)

Description

msgformat

Same as for read request.

targetType

MAY be present. Currently defined types are “node” or “device”. In applications dealing with physical devices, the value of this attribute indicates whether requested value(s) come from the device directly or whether it is the last data known by the node. If omitted, the default value is “node”.

format (requestID)

MAY contain text string that specifies the format of the request ID used.

Attributes of Response Element

Child Element

Description

return

SHALL be present. Return code of the request. MAY contain a “description” attribute, which is then a text string describing the error.

requestID

SHALL be present if this message is the result of a callback request, else SHALL NOT be present.

msg

MAY be present. Actual payload of the result.

nodeList

MAY be present. List of O-MI nodes that have provided the result.

omiEnvelope

MAY be present. O-MI envelope containing a new request from the responding O-MI node to the originator O-MI node. The purpose of this child element is to enable a synchronous, direct dialog between two O-MI nodes using an already open connection. It is also useful for communicating with O-MI nodes that are behind firewalls and that therefore have to initiate the communication.