OSNP Application Layer

##Scope

The OSNP application layer defines the way a hub and a device communicate with each other at the application level. This includes the format of the message itself and the type of command/responses exchanged between the parties. It assumed that lower layer provide, addressing, pairing, routing and, at least optionally, authenticated and confidential communication.

##Introduction

All data structures defined in this specification are encoded using ASN.1 and more specifically the X.690 standard using the BER format. More details can be found here. All numeric values are encoded Most Significant Byte first (Big Endian)

In short, the BER-encoding dictates that data units are formatted in the TLV format (Tag-Length-Value), where the tag expresses the kind of data. This is followed by its length and value. TLVs can be nested (this is indicated in the tag), and the meaning of the tag can be dependent on its location in the structure.

##Notes about the TLV format

• The hub is required to support receptions of BER-TLVs encoded with the indefinite length format but they are not allowed to send such TLVs. The reason for this is that while indefinite length TLVs might be easier to encode, they can be harder to parse. We assume that devices have limited capabilities and are allowed to take shortcuts in parsing/encoding.

• For the same reason, the hub must send the command parameters in the same order as listed in this specifications (which removes the effort of searching from the device). Devices are instead allowed to send the TLVs in any order, unless otherwise noted.

• It is important to keep tags with a 1-byte encoding, and when possible a 1-byte length encoding (for lengths <= 127) to minimize complexity on the device side. This means the hub is required to always use the shortest possible encoding for the length field, but must accept any valid length encoding from the device. This is once again to allow underpowered devices to take shortcuts in parsing and encoding.

##Packets

An unit of data in the application layer is called a packet. There are three kinds of packets:

• Command Packet: sent from the Hub to the Device containing one or more commands.
• Response Packet: sent from the Device to the Hub in relation to a previously sent command packet. It contains a response for each of the commands in the command packet, in the same order in which they were sent.
• Notification Packet: sent from the Device to the Hub spontaneously to notify it of one or more events. The Hub can subscribe to different kind of notifications from the device, but the Hub should tolerate (eventually ignore) unsolicited notifications.

Each of this packet is represented by a constructed TLV. The tag for each of them is:

Tag	Description
0xE0	Command
0xE1	Response
0xE2	Notification

##Commands & responses Commands are delivered in Command Packets. All commands are constructed TLV tag. Parameters and options are encoded in children TLVs.

All commands can optionally contain a sub-device address, which 1 byte identifying the sub-device index. A device can have a maximum of 256 sub-devices (0 to 255). When communicating to the main (or only) device this field shall not be present.

All responses must contain the sub-device index if the command they respond to contained it. All responses may contain the Error tag in case of errors. Error codes will be defined later.

The commands are:

Tag	Description
0xA0	Get Device Info
0xA1	Configure
0xA2	Get Data
0xA3	Perform
0xA4	Subscribe
0xA5	Unsubscribe

###Get Device Info Get Device Info is used during device discovery to retrieve information about the device or sub-device, such as supported commands, name, manufacturer etc. Its parameters are:

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index

When sent to the main device (i.e. not a sub-device), the body of this command is empty and is encoded as following: 0xA0, 0x00. When addressing a sub-device, the Sub-device Index parameter must be present.

The response to a Get Device Info command is formatted as following:

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index
0x9E	Conditional	1	Error
0x81	Mandatory	2	Device Type
0x82	Mandatory	1-n	Supported Commands
0x83	Optional	1	Sub-device Count
0x84	Conditional	1-n	Supported Configuration Options
0x85	Optional	1-n	Supported Get Data Options
0x86	Conditional	1-n	Supported Perform Actions
0x87	Conditional	1-n	Supported Notification Types
0xC0	Mandatory	1-n	Device Name (UTF-8)
0xC1	Optional	1-n	Manufacturer Name (UTF-8)

The Device Type is a 2 bytes short describing the type of device. The type of device also indicates the device specification it implements. Assigned device types are listed in the OSNP Assigned Device Types page. New ones will be added as soon as a good specification for them.

The Supported Commands field is a list of tags, with the list of commands the device supports. The Get Device Info (0xA0) command does not need to be listed, since all devices and sub-devices must support it. The tags are listed one after the other. For example a device supporting Get Data, Subscribe, Unsubscribe would encode this field as 0x82, 0x03, 0xA2, 0xA4, 0xA5.

The Sub-device count field is optional and shall only be present if there is 1 or more sub-devices. Sub-devices are addressed by index.

The Supported Configuration Options field is conditional, and shall only be present if the device supports the Configure command. It is formatted in the same way as the Supported Commands field and list the supported configuration options. The configuration options tag can be either constructed or primitive. The meaning of the configuration options depend on the device type.

The Supported Get Data Options field is optional, and can only be present if the device supports the Get Data command. Even in that case, it is only needed if there are options or different kind of data that can be returned by the command. Simple sensors which only return one kind of data, without options can omit this field. The considerations about the format and meaning are the same as for the Supported Configuration Options field.

The Supported Perform Actions field is conditional, and shall only be present if the device supports the Perform command. It contains a list of actions the device can perform, encoded as a list of TLV tags. The considerations about the format and meaning are the same as for the Supported Configuration Options field.

The Supported Notification Types field is conditional, and shall only be present if the device supports the Subscribe/Unsubscribe commands. It contains a list of notifications the device can emit, encoded as a list of TLV tags. The considerations about the format and meaning are the same as for the Supported Configuration Options field.

The Device Name field is an UTF-8 encoded string with the name of the device as it should be displayed. The manufacturer name should not be part of this string, and it should be kept short. Using the latin script will probably reach a wider audience, but there is no specific restriction.

The Manufacturer Name field is an UTF-8 encoded string. It is optional, but highly recommended. If the device is manufactured by an hobbyist the full name (omitting title is advised) or a nickname would be the appropriate way to fill this field. For companies it would be a good idea to use the brand name, not the full legal name. This field is not meant to contain contact information either.

###Configure

The Configure command can be used to configure the device. These configuration options can range from calibration data to selected alarm tone, etc. The command is appropriate when the data will be stored by the device in some kind of long term memory, like the EEPROM or similar. These commands should be only sent by an appliance at direct or indirect request of the user, since they affect the device as a whole and not only a specific appliance.

The meaning of the configuration options is device-type dependent, so their values are defined in the specifications of each device type, when applicable. The parameter of the Configure command are:

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index
0xA0	Mandatory	1-n	Configuration Options

The Configuration Options field contains the device-type specific configuration options. Only options declared to be supported in the Get Device Info command should be sent. Unsupported options may be ignored by the device, or cause it to respond with an error condition.

The response to a Configure command is:

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index
0x9E	Conditional	1	Error

This Error field is only present if an error occurred, this means that in the simplest case where the command has been executed and no sub-device was being addressed, the response will simply the empty Configuration tag, which is encoded 0xA1, 0x00.

... to be continued ...