Introduction
The following document provides the necessary information for implementing a generic communication interface between the wireless board (mote) and the sensor board. Any kind of sensor board can be connected to the mote using this specification given it provides a SPI peripheral, one input pin with interrupt capability and one digital output. The sensor board must implement a special register set from which all required information can be retrieved.
Pin out
New sensor boards can be seamless connected to a mote if the following characteristics are available:
- A sensor board with standard slave SPI channel SPI (MOSI, MISO, SCLK, /SS)
- Frequency of 4MHz for communication, using 8 bits, with with least significant bit (LSB) first
- Polarity and Phase clock must be set in mode 0 (both zero) .
Two interrupt lines are provided for indicating critical events. One line is from sensor to mote and the other is from mote to sensor.
- Sensor → mote interrupt line: When the mote wants to read values from the sensor it puts this line in high beforehand and waits 100ms. This signal is used to wake up the sensor from any possible energy saving mode, waiting for the communication. This line will be kept high while the mote continues to communicates with the sensor. If the sensor board does not provide any energy saving mode (always in active mode) or it can be activated quickly, this line can be ignored. In such situation, SPI chip select (/SS) will be used to detect the communication request.
- Processor → sensor interrupt line: This line is used for urgent notifications from sensor, indicating any asynchronous event that should be handled immediately . It may be an indication of an external event that can not wait for normal read cycle or a sensor failure, for instance. The mote will read the status register to acknowledge the interrupt, detecting the type of event, like a urgent point that should be read or some sensor failure. The sensor will deactivate this line only after the status register is read and a minimum time of 500ms should be respected before making this line active again.
Power supply lines are also provided (VCC and GND). In this case, the mote should be prepared to provide energy for the sensor board or to receive energy from it. Sensor boards that are capable of providing energy will indicate such situation in their identification registry (capability field).
Protocol Overview
The proposed protocol is based on several access to a register map defined in the sensor board. All accesses are synchronous so each request must be followed by a response and a maximum timeout need to be respected. Any communication frame can not be greater than 96 bytes (TBD). The exact amount of bytes is determined after reading the device identification register and point description registers. The idea is all sensor data fits inside a unique 6LoWPAN frame.
Data types used in this documentation are described in the data types table. There is no string data type and arrays should be considered as a regular array of any basic data type. When describing a field, numbers in front of the data type indicates the array size. For instance, 4L means a sequence of four unsigned longs (16 bytes). If the quantity is omitted it must be considered as 1. All data types that are longer than one byte should be considered as little endian.
The generic request frame is below:
| Size | Description |
|---|---|
| B | Frame Size (n+1 bytes) - CRC not included |
| B | Register Address |
| nB | Frame Data (if any) |
| 2B | CRC |
Response frames are described below. All answers must be synchronous, with 500ms of timeout. After this timeout two retries can be done, with timeouts of 1000ms and 2000ms, respectively. If sensor board continues not responding, it should be considered in failure state and the mode should try to identify the board again at each one minute.
| Size | Description |
|---|---|
| B | Frame Size (n+2 bytes) - CRC not included |
| B | Response Status (see response code table) |
| B | Register Address |
| nB | Frame Data |
| 2B | CRC |
Sensor Board Register Map
The set of registers that should be implemented are listed below:
| Address | Access Rights | Description |
|---|---|---|
| 0x00 | RO | Sensor Board Interface Version |
| 0x01 | RO | Sensor Board Identification |
| 0x02 | RO | Sensor Board Status |
| 0x03 | RO | Sensor Board Command |
| 0x04 | RO | Read Battery Status |
| 0x05 | WO | Write Battery Status |
| 0x06 | RO | Read Battery Charge |
| 0x07 | WO | Write Battery Charge |
| 0x08 | WO | Wireless network status |
| 0x09 | WO | Wireless network Strength (RSSI, 0 to 100%) |
| 0x0A | WO | Display (when display is available) |
| 0x0B | RO | Main server address (IPv6) |
| 0x0C | RO | Secondary server address (IPv6) |
| 0x0D to 0x0F | -- | Reserved (Should not be answered) |
| 0x10 to 0x2F | RO | Sensor Point Description (Point 0 to 31) |
| 0x30 to 0x4F | RO | Read Sensor Point (Point 0 to 31) |
| 0x50 to 0x6F | WO | Write Sensor Point (Point 0 to 31) |
| 0x70 to 0xFF | -- | Reserved |
Command Description
Sensor Board Interface Version (0x00)
In this register is stored which version of the sensor interface is implemented. At this moment, only version available is 0x00 (alpha version).
Request
| Value | Size | Description |
|---|---|---|
| 0x01 | B | Size |
| 0x00 | B | Address |
| CRC | S | CRC |
Response
| Value | Size | Description |
|---|---|---|
| 0x03 | B | Size |
| Status | B | Response status |
| 0x00 | B | Address |
| Version | B | Interface version implemented |
| CRC | S | CRC |
Sensor Board Indentication (0x01)
This register returns the sensor identification, like serial number, name and the amount of sensor points available. The maximum number of sensor points is 32.
Request
| Value | Size | Description |
|---|---|---|
| 0x01 | B | Size |
| 0x01 | B | Address |
| CRC | S | CRC |
Response
| Value | Size | Description |
|---|---|---|
| 0x19 | B | Size |
| Status | B | Response status |
| 0x01 | B | Address |
| Model | 8B | Eight bytes describing the model name. This field may be filled with (0x00) |
| Manufacturer | 8B | Eight bytes describing the manufacture name. This field may be filled with (0x00) |
| ID | L | Sensor board ID |
| Revision | B | Hardware revision |
| Points | B | Number of points (maximum is 32 |
| Capabilities | B | Sensor capabilities (see capabilities table) |
| CRC | S | CRC |
Sensor Board Status (0x02)
This register holds the sensor board status, following table sensor status table. Critical and asynchronous events may be flagged using this register.
Request
| Value | Size | Description |
|---|---|---|
| 0x01 | B | Size |
| 0x02 | B | Address |
| CRC | S | CRC |
Response
| Value | Size | Description |
|---|---|---|
| 0x03 | B | Size |
| Status | B | Response status |
| 0x02 | B | Address |
| Status | B | Sensor Status Code |
| CRC | S | CRC |
Sensor Board Command (0x03)
A command can be sent to the sensor using this register. Refer to the command table (TDB).
Request
| Value | Size | Description |
|---|---|---|
| 0x02 | B | Size |
| 0x03 | B | Address |
| Command | B | Command |
| CRC | 2B | CRC |
Response
| Value | Size | Description |
|---|---|---|
| 0x03 | B | Size |
| Status | B | Response status |
| 0x03 | B | Address |
| Status | B | Command execution result |
| CRC | S | CRC |
Read Battery status (0x04)
If the power supply is provided by the sensor, it should report this information using the sensor capabilities field. In this case, this register is used to read the battery status. Please, refer to the battery status table.
Request
| Value | Size | Description |
|---|---|---|
| 0x01 | B | Size |
| 0x04 | B | Address |
| CRC | S | CRC |
Response
| Value | Size | Description |
|---|---|---|
| 0x03 | B | Size |
| Status | B | Response status |
| 0x04 | B | Address |
| Status | B | Battery status |
| CRC | S | CRC |
Write Battery status (0x05)
When the battery is attached to the mote, it can use this register to report battery information to the sensor board. A sensor board with display could show this information to the user.
Request
| Value | Size | Description |
|---|---|---|
| 0x02 | B | Size |
| 0x05 | B | Address |
| Status | B | Battery status |
| CRC | 2B | CRC |
Response
| Value | Size | Description |
|---|---|---|
| 0x02 | B | Size |
| Status | B | Response status |
| 0x05 | B | Address |
| CRC | 2B | CRC |
Read Battery charge (0x06)
If the power supply is provided by sensor it should report this information using the sensor capabilities field. In this case, this register is used to read the battery charge.
Request
|-------+------+-------------|
| Value | Size | Description |
|-------+------+-------------|
| 0x01 | B | Size |
| 0x06 | B | Address |
| CRC | S | CRC |
|-------+------+-------------|
Response
|--------+------+----------------------------|
| Value | Size | Description |
|--------+------+----------------------------|
| Size | B | Response size |
| Status | B | Response status |
| Charge | B | Battery charge (0 to 100%) |
| CRC | S | CRC |
|--------+------+----------------------------|
Read Battery charge (0x07)
When the battery is attached to the mote, it can use this register to report battery charge to the sensor board. A sensor board with display could show this information to the user.
Request
|--------+------+----------------------------|
| Value | Size | Description |
|--------+------+----------------------------|
| 0x02 | B | Size |
| 0x07 | B | Address |
| Charge | B | Battery charge (0 to 100%) |
| CRC | S | CRC |
|--------+------+----------------------------|
Response
|--------+------+-----------------|
| Value | Size | Description |
|--------+------+-----------------|
| Size | B | Response size |
| Status | B | Response status |
| CRC | S | CRC |
|--------+------+-----------------|
Wireless network status (0x08)
This register is used to report the wireless status to the sensor board. A sensor board with display could show this information to the user. In this case, sensor capability should indicate that wireless information is required.
Request
|--------+------+-----------------------------|
| Value | Size | Description |
|--------+------+-----------------------------|
| 0x02 | B | Size |
| 0x08 | B | Address |
| Status | B | Network status (see table) |
| CRC | S | CRC |
|--------+------+-----------------------------|
Response
|--------+------+-----------------|
| Value | Size | Description |
|--------+------+-----------------|
| Size | B | Response size |
| Status | B | Response status |
| CRC | S | CRC |
|--------+------+-----------------|
Wireless network strength (0x09)
This register is used to report the wireless strength to the sensor board. A sensor board with display could show this information to the user. In this case, sensor capability should indicate that wireless information is required.
Request
|--------+------+-------------------------------------|
| Value | Size | Description |
|--------+------+-------------------------------------|
| 0x02 | B | Size |
| 0x09 | B | Address |
| Status | B | Network signal strength (0 to 100%) |
| CRC | S | CRC |
|--------+------+-------------------------------------|
Response
|--------+------+-----------------|
| Value | Size | Description |
|--------+------+-----------------|
| Size | B | Response size |
| Status | B | Response status |
| CRC | S | CRC |
|--------+------+-----------------|
Display register (0x0A)
If the sensor has some display attached (reported in capabilities field),the mote can use it for bringing information to the user. The display need to have a way to map the ASCII information received for a specific display line. Character displays organized as 24x2 (24 columns and 2 lines) are a natural candidate but other displays can be used since a proper mapping is provided.
Request
|-------------+------+-------------------------------|
| Value | Size | Description |
|-------------+------+-------------------------------|
| 26 | B | Size |
| 0x0A | B | Address |
| Line | B | Display Line |
| Information | 24B | Display information, in ASCII |
| CRC | S | CRC |
|-------------+------+-------------------------------|
Response
|--------+------+-----------------|
| Value | Size | Description |
|--------+------+-----------------|
| Size | B | Response size |
| Status | B | Response status |
| CRC | S | CRC |
|--------+------+-----------------|
Main server address (0x0B)
This register holds the server address to which the sensor data should be reported.
Request
|--------+------+--------------|
| Value | Size | Description |
|--------+------+--------------|
| 0x02 | B | Size |
| 0x0B | B | Address |
| Server | 16B | IPv6 address |
| CRC | S | CRC |
|--------+------+--------------|
Response
|--------+------+-----------------|
| Value | Size | Description |
|--------+------+-----------------|
| Size | B | Response size |
| Status | B | Response status |
| CRC | S | CRC |
|--------+------+-----------------|
Secondary server address (0x0C)
When the main server is not available (register 0x09), this register holds the secondary server address to which the sensor data should be reported.
Request
|--------+------+--------------|
| Value | Size | Description |
|--------+------+--------------|
| 0x02 | B | Size |
| 0x0C | B | Address |
| Server | 16B | IPv6 address |
| CRC | S | CRC |
|--------+------+--------------|
Response
|--------+------+-----------------|
| Value | Size | Description |
|--------+------+-----------------|
| Size | B | Response size |
| Status | B | Response status |
| CRC | S | CRC |
|--------+------+-----------------|
Sensor Point Description (0x10 to 0x2F)
This range of registers is used to provided information about a specific point like point name, access rights, data type, unit and sampling time. It is possible to use the interrupt line and status register to indicate that a reading is pending for this point. The sampling time is specified as a multiple of 250ms and points with sampling time equal to 0 should not be read in the cyclic readings.
Request
|-------+------+------------------------------|
| Value | Size | Description |
|-------+------+------------------------------|
| 0x01 | B | Size |
| Point | B | Point Address (0x10 to 0x2F) |
| CRC | S | CRC |
|-------+------+------------------------------|
Response
|----------+------+--------------------------------------|
| Value | Size | Description |
|----------+------+--------------------------------------|
| Size | B | Response size |
| Status | B | Response status |
| Name | 8B | Point name |
| | | This field may be filled with (0x00) |
| Type | B | Point type |
| Unit | B | Point unit |
| Rights | B | Access rights |
| Sampling | L | Sampling time (x 250ms) |
| CRC | S | CRC |
|----------+------+--------------------------------------|
Read Sensor Point (0x30 to 0x4F)
Read the current value for some sensor point. Point description is used to determine the access rights to the point.
Request
|-------+------+------------------------------|
| Value | Size | Description |
|-------+------+------------------------------|
| 0x01 | B | Size |
| Point | B | Point Address (0x30 to 0x4F) |
| CRC | S | CRC |
|-------+------+------------------------------|
Response
|--------+------+------------------------------------------|
| Value | Size | Description |
|--------+------+------------------------------------------|
| Size | B | Response size |
| Status | B | Response status |
| Value | - | Point value (size depends on point type) |
| CRC | S | CRC |
|--------+------+------------------------------------------|
Read/Write Sensor Point (0x50 to 0x6F)
Write the current value for some sensor point. Point description is used to determine the access rights to the point.
Request
|-------+------+------------------------------------------|
| Value | Size | Description |
|-------+------+------------------------------------------|
| 0x01 | B | Size |
| Point | B | Point Address (0x50 to 0x6F) |
| Value | - | Point value (size depends on point type) |
| CRC | S | CRC |
|-------+------+------------------------------------------|
Response
|--------+------+-----------------|
| Value | Size | Description |
|--------+------+-----------------|
| Size | B | Response size |
| Status | B | Response status |
| CRC | S | CRC |
|--------+------+-----------------|
Appendix: Tables
Data Types
Available data types
|------+---------+--------------------------------------------|
| Type | Acronym | Representation |
|------+---------+--------------------------------------------|
| 0x00 | B | Byte, 8 bits unsigned |
| 0x01 | b | Byte, 8 bits signed |
| 0x02 | S | Short, 16 bits unsigned |
| 0x03 | s | Short, 16 bits signed |
| 0x04 | L | Long, 32 bits unsigned |
| 0x05 | l | Long, 32 bits signed |
| 0x06 | Q | Long long, 64 bits unsigned |
| 0x07 | q | Long long, 64 bits signed |
| 0x08 | F | Float, IEEE 754 single precision, 4 bytes |
| 0x09 | D | Double, IEEE 754 double precision, 8 bytes |
|------+---------+--------------------------------------------|
Sensor Status
Sensor status table
|------------+---------------------------------|
| Code | Status |
|------------+---------------------------------|
| 0 | OK (normal operation) |
| 1 | Point 1 urgent reading/writing |
| 2 | Point 2 urgent reading/writing |
| 3 | Point 3 urgent reading/writing |
| ... | ... |
| 31 | Point 31 urgent reading/writing |
| 32 | Point 32 urgent reading/writing |
| 33 to 127 | Reserved |
| 128 | General sensor failure |
| 129 to 255 | Reserved |
|------------+---------------------------------|
Commands
Sensor command table
|-------+---------+--------------------------------|
| Value | Command | Description |
|-------+---------+--------------------------------|
| 0 | Reset | Performs a reset in the sensor |
| ... | ... | ... |
|-------+---------+--------------------------------|
Units
Units table (TDB, maybe a simplified version of hart data types)
|--------+---------+-------------|
| Values | Acronym | Description |
|--------+---------+-------------|
Answer Status
Answer status table
| Code | Status |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | CRC error |
| 3 | Value is RO |
| 4 | Value is WO |
| 5 | Register not implemented |
Access Rights
Access rights table
|-------+---------+---------------------|
| Value | Acronym | Description |
|-------+---------+---------------------|
| 0x01 | RO | Reading only |
| 0x02 | WO | Writing only |
| 0x03 | RW | Reading and writing |
|-------+---------+---------------------|
Sensor Capabilities
Sensor capabilities table
|-----+-------+----------------------------------------------------|
| Bit | Value | Description |
|-----+-------+----------------------------------------------------|
| 0 | 0x01 | Sensor has attached battery |
| 1 | 0x02 | Sensor has attached display |
| 2 | 0x04 | Sensor wants to receive periodic information about |
| | | the wireless network status |
| 3 | 0x08 | Sensor wants to receive periodic information about |
| | | battery status (only valid whtn attached battery |
| | | flag is not set) |
| 4-7 | - | Reserved |
|-----+-------+----------------------------------------------------|
Battery Status
Battery status table
|-------+----------------|
| Value | Description |
|-------+----------------|
| 0 | Charged (100%) |
| 1 | Charging |
| 2 | Discharging |
| 3 | Failure |
|-------+----------------|
Wireless Status
Wireless status table
|-------+-----------------------|
| Value | Description |
|-------+-----------------------|
| 0 | Network not available |
| 1 | Connecting |
| 2 | Connected |
| 3 | Invalid joining key |
| 3 | ... |
| ... | ... |
|-------+-----------------------|