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 provides 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

A 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 device can support the Subscribe and Unsubscribe command to allow turning on and off specific notifications, but it is not required to do it.

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	Conditional	1-n	Supported Commands
0x83	Conditional	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 is written.

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. This field is optional, although it will most likely be supported. One use case for omitting this tag is a device which only emits notifications, without the ability of turning these notifications on/off.

The Sub-device count field is conditional 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 action types the device can perform. Action types are coded on one byte and their meaning depend on the device type.

The Supported Notification Types field is conditional, and shall only be present if the device emits notification on some events. This can happen regardless of support of the Subscribe/Unsubscribe command (in which case the notifications are always sent). This field 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, with the addition that the tags must indicate the constructed format, because of how they are used in the protocol.

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 a 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 is to 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

The 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.

###Get Data

The Get Data command is used to retrieve data from a device. This data can be the output of a sensor, or some internal state. The exact data returned depends on the device type.

The command has the following parameters:

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

The Options field is optional and the meaning of its content depends on the device type. The most basic Get Data command is the empty A2 tag, encoded as 0xA2, 0x00.

The response for a Get Data command has the following format:

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

The Data field contains the actual retrieved data. The format of the response depends on the device type.

###Perform

The Perform command is used to instruct a device to perform an action. This might be for example switching on/off an attached device, opening a door, ringing, etc.

The parameters of the command are:

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index
0x81	Mandatory	1	Action Tag
0xA0	Optional	1-n	Parameters

The Action Tag field is the identifier of the action, coded on 1 byte. The meaning of the action type depends on the device type.

The Parameters field contains a list of parameters needed to perform the given action. An example of parameter could be the temperature for a "Set Temperature" command of an HVAC system. This field is optional and its meaning depend on the device type.

The response to the Perform command has the following format:

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

In the simplest case of no sub-device and no error, the response will be encoded as 0xA3, 0x00.

###Subscribe

The Subscribe command is used to subscribe to specific device notifications. After subscribing, the device shall attempt to send notification packets every time the event to which the hub subscribed happens. This command is used to turn on the emission of specific kind of notifications.

The parameters of this command are:

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index
0x81	Mandatory	1	Notification Tags List

The Notification Tags List field contains the list of notifications to subscribe to, encoded as a list of BER-TLV tags. The notification types are specific for each device type. The device reports which kind of notifications it supports as response of the Get Device Info command.

The format of the response to the Subscribe command is:

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

###Unsubscribe

The Unsubscribe command is the opposite of the Subscribe command. It asks the device to turn off specific notification types.

The parameters of the command are:

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index
0x81	Mandatory	1	Notification Tags List

The format of the response is:

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

##Notifications

Notifications are emitted from a Device and received by the Hub. Optionally, the device can give the option of turning off or on specific notification types. The notification types depend on the device type. Notifications do not require a response from the hub, but of course they can cause it to generate commands or take other kind of actions. One or more notifications can be sent in a Notification Packet.

A notification is a TLV, the tag of which is its identifier.

Tag	Presence	Length	Description
0x80	Conditional	1	Sub-device Index
....	Optional	......	Notification specific TLVs

The notification specific TLVs contain the actual notification data, if any. A notification may also not need to carry any data (in case its identifier carries enough information about the event which is being notified).

Let's say for example, that there is a sensor saying if a door is closed or opened. This device emits two kind of notifications: Door Opened, which we will code as 0xA0 and Door Closed, which we will code as 0xA1.

Let's now assume the door being monitored has just been opened. The device will send the following packet: 0xE2, 0xA0, 0x00.

More complex notification may carry data inside the notification-specific TLV.

##Error codes

Some error codes are device independent and they will be defined here:

... tbd ...