The client that wishes to receive momentary values from the sensor initiates the request using the req element sent to the device.

When the device has received and accepted the request, it responds as follows:

When read-out is complete, the response is sent as follows:

If instead a read-out could not be performed, the communication sequence might look as follows:

If for some reason, the device rejects the read-out request, the communication sequence might look as follows:

Depending on the reason for rejecting the request, different XMPP errors can be returned, according to the description in the following table. The table also lists recommended error type for each error. Any custom error message is returned in a text element, as in the example above.

The following example shows a communication sequence when a client reads out all available information from a sensor at a given point in time:

The following example shows how a client reads a subset of multiple sensors behind a device with a single JID.

The req element can take field sub elements, with which the client can specify which fields it is interested in. If not provided, the client is assumed to return all matching fields, regardless of field name. However, the field elements in the request object can be used as a hint which fields should be returned.

Note: the device is not required to adhere to the field limits expressed by these field elements. They are considered a hint the device can use to limit bandwidth.

The following example shows how a client can read specific fields in a device.

The following example shows how the client cancels a scheduled read-out:

As noticed, a conscious effort has been made not to shorten element and attribute names. This is to make sure, XML is maintained readable. Packet size is not deemed to be affected negatively by this for two reasons:

• For sensors with limited memory, or where package size is important, &xep0322; is supposed to be used. EXI compresses strings as normalized index values, making the string appear only once in the packet. Therefore, shortening string length doesn't affect packet size much. Element and attribute names in known namespaces are furthermore only encoded by index in schema, not by name.
• If limited memory or package size is not a consideration, readability and ease of implementation is preferred to short messages.

This protocol has avoided the use of enumerations for data types such as units, field names, etc., and instead use strings. The reasons for this are:

• Enumerations would unnecessarily restrict the use of the protocol to field names and units listed in the protocol.
• It would be very difficult to try to create a complete set of field names and units that would suit all applications.
• Leaving these values as strings would let developers the liberty to use units as they desire.
• If EXI is used for compression, the use of strings will only increase payload slightly, with only one copy of each distinct value used.
• If EXI is not used, this does not affect packet size.

However, some things need to be taken into account:

• Since free strings are used, XML validation cannot be used to secure correct names are used.
• xep-0000-IoT-Interoperability lists recommendations on how field names and units should be used in order to achieve maximum interoperability in SN.
• Consumers of sensor data need to include unit conversion algorithms.

Since some applications require real-time feedback (or as real-time as possible), and read-out might in certain cases take a long time, the device has the option to send multiple fields messages during read-out. The client is responsible for collecting all such messages until either a done message is sent, or a corresponding done attribute is available in one of the messages received. Only the device knows how many (if any) messages are sent in response to a read-out request.

There are different types of values that can be reported from a device. The following table lists the various types:

When representing control parameters as momentary field values, it is important to note the similarities and differences between XEP-0323 (this document) and XEP-0325 (Control):

The enum field value data type is not available in XEP-0325 (Control). Instead enumeration valued parameters are represented as string control parameters, while the control form explicitly lists available options for the parameter. Options are not available in XEP-0323, since it would not be practical to list all options every time the corresponding parameter was read out. Instead, the enum element contains a data type attribute, that can be used to identify the type of the enumeration.

The numeric field value data type is not available in XEP-0325 (Control). The reason is that a controller is not assumed to understand unit conversion. Any floating-point valued control parameters are represented by double control parameters, which lack a unit attribute. They are assumed to have the same unit as the corresponding numeric field value. On the other hand, floating point valued control parameters without units, are reported using the numeric field element, but leaving the unit blank.

Control pameters of type color have no corresponding field value data type. The color value must be represented in another way, and is implementation specific. Possibilities include representing the color as a string, using a specific pattern (for instance RRGGBBAA), or report it using multiple fields, one for each component for instance.

The boolean, date, dateTime, duration, int, long, string and time field value data types correspond to control parameters having the same types and same element names.

There are different types of fields, apart from types of values a field can have. These types are conceptual types, similar to categories. They are not exclusive, and can be combined.

If requesting multiple field types in a request, the device must interpret this as a union of the corresponding field types and return at least all field values that contain at least one of the requested field types. Example: If requesting momentary values and historical values, devices must return both its momentary values and its historical values.

But, when a device reports a field having multiple field types, the client should interpret this as the intersection of the corresponding field types, i.e. the corresponding field has all corresponding field types. Example: A field marked as both a status value and as a historical value is in fact a historical status value.

The following table lists the different field types specified in this document:

There are two field type attributes that can be used in requests to simplify read-out:

Note: The reason for including different predefined time periods for historical values is that these periods are common in certain applications. However, the client is not restricted to these in any way. The client can always just ask for historical values, and do filtering as necessary to read out the interval desired.

Also, devices are not required to include logic to parse and figure out what historical values are actually desired by the client. If too complicated for the device to handle, it is free to report all historical values. However, the device should limit the historical values to any interval requested, and should try to limit itself to the field types requested. Information in the request element are seen as hints that the device can use to optimize any communication required by the operation.

In applications where quality of service is important, a field must always be accompanied with a corresponding quality of service flag. Devices should set these accordingly. If no quality of service flag is set on a field, the client can assume automaticReadout is true.

Note that quality of service flags are not exclusive. Many of them can be logically be combined. Some also imply an order of importance. This should be kept in mind when trying to overwrite existing values with read values: An estimate should not overwrite an automatic read-out, an automatic read-out not a signed value, and a signed value not an invoiced value, etc.

Available quality of service flags, in order of importance:

This document does not go into detail on how devices are ordered behind a JID. Some of the examples have assumed a single device lies behind a JID, others that multiple devices exist behind a JID. Also, no order or structure of devices has been assumed.

But it can be mentioned that it is assumed that if a client requests a read-out of a supernode, it implies the read-out of all its subnodes. Therefore, the client cannot expect read-out to be limited to the devices listed explicitly in a request, as nodes implicitly implied, as descendant nodes of the selected nodes, can also be included.

More information about how multiple devices behind a JID can be handled, is described in the XEP-0326 Internet of Things - Concentrators.

All examples in this document have been simplified examples where a few devices containing a few fields have been read. However, in many cases large subsystems with very many sensors containing many fields have to be read, as is documented in Internet of Things - Concentrators. In such cases, a node may have to be specified using two or perhaps even three ID's: a sourceId identifying the data source controlling the device, a possible cacheType narrowing down the search to a specific kind of node, and the common nodeId. For more information about this, see Internet of Things - Concentrators.

Note: For cases where the nodeId is sufficient to uniquely identify the node, it is sufficient to provide this attribute in the request. If there is ambiguity in the request, the receptor must treat the request as a request with a set of nodes, all with the corresponding nodeId as requested.

If reading field values from a device that also supports control through &xep0325;, the device can report current control parameter values as momentary or status field values, using field names corresponding to its control parameter names. However, such values would probably only correspond to a subset of all data read out. To help the reader to know what fields correspond to controllable parameters, the optional writable attribute can be used in responsens. If this attribute is available, it tells the client if the field corresponds to a control parameter with the same name on the device. If the attribute is not available, no deduction can be made if a control parameter with the same name exists or not on the device.

All timestamps and dateTime values use the XML data type xs:dateTime to specify values. These values include a date, an optional time and an optional time zone.

Note: If time zone is not available, it is supposed to be undefined. The client reading the sensor that reports fields without time zone information should assume the sensor has the same time zone as the client, if not explicitly configured otherwise on the client side.

If devices report time zone, this information should be propagated throughout the system. Otherwise, comparing timestamps from different time zones will be impossible.

This specification allows for localization of field names in meter data read-out. This is performed by assigning each localizable string a String ID which should be unique within a given Language Module. A Language Module can be any string, including URI's or namespace names. The XEP xep-0000-IoT-Interoperability details how such localizations can be made in an interoperable way.

Note: Localization of strings are for human consumption only. Machines should use the unlocalized strings in program logic.

The following example shows how a device can report localized field information that can be presented to end users without systems being preprogrammed to recognize the device. Language modules can be aggregated by operators after installation, or installed as a pluggable module after the main installation, if localization is desired.

The above example defines a language module called Watchamacallit. In this language module it defines four strings, with IDs 1-4. A system might store these as follows, where the system replaces all %N% with a conceptual n:th parameter. (It's up to the system to define these strings, any syntax and how to handle input and output.). In this example, we will assume %0% means any previous output, and %1% any seed value provided. (See below).

So, when the client reads the field name Temperature, Min, it knows that the field name is the composition of the string Temperature, and the string %0%, Min, where it will replace %0% with the output of the previous step, in this case Temperature. These strings can later be localized to different languages by operators of the system, and values presented when reading the device, can be done in a language different from the one used by the sensor.

Note: The XEP xep-0000-IoT-Interoperability details how such localizations can be made in an interoperable way.

The stringIds attribute merits some further explanation. The value of this attribute must match the following regular expression:

This basically means, it's of the format: ID_1[|[Module_1][|Seed_1]][...[,ID_n[|[Module_n][|Seed_n]]]]

Where brackets [] mean the contents inside is optional, ID_i is an integer representing the string ID in a language module. Module_i is optional and allows for specifying a module for ID_i, if different from the module defined in the module attribute. Seed_i allows for seeding the generation of the localized string with a value. This might come in handy when generating strings like Input 5, where you don't want to create localized strings for every input there is.

Why such a complicated syntax? The reason is the following: Most localized strings are simple numbers, without the need of specifying modules and seeds. This makes it very efficient to store it as an attribute instead of having to create subelements for every localized field. It's an exception to the rule, to need multiple steps or seeds in the generation of localized strings. Therefore, attributes is an efficient means to specify localization. However, in the general case, a single string ID is not sufficient and multiple steps are required, some seeded.