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.

A short summary of the standard is that all data types 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.

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

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:

... to be continued ...