Deep-dive into the OAP Protocol
The “On-chip Application Protocol“ (OAP) runs on all SmartMesh IP motes running in Master mode. See how you can interact with it to sample temperature, set/get the state GPIO pins, and trigger ADC readings.
Setup
We assume you have the following:
A SmartMesh IP manager connected to your computer
A SmartMesh IP mote that has joined that SmartMesh IP manager
The APIExplorer application running your computer, and connected to the API serial port of your SmartMesh IP manager
Interacting with the default firmware
This section lists the different payloads you send a receive from the mote:
To receive notifications, make sure you have subscribed to notifications by issuing the “subscribe” command with the filter argument set to 0xffffffff:
In the examples below, use the sendData command to send OAP commands to a mote in the network with the command payload in the “data” field.
You will see the notifications in the “notifications” pane.
Temperature sensor
Receiving temperature notifications
You receive the following payload:
00000500ff0105000000003d226bc600060eb300007530011008f9
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| NOTIFICATION (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
type | 1 byte |
| 0 = raw samples (see table "Sample/Report notification" of http://www.linear.com/docs/42453, pdf page 198) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
timestamp | 12 bytes | 12 bytes |
| timestamp when the measurement was taken. Timestamps are in “network time” where the first four bytes are always 0, the middle four bytes are seconds (and the start of “network time” is XXX), and the final four bytes are microseconds. |
rate | 4 bytes |
| 0x7530 == 30000 (30,000ms == 30s) | |
num samples | 1 byte |
|
| |
sample size | 1 byte |
| 16-bit sample | |
sample | 2 bytes |
| 0x08f9 == 2297 (in 1/100th of a degree: 22.97 C) |
Changing temperature period to 10s
Send the following payload:
050002ff0105000101010400002710
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
value | type | 1 byte |
| variable “enable“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 1=enabled | |
value | type | 1 byte |
| variable “rate“ for |
length | 1 byte |
| 4 bytes | |
value | 1 byte |
| 0x2710 == 10000 (10,000ms == 10s) change this value to change the period. |
Disabling temperature measurements
Send the following payload:
050002ff0105000100
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
value | type | 1 byte |
| variable “enable“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 0=disabled |
Re-enabling temperature measurements every 30s
Send the following payload:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
value | type | 1 byte |
| variable “enable“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 1=enabled | |
value | type | 1 byte |
| variable “rate“ for |
length | 1 byte |
| 4 bytes | |
value | 1 byte |
| 0x7530 == 30000 (30,000ms == 30s) change this value to change the period. |
GPIO
Setting the state of a GPIO
Send the following payload to switch the blue LED ON:
Send the following payload to switch the blue LED OFF:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| digital_out/INDICATOR_0 LED (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) change this value to address any of the other “digital_out“ pins. | |
value | type | 1 byte |
| variable “value” for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 1=set pin to 1 |
Enabling GPIO notifications
Send the following payload:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| digital_in/D0, pin identified with silkscreen “DP2“ on DC9003 board (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
value | type | 1 byte |
| variable “enable“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 1=enabled | |
value | type | 1 byte |
| variable “dataformat“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 1='on-change' |
Receiving a GPIO notification
You receive the following payload:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| NOTIFICATION (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
type | 1 byte |
| 2 = digital change notification (see table "Sample/Report notification" of http://www.linear.com/docs/42453, pdf page 199) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| digital_in/D0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
timestamp | 12 bytes | 12 bytes |
| timestamp when the measurement was taken |
new value | 1 byte |
| 1 = pin is pulled high |
Disabling GPIO notifications
Send the following payload:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| digital_in/D0, pin identified with silkscreen “DP2“ on DC9003 board (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
value | type | 1 byte |
| variable “enable“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 0=disabled |
ADC
Enabling ADC readings every 10s
Send the following payload:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| analog/A0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
value | type | 1 byte |
| variable “enable“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 1=enabled | |
value | type | 1 byte |
| variable “rate“ for |
length | 1 byte |
| 4 bytes | |
value | 1 byte |
| 0x2710 == 10000 (10,000ms == 10s) |
Receiving an ADC reading
You receive the following payload:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| NOTIFICATION (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
type | 1 byte |
| 0 = raw samples (see table "Sample/Report notification" of http://www.linear.com/docs/42453, pdf page 198) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| analog/A0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
timestamp | 12 bytes | 12 bytes |
| timestamp when the measurement was taken |
rate | 4 bytes |
| 0x2710 == 10000 (10,000ms == 10s) | |
num samples | 1 byte |
|
| |
sample size | 1 byte |
| 16-bit sample | |
sample | 2 bytes |
| 0x0603 == 1539 (1539 mV == 1.539 V) |
Disabling periodic ADC readings
Send the following payload:
Which encodes the following:
field name | length | value | explanation | |
---|---|---|---|---|
control byte | 1 byte |
|
| |
id byte | 1 byte |
|
| |
command | 1 byte |
| PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186) | |
channel | type | 1 byte |
| address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188) |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| analog/A0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191) | |
value | type | 1 byte |
| variable “enable“ for |
length | 1 byte |
| 1 byte | |
value | 1 byte |
| 0=disabled |