From AirQ Networks wiki
Jump to: navigation, search

Understanding and using sNET Protocol v4.1


sNET is the protocol developed and implemented to exchange information and commands between AirQ Networks devices (sensors, control boards, range extenders and control units).

This document is addressed to developers and integrators interested in developing customs applications above AirQ Networks devices. Please take note that this document, as stated next, does not describe the link protocol between AirQ Networks devices: sNET Wireless Link Protocol is a proprietary protocol subject to copyright. This document describes:

  • how to collect data coming from sensor networks using an AirQ Networks transceiver (AirQ 190, AirQ ShielD);
  • how to interact with control boards (AirQ 300 and AirQ 310).

This document is useful to build up custom applications and to integrate AirQ Networks devices in existing ones.

This document describes sNET protocol release 4.1. For previous release of sNET protocol, please contact AirQ Networks.

Contents


Basics

sNET (acronym for sensor NETworks) is a wireless network stack designed for low consumption and battery powered wireless sensors. sNET protocol was designed and developed by AirQ Networks to build up networks of wireless sensors operating in sub-gigahertz frequencies (434Mhz and 868-915Mhz). sNET stack was designed taking into account the following requirements:

  • Devices that implements sNET protocol must have really low power consumption.
  • sNET devices can sleep for an unlimited time (if required) to save battery power and to extend its operative life.
  • sNET devices can be battery powered devices and can operate at temperatures below -20°C.
  • A virtually unlimited number of sNET devices can coexist on the same sensor network.
  • sNET is optimized for sub-gigahertz frequencies with low bandwidth.

To address these requirements, sNET was designed to be a connection-less network protocol, developed to do the best effort to deliver messages between devices on the same network. This is a really important aspect to stress: from the network point of view, sNET does not to ensure that a message coming from a device is received from another device (eg. message from sensor to a receiver). However, application level can develop strategies to detect whether a message was received from a particular device. For more information, please refer to the next paragraphs.

The stack

sNET Protocol stack as release 4.1

sNET stack 4 can be logically divided in two main layers: sNET Wireless Link Protocol and sNET Messages.

sNET Wireless Link Protocol is the stack layer that establishes the wireless linking between sNET devices. This stack layer defines how devices are connected on the same network and how they exchange messages. sNET Wireless Link Protocol is the physical protocol implemented on the on-board firmware equipped with all AirQ Networks devices. sNET Wireless Link Protocol is a proprietary protocol subject to copyright of AirQ Networks and it's not described in details here. However, an outline is provided to allow user understanding of how devices interact each other and how to build custom applications.

sNET Protocol stack as release 4.1

sNET Messages layer is described in this document. An AirQ Network transceiver (eg. AirQ 190 or AirQ ShielD) allows user to interact with this stack layer through "messages". Some devices are able to send messages only in one way: please refer to the next paragraph. sNET Messages layer allows developers to build up custom applications and libraries to integrate AirQ Networks devices in their application.

Types of sNET nodes

sNET Link Protocol defines three type of network nodes: end device, router and receiver. It is important to clarify that a specific device can implement multiple node types at the time. For example, AirQ 310 boards act both as end device and router device. The following paragraphs explain functionalities of each node type.

sNET End Device

All AirQ Networks sensors and control boards are sNET End Devices. In a sNET network, end devices communicate to a sNET receiver and implement a specific functionality (eg. temperature sensors). sNET End devices can be powered through a battery (eg. AirQ 101 temperature sensor) or through a wall mount power adapter (eg. AirQ 300 control board). sNET End Devices can be one-way and two-ways devices. One-way devices only send data to a receiver and don't accept any message coming from it during their normal operation (unless they are in configuration mode). AirQ 101 temperature sensor is a one-way device. Two-ways devices are able both to send data to a receiver and to accept command from it. For example, AirQ 300 control board sends information about its status on regular basis and receives commands that change status of its relays.

sNET Router Device

sNET Router Devices implement functionalities that allow to route message coming from an sNET device to other devices. sNET Router Devices act as a signal repeater and extend operative range of sensor networks. Router Devices are transparent devices: the user is not responsible of their setup. AirQ RNG is a typical example of Router Device. Some End Devices implement router functionalities: for example, AirQ 310 and AirQ 300 control boards implement range extender functionalities. Router Devices are implemented to avoid network flooding: routers take special policies when traffic on the network is really high. Moreover, Router Devices are designed to avoid rerouting of messages.

sNET Receiver

sNET Receiver is the main coordinator of a sNET wireless sensor network. It's role is to collect data coming from End Devices as well as to send data to devices capable to receive commands (like control boards). sNET Receivers implements transceiver functionalities. This means that receivers make available to application layer both messages coming from sensors network as well as allow to send command to End Devices. There is usually only one receiver in a sensors network. Under particular circumstances, multiple receivers can coexist in the same network. For further information please contact AirQ Networks. Most of the information reported in this document is described from a receiver "point of view".

Types of sNET networks

sNET Protocol stack as release 4.1

sNET is a fully self-configuring and flexible wireless network protocol. It allows to build simple as well as really complex sensors networks mixing up range extenders (router devices), control boards and sensors. The user is totally free to decide network topology: starred, one to one, one to many, many to many. The user can decide to create "sub networks" of autonomous devices interconnected by routers.

It's important to underline that the user doesn't need to do configuration of physical network. Unlike other network protocols requiring explicit configuration of network, sNET is a self-configuring protocol: each node is able to explore the network to find path to sNET Receiver automatically. The user has the only responsibility to ensure that a physical link exists between devices.

One End Device and one Receiver compose the most simple network topology. For example, an AirQ 101 wireless sensor is connected to an AirQ 200 control unit that implements receiver functionalities. A one to many network topology can be achieved using many End Devices and one Receiver. More complex network topologies can be done mixing End Devices and Router Devices.

A sNET wireless network has usually only one Receiver Device although it's possible to mix-up multiple receivers on the same network. However, this implies that application layer must handle the case of same messages coming from multiple sources and this could dramatically make complex the application implementation. If you think that your application requires multiple receivers on the same network, please contact AirQ Networks and explain your scenario.

Device addressing

Each sNET device (end device, router or receiver) has one unique network address, which identifies it on the wireless network. sNET addresses consist of 32 bit represented in dot-decimal notation, which consists of four decimal numbers, each ranging from 0 to 255 (except for first byte), separated by dots, e.g., 101.2.1.0. Each part represents a group of 8 bits (octet) of the address. Although sNET addresses are represented in the same way of IPv4 addresses, sNET address are NOT IP addresses and there is no way to address a sNET device by the Internet. sNET is an autonomous protocol and it's not related to the Internet Protocol.

sNET Addressing

The first octet of a sNET address is the most important: it allows to detect the device type. Detecting device type is important to know its capabilities. For example, AirQ 101 temperature sensor has different functionalities compared to AirQ 300 control boards. To interact correctly with the device it's important to know exactly its type. The first address octet is hardcoded inside device firmware and uniquely identifies device type. For example, all AirQ 101 devices have an address of the form 101.x.x.x, meaning that 101 octet identifies all AirQ 101 sensors.

Please, keep in mind that the device address must be unique for the same sensor network.

The next table shows currently available AirQ Network devices and the class number (first octet) associated with them.

sNET Address classes as february 2013
AirQ 101 101.x.x.x AirQ 101 wireless temperature sensor
AirQ 101-EXT 101.2.x.x AirQ 101 wireless temperature sensor with external probe
AirQ 121/122 121.x.x.x AirQ 121 wireless temperature datalogger
AirQ 110 110.x.x.x AirQ 110 wireless humidity sensor
AirQ 111 111.x.x.x AirQ 111 wireless humidity and temperature sensor
AirQ 112 112.x.x.x AirQ 112 wireless humidity datalogger
AirQ 300 3.x.x.x AirQ 300 control board with 2 relays and 4 inputs
AirQ 305 5.x.x.x AirQ 305 control board with 4 relays and 4 inputs
AirQ 310 4.x.x.x AirQ 310 control board with 6 relays
AirQ RNG 1.x.x.x AirQ RNG range extender (signal repeater)
AirQ ShielD 192.x.x.x AirQ ShielD Arduino UNO compatibile shield
AirQ 200 191.x.x.x AirQ 200 control unit
AirQ 190 190.x.x.x AirQ 190 USB transceiver

How sNET transceivers work

A transceiver is a device comprising both a transmitter and a receiver, which are combined and share common circuitry or a single housing. A sNET transceiver is a device that plays these important roles in a sNET wireless network:

  • It is the network coordinator node responsible to build up and coordinate sensors network.
  • It acts both as receiver and transmitter in the sensor network.
  • It collects messages coming from devices and gives to application layer a way to obtain them.
  • It allows application layer to interact with devices on the network through an API.

From the developer point of view, sNET transceivers act as MODEMs: they transform data coming from sNET network in sequences of bytes in a predefined form and give a way to communicate with devices through commands (AT-like commands). sNET transceivers allow developers to abstract from underlying sNET Wireless Link Protocol.

AirQ Networks produces several types of sNET transceivers. The most common one is AirQ 200 control unit that integrates a sNET transceiver and exposes sNET functionalities through a web interface named Pingu. Another sNET transceiver is AirQ 190, which is a USB transceiver that allow developers to interact through a serial interface over USB.

All sNET transceivers are UART devices running on top of physical medium like RS-232 and USB at a baudrate of 19200 bps unless otherwise specified. AirQ Networks is also developing transceivers compatible with Modbus protocol. They will be released in Q1 2013.

sNET transceivers work in two different modes: Data and Command" mode'. The following paragraphs explain this aspect.

Data Mode

Data Mode is the predefined way to work for a sNET transceiver. In Data Mode all data coming from a sNET device is mapped in a predefined message: data messages. Each AirQ Networks device is designed to send data about its status or detected physical quantity. For example, an AirQ 310 board sends on regular basis the status of its six relays using a data message. An AirQ 101 temperature sensor sends every n minutes measured temperature.

Data messages are made by two parts: a fixed part that is common for all AirQ Networks devices and a variable part related to the specific device. However data messages aren't limited to transmission of device status. There are several types of data messages, as described in the following paragraphs. It's important to stress that data messages are asynchronous messages. Transceivers are designed to generate data messages on their UART interface when the remote device sends the corresponding message. This means that application layer has to be designed to capture messages transmitted by transceiver. Transceivers have no memory and can't be interrogated to know the state of a given remote device. Example section of this document shows strategies to detect messages from a transceiver.

Data message structure is described later.

Command Mode

In command mode a transceiver is designed to accept commands coming from the application layer. Commands tell transceiver to do particular actions. By using commands is possible to send a message to a specific device (eg. to send a message to an AirQ 300 board to turn on a relay) or to do configuration of devices. Commands are the only way for the application layer to interact with AirQ Networks devices. There are several types of commands available. Most of them are described in the following paragraphs.

Messages

Messages are the way sNET transceivers interact with other sNET devices. Indeed, sNET protocol can be seen, from the developer point of view, as a message-passing infrastructure. Messages are exchanged between devices. Some of them transport information about status of devices (data messages). Other messages are used to interact with a particular device. In a sNET network there are several types of messages exchanged by devices:

  • Network messages: these types of messages are related to the sensors network; they can be seen as "low level" messages and they aren't described in this document.
  • Data messages: these types of messages come from a device and are used in the application layer (eg. acquired temperature, etc).
  • Command messages: these types of messages come from a sNET transceiver and are addressed to a given device; they are used to configure device, set status of peripherals and so on.
sNET Addressing

The above picture shows the interaction between sNET End Device and sNET Receiver through data and command messages.

Message types

sNET defines several message types. Some of them are related to the network infrastructure, others are related to the specific device configuration. The following table reports all available message types in sNET. However, this document describes only DATA and SET messages. For further information, please contact AirQ Networks.


sNET Message Types as protocol version 4.1
Message Type Identifier Type Sender Addressee Available to application layer Description
DATA 0x1 Data End Device Receiver Yes Standard data message
SET 0x2 Command Receiver End device Yes Message sent to an end device to change its status (eg. relay status)
CFG_SET 0x3 Command Receiver End device Yes Message sent to an end device to change its configuration (eg. sleep time)
CFG_GET 0x4 Command / Data Receiver / End device End device / Receiver Yes Message sent to/from an end device to obtain its configuration (eg. sleep time)
RCV_FIND 0x5 Network End device Receiver No Message sent to a receiver to check routing to it
RCV_FOUND 0x6 Network Receiver End device No Message sent to an end device to signal correct routing to receiver
DEV_FIND 0x7 Network Receiver End device Yes Message sent to an end device to signal correct routing to device
DEV_FOUND 0x8 Network End device Receiver Yes Message sent to a receiver to signal correct routing to device
DEV_PAIR 0x9 Command Receiver End device No Message sent to an end device to pair it to receiver
BROADCAST 0xF Data Receiver / End device End device / Receiver Yes Message sent to all device on the same network


Data messages

Data messages are the way sNET devices send information to the application layer through a transceiver.

sNET Addressing


Data messages are divided in two parts: a fixed part common to all data messages and a variable part related to the specific device. The fixed part has a length of 20 bytes in sNET v4.1. The fixed part of a message is in turn divided in several fields described below.

  • PREAMBLE: all data messages starts with a preamble that has a length of 4 bytes. This part is fixed and common to all data messages and it contains bytes 0x41, 0x49, 0x52, 0x51, that is ASCII codes for string "AIRQ". If preamble doesn't contain "AIRQ" string, the whole message has to be considered corrupted and has to be discarded from the application layer.
  • Receiver ID: it contains the transceiver sNET address. It respects the sNET addressing schema as described in the previous paragraph. For example, a valid address for a sNET transceiver is 0xBF, 0x1, 0x1, 0xA (191.1.1.10 in decimal notation).
  • Message Type: this field indicates the type of message. For example, a data message has a message type of 0x1. There are several types of messages, with different structure, as described later.
  • Device ID: it contains the remote device sNET address that is sending the message. It respects the sNET addressing schema as described in the previous paragraph. For example, a valid address for a sNET device is 0x65, 0x2, 0x1, 0x0 (101.2.1.0 in decimal notation - a device address for an AirQ 101 wireless temperature sensor).
  • Message Subtype: sNET devices can define several message subtypes. This field is device dependent. For more information refer to the data message structure of the specific device (eg. AirQ 101 data message).
  • Packet number: all data messages have a progressive number that identifies them. When a device is powered up, the first data message has a progressive number of 1. Every time a device sends a data message, this number is incremented by 1. Since sNET protocol does the best effort to deliver messages between devices, the packet number is a really useful tool to detect packet loss. More information about packet number is given later.
  • RSSI: this field is one of the two field related to the quality of the network connection. Being sNET a wireless network protocol, it's really important to detect the quality of the network link between devices. RSSI is the Radio Signal Strength Indicator. Its value is expressed in dBi, and it ranges from -20 (best quality) to -120 (worst quality). It is important to highlight that some AirQ Networks devices (especially control boards) implement an adaptive radio power algorithm that allows device to adapt radio emission. This means that RSSI isn't an "absolute value", and it can change over the time if the network connection changes (for example, new routes are discovered, etc).
  • FWD: this field reports how many times the message has been forwarded before the transceiver captured it. If it's equal to 0x0 it means that the messages wasn't repeated. This field is really useful to understand how many range extenders repeated the message.
  • LQI: this field is the link quality indicator and gives an estimation of the quality of the link connection between devices. LQI is used as a relative measurement of the link quality (a high value indicates a better link than what a low value does), since the value is dependent on the type of connection between sNET nodes. From a developers perspective, RSSI gives the best and the simplest value to measure the signal quality.
  • Data: this sequence of bytes, ranging from 1 up to 10 bytes, is device dependent and contains data transmitted by the remote device. Data is also related to the message type. Each device defines its set of data messages. For further information refer to sNET documentation of each AirQ Networks device type.
  • EOL: this field is a sequence of two bytes that indicates the end of a data message. Its content is fixed and is formed by 0x24, 0xA bytes ("$\n" in ASCII). Since data messages have a variable length among different devices and type of messages, EOL sequence is the only way to detect the end of a message. The application layer must check against this sequence to detect that a data message is ended and a new message is starting.


Example

The following picture represents a data message coming from an AirQ 101 wireless temperature sensor.

sNET Addressing

The message contains the following relevant information for application layer:

  • Receiver sNET address is 191.1.1.10.
  • Message type is 0x1 (data message)
  • Remote sensor address is 101.2.1.0 (first octet, 101, clearly indicates that the message comes from an AirQ 101).
  • Message sub-type is 0x1 (AirQ 101 defines two types of subtype messages: 0x1 and 0x3. Please, refer to sNET documentation for AirQ 101)
  • Packet number is 3110 (0x1F in hexadecimal)
  • Forward field is 0x0, so the message wasn't repeated
  • RSSI is -32dBi (really good link between sensor and receiver)
  • Detected temperature is -23.09872 °C (data is expressed in a C language float datatype)
  • Sensor battery (AirQ 101 is a battery powered sensor) has a voltage of 3567 mV (data is expressed in a C language short datatype)

Command messages

As data messages are the way devices communicate to the application layer, command messages is how the application layer communicates to single devices. sNET protocol defines several types of command messages, as reported in the above table about the type of messages. However, this document describes only SET command message, which has a message code of 0x2.

The SET command isn't implemented by all AirQ Networks devices: all AirQ 1XX wireless sensors don't implement it. Instead, the SET command is fully supported by control boards (eg. AirQ 300).

Every sNET command message is sent to the remote device using an ATS AT command.

sNET Addressing

The ATS command (also known as Send Command) has to be written on the transceiver UART interface. The Send Command has a well-defined structure, as reported in the above picture. The Send Command is divided in two parts: a fixed part common to all command messages and a variable part related to the specific command and device. The fixed part has a length of 10 bytes in sNET v4. Each field of ATS command has the following meaning:

  • ATS: this is the ASCII representation of the command. It's 3 bytes length.
  • Message Type: this field contains the corresponding command message id (0x2 for SET command message).
  • Message Subtype: this field contains message sub-type.
  • Device ID: it's the sNET address of the remote device that will receive command message.
  • Data: this sequence of bytes, ranging from 1 up to 10 bytes, is device dependent. It contains data transmitted to the remote device, and it is also related to command message type. For further information refer to sNET documentation of each AirQ Networks device type.
  • EOL: this field is a sequence of two bytes that indicates the end of the command message. Its content is fixed and is formed by 0x24, 0xA bytes ("$\n" in ASCII). Since command messages have a variable length among different devices and type of messages, EOL sequence is the only way to detect when a message is ended.


Example

The following picture represents a SET command message sent to an AirQ 300 control board to turn on RELAY1.

sNET Addressing

The message contains the following information:

  • Message type is 0x2, that is SET command message.
  • Message sub-type is 0x1 (this standard for all AirQ 300 boards)
  • Remote control board address is 3.0.1.5 (first octet, 3, clearly indicates that the message is addressed to an AirQ 300).
  • Sent data is 0x10, which is the command to send to control board to turn on RELAY1 (Please, refer to sNET documentation for AirQ 300)

Message modifiers

sNET defines some message modifiers used to mark a message and to associate it a special behavior. Message modifiers are masks that are logic ANDed with Message Type field. These are the currently defined message modifiers in sNET 4:

sNET Message Types as protocol version 4.1
Message Modifier Mask Apply to Description
RESERVED 0x20 Data messages Reserved modifier. Discard if present
MSG_CONFIRM 0x40 Data and Command messages Ask to receiving peer to confirm message
MSG_CONFIRMED 0x80 Data and Command messages Tell to remote peer that message is confirmed

Message modifiers are really useful to add additional information related to the message avoiding to waste bytes (the power required is directly dependent on the message length).

As described before, sNET is a best effort protocol that doesn't guarantee that a message is received from a device. MSG_CONFIRM is a way to ask a device to confirm a received message (both data and command). When a remote peer (both End or Receiver device) receives a message with a MSG_CONFIRM modifier, it has to confirm the message resending the SAME message but with MSG_CONFIRMED modifier instead of MSG_CONFIRM. This functionality is not supported by all AirQ Network devices.

Message modifiers are a bitmask of Message Type field. This means that the application layer has to check if a message modifier is present to compute the correct type. Following C language pseudo-code shows the wrong way to check a message type.

...
#define MAX_MSG_LENGTH 30
typedef char uint8_t;

uint8_t message[MAX_MSG_LENGTH]; /* message is supposed to contain a data message */

...

if (message[8] == 0x1) { /* WRONG WAY */
...

The above code is clearly the wrong way to check against a message type as it could contain a message modifier. Following code shows the right way to do it:

...
#define MAX_MSG_LENGTH 30
#define MSG_TYPE_MODIFIERS (0x20 | 0x40 | 0x80)
 
#define CHECK_MSG_TYPE(msg, type) ((msg[8] & ~MSG_TYPE_MODIFIERS) == type)
typedef char uint8_t;
 
uint8_t message[MAX_MSG_LENGTH]; /* message is supposed to contain a data message */
 
...
 
if (CHECK_MSG_TYPE(msg, 0x1)) { /* CORRECT WAY */...

Device dependent messages

Each AirQ Networks device defines its subtype of messages and their data representation. So, in order to establish the content of whole message, it's important to know the exact format of a message for a given device. Documentation for each type of device is available clicking on the corresponding device in the following list.

AirQ 101 - wireless temperature sensor (covers both AirQ 101 and AirQ 101-EXT)
AirQ 121 - wireless temperature datalogger (covers AirQ 121/122 and AirQ 121/122-EXT)
AirQ 110 - wireless humidity sensor
AirQ 111 - wireless humidity and temperature sensor
AirQ 300 - wireless control board with 4 opto-isolated inputs and 2 relay
AirQ 310 - wireless control board with 6 relays
AirQ RNG - wireless range extender (signal repeater)
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox