Open Messaging Interface (O-MI), an Open Group Internet of Things (IoT) Standard – Typical Uses of O-MI Requests
The typical uses of the O-MI given in this chapter should cover most of the actual needs and scenarios. However, the O-MI has been specified with the intention to be as generic and flexible as possible for most potential information architectures that might occur or be needed for an IoT as well as for lifecycle management. Therefore, these typical uses should not be considered as the only possible ones even though they do represent most of the actual implementations of the O-MI so far.
One-Time Read
An O-MI node SHALL answer a one-time read request once only. The answer can be provided using immediate responses or a callback service. If a callback is used, the requesting O-MI node SHALL only call the callback point once.
An O-MI node SHALL answer a one-time read request with a response that contains the requested data if the data was available and the requester had appropriate access rights to that data, and with a response that contains an error message if the data was not available.
An O-MI node MAY answer a one-time read request with a response that contains both error messages and data if parts of the request were successful.
Immediate response requests can typically be used for GUIs and components where there is an active user, to be able to respond to the user in an interactive way. Immediate response requests are answered immediately to the requesting system without using a callback.
Immediate response requests need not be buffered and the requesting O-MI node SHOULD be waiting idle until the request is either fulfilled or results in an error. If the defined TTL expires before the request can be processed or before it causes an error response, the responding O-MI node SHALL answer the request with an error response.
Attribute and Child Element Descriptions for One-Time Read
Attribute/ |
Description |
interval |
SHALL NOT be present. |
ttl |
When the defined TTL expires, the responding O-MI node SHALL answer the request with an error response and the data retrieved so far. |
callback |
SHALL NOT be present in the immediate response request. |
Subscription Request
The O-MI allows one-off or standing information request subscriptions to be made in a loosely-coupled, lightweight, and generic way. Subscriptions can be made for receiving updates at regular intervals or on an event basis – when the value or status changes for the information subscribed to.
Subscription requests SHOULD use a callback point as the request may be answered several times. If no callback address is provided, then the responding O-MI node SHOULD store the data acquired for the subscription for later retrieval with a read message that contains the corresponding requestID.
An O-MI node receiving a subscription request SHALL answer it by an immediate response message containing a requestID. The response SHALL NOT return any data.
A callback service is typically used to answer requests that cannot be fulfilled immediately and requests where the requesting system waits in an idle state until the request is fulfilled.
An O-MI node receiving a subscription request with a callback O-MI node SHALL answer it when the request is fulfilled by calling the callback service, either if the request could be fulfilled successfully or if it resulted in an error. An O-MI node receiving a subscription request MAY send responses and actual values in any order according to data availability. The responses MAY contain both data and error messages.
An O-MI node receiving a subscription request (or any system connected to it and set up for the purpose) SHOULD generate the requestID. An O-MI node sending a subscription request SHOULD NOT include a request ID in it. An O-MI node receiving a subscription request SHALL send an immediate response that MAY contain error information but SHALL NOT contain actual request data. If it contains error information the response SHOULD NOT contain a request ID. The request is considered failed.
An O-MI node receiving a subscription request with a callback O-MI node MAY call the callback O-MI node several times for the same request. It SHOULD call the callback point every time data is available to answer the request, or when an error occurred. It MAY call the callback point with incomplete response messages where only part of the requested data is included.
Attributes and Child Elements Descriptions for Subscription Request
Attribute/ |
Description |
interval |
SHALL be present. |
ttl |
TTL defines for how long the subscription is valid. The receiving O-MI node SHALL NOT send actual data to the callback after the TTL expires. |
callback |
SHALL be defined for callback responded requests. SHALL define the URL to the callback O-MI node to be called by the system when the request is answered. |
requestID |
SHALL be provided by the responding O-MI node to the originating O-MI node in the immediate response if the subscription request is received correctly. If an error occurred, a request ID SHOULD NOT be provided. SHALL be present in all responses to the callback, if there is not an error. |
Write Request
Whereas subscription requests are used for setting up time-limited, loosely-coupled information flows for different pieces of information between O-MI nodes, write requests are rather used for “live forever” requests, such as a machine sending a predefined set of information at predefined intervals and to a predefined callback address of its manufacturer company.
Another example when a write request is needed is if a sporadic event occurs at an O-MI node that needs to be communicated to another O-MI node that hasn’t set up a subscription to receiving such events. It is then up to the receiving O-MI node to accept the incoming write request or not.
While read requests correspond to a “client pull” mechanism, write requests correspond to a “client push” mechanism. Subscription requests represent a kind of mixture between these two mechanisms. Which mechanism and request type is the most appropriate to use is typically application-dependent.
It is worth noting that the callback mechanism in write requests is intended to be used for asynchronous notifications about the success or failure of the write request. For instance, if a write request is issued for a mobile device, then the actual write operation may occur a long time after issuing the write request.
Write requests can also be used for publishing data sources, as explained in Data Source and Metadata Discovery.
Data Source and Metadata Discovery
The RESTful, URL-based (HTTP GET) mechanism described in RESTful Interface is intended to be the main mechanism of discovering available data sources and metadata about them. An alternative is to issue a read request (typically using HTTP POST). However, a major difference between these two approaches is that an O-MI node responding to the URL-based mechanism SHOULD return only the requested hierarchical level of information. This is shown in A Result for URL-Based Data Discovery Request using O-DF Semantics. This example uses O-DF semantics for defining and requesting the available “information items” of a refrigerator; e.g., at “<QLMnodeURL>/qlm/SmartFridge22334412/”.
A Result for URL-Based Data Discovery Request using O-DF Semantics
<Object>
<id>SmartFridge22334412</id>
<InfoItem name=”PowerConsumption”/>
<InfoItem name=”RefrigeratorDoorOpenWarning”/>
<InfoItem name=”RefrigeratorProbeFault/>
</Object>
The way in which different O-MI nodes publish their available data sources and metadata depends on the actual implementation. For instance, in the case of a Smart Home, the O-MI node would typically publish the list of available devices or other information sources about the house, as well as what information is available about those devices and information sources. Finally, metadata information such as units, accuracy, etc. can also be published in the same way.
Another example of information that can be published would be available folders and files for a file repository, together with metadata about the files. However, the semantics and structure of that information are out of the scope of the O-MI. Such semantics would be defined by other standards or conventions, such as the O-DF, oBIX, or similar. However, in order to simplify the maintenance of an extensible set of application-specific semantic object models, it is recommended that they use URIs for object IDs and for InfoItem names.
O-MI nodes SHOULD NOT use read requests (with HTTP POST or HTTP GET with the “msg” parameter) for this kind of query because read requests should reply with the entire XML structure that corresponds to the read request. Therefore, issuing a read request to the uppermost level of an O-MI node would conceptually result in a response that contains the entire information hierarchy for all data sources, metadata, and current data values. In practice, O-MI nodes would restrict the amount of information returned based on security settings and other configuration options.
Publishing Data and Data Sources
As mentioned in the previous section, different O-MI nodes may use different mechanisms for publishing their data sources. In addition to those, O-MI nodes MAY allow the usage of write requests for publishing data sources and data.
Publishing “Object”, “InfoItem”, and “Value” using O-DF Semantics shows an example of an ordinary message using O-DF semantics for publishing the value of information item “FridgeTemperatureSetpoint” of the refrigerator “SmartFridge22334411”. The crucial question here is how the receiving O-MI node behaves if either “SmartFridge22334411” or “FridgeTemperatureSetpoint” (or both) are not previously known to the node. Different possibilities are, for instance:
- Reject the write request, return an error response.
- Accept the write request, accept and “publish” the new data source(s) “SmartFridge22334411” and/or “FridgeTemperatureSetpoint”. If “SmartFridge22334411” existed already, then just add the new information item “FridgeTemperatureSetpoint” with the given value.
- Accept or reject the write request depending on whether it comes from “localhost”, a trusted server, or an unknown location. This decision may also depend on whether it is a new Object that is being created or just a new InfoItem for an existing Object.
As shown by these three possibilities, the O-MI provides the possibility to publish new data sources and data using write requests. However, how this is implemented by the receiving O-MI node and what security policies apply are not in the scope of the O-MI.
Publishing “Object”, “InfoItem”, and “Value” using O-DF Semantics
<?xml version="1.0" encoding="UTF-8"?>
<omi:omiEnvelope ttl="0" version="1.0">
<omi:write msgformat="odf">
<omi:msg>
<Objects>
<Object>
<id>SmartFridge22334411</id>
<InfoItem name=”FridgeTemperatureSetpoint”>
<value>3.5</value>
</InfoItem>
</Object>
</Objects>
</omi:msg>
</omi:write>
</omi:omiEnvelope>
The removal of data sources using write requests is done by re-writing the containing XML data structure without the data source(s) to remove. For instance, re-writing the “SmartFridge22334411” structure without the “FridgeTemperatureSetpoint” InfoItem would remove that information item.
In the future, it might turn out that there is a need to define some kind of delete operation into the O-MI. However, we believe that it is essential to gain practical experience from O-MI implementations first in order to see to what extent such an operation would be used and how different implementations will handle the security issues related to this kind of data source publishing.
Synchronous Dialog
A result element of an O-MI response MAY include a child element called omiEnvelope that is, indeed, of type omiEnvelope. A receiving O-MI node SHALL use this element if it wants to issue its own request at the same time as it sends its response to the original request. This functionality is provided and needed at least in the following cases:
- The sender O-MI node of the original request is behind a firewall, it is mobile, or, for some other reason, is never or only occasionally accessible for sending requests to it. This signifies that the original sender O-MI node always has to initiate all communication so the only way of sending requests to it is to do it together with a response.
- For some reason the dialog between the two O-MI nodes needs to be as fast as possible. This could be the case, for instance, when a user is directly interacting with a machine over the Internet. Using this synchronous dialog signifies that the speed of interaction will not be limited by callback overhead or similar.
- Others: it is expected that future applications will develop new ways of using this functionality.
Specifying a List of Destination O-MI Nodes
The optional child element nodeList can be used in requests for explicitly specifying URIs of O-MI nodes that the receiving O-MI node SHALL send the request to. This possibility is useful, for instance, in the following cases:
- An O-MI “proxy” node is used as a unified message router inside a company network (or a Smart House or similar) that takes care of forwarding and receiving all messages through a firewall. In this case, all messages are sent to the “proxy” node that then takes care of forwarding the messages to the recipient nodes. In this case, the “proxy” node also needs to take care of routing responses back to the original sender O-MI node.
- An event needs to be sent by a write request to many different destination nodes but the sending O-MI node does not have message persistence (buffering), callback, or similar needed capacities for ensuring that the request reaches its destination.
- For some reason, we need information about the same product (or some other item) from a predefined and known list of O-MI nodes and the requesting O-MI node cannot manage all the needed read requests itself.
Correspondingly, an O-MI node that receives a request with explicitly defined destination nodes SHALL respond with result elements that include nodeLists that indicate from which O-MI node(s) the results come.
As seen from the example cases given above, the possibility to explicitly specify a list of destination nodes is mainly related to the use of a “proxy” O-MI node that provides some functionality that the originating O-MI node does not implement. However, it is also imaginable that the nodeList element may be used for other purposes, depending on application requirements.
Information |
Description |
nodeList |
List of recipient O-MI nodes. The requesting O-MI node MAY include a list of recipient nodes for the request. If included, the O-MI node receiving the request SHALL send it only to those nodes. If not included, the O-MI node receiving the request is the only recipient node. |