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

field name

length

value

explanation

control byte

1 byte

00

 

id byte

1 byte

00

 

command

1 byte

05

NOTIFICATION (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

type

1 byte

00

0 = raw samples (see table "Sample/Report notification" of http://www.linear.com/docs/42453, pdf page 198)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

01

1 byte

value

1 byte

05

temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

timestamp

12 bytes

12 bytes

000000003d226bc600060eb3

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

00007530

0x7530 == 30000 (30,000ms == 30s)

num samples

1 byte

01

 

sample size

1 byte

10

16-bit sample

sample

2 bytes

08f9

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

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

01

1 byte

value

1 byte

05

temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

value

type

1 byte

00

variable “enable“ for /temperature

length

1 byte

01

1 byte

value

1 byte

01

1=enabled

value

type

1 byte

01

variable “rate“ for /temperature

length

1 byte

04

4 bytes

value

1 byte

00002710

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

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

01

1 byte

value

1 byte

05

temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

value

type

1 byte

00

variable “enable“ for /temperature

length

1 byte

01

1 byte

value

1 byte

00

0=disabled

Re-enabling temperature measurements every 30s

Send the following payload:

Which encodes the following:

field name

length

value

explanation

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

01

1 byte

value

1 byte

05

temperature (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

value

type

1 byte

00

variable “enable“ for /temperature

length

1 byte

01

1 byte

value

1 byte

01

1=enabled

value

type

1 byte

01

variable “rate“ for /temperature

length

1 byte

04

4 bytes

value

1 byte

0000‭7530‬

0x‭7530‬ == 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

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

02

1 byte

value

1 byte

0302

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

00

variable “value” for /digital_out

length

1 byte

01

1 byte

value

1 byte

01

1=set pin to 1

Enabling GPIO notifications

Send the following payload:

Which encodes the following:

field name

length

value

explanation

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

02

1 byte

value

1 byte

0200

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

00

variable “enable“ for /digital_in

length

1 byte

01

1 byte

value

1 byte

01

1=enabled

value

type

1 byte

03

variable “dataformat“ for /digital_in

length

1 byte

01

1 byte

value

1 byte

01

1='on-change'

Receiving a GPIO notification

You receive the following payload:

Which encodes the following:

field name

length

value

explanation

field name

length

value

explanation

control byte

1 byte

00

 

id byte

1 byte

04

 

command

1 byte

05

NOTIFICATION (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

type

1 byte

02

2 = digital change notification (see table "Sample/Report notification" of http://www.linear.com/docs/42453, pdf page 199)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

02

1 byte

value

1 byte

0200

digital_in/D0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

timestamp

12 bytes

12 bytes

000000003d226bc9000bea65

timestamp when the measurement was taken

new value

1 byte

01

1 = pin is pulled high

Disabling GPIO notifications

Send the following payload:

Which encodes the following:

field name

length

value

explanation

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

02

1 byte

value

1 byte

0200

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

00

variable “enable“ for /digital_in

length

1 byte

01

1 byte

value

1 byte

00

0=disabled

ADC

Enabling ADC readings every 10s

Send the following payload:

Which encodes the following:

field name

length

value

explanation

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

02

1 byte

value

1 byte

0400

analog/A0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

value

type

1 byte

00

variable “enable“ for /analog

length

1 byte

01

1 byte

value

1 byte

01

1=enabled

value

type

1 byte

01

variable “rate“ for /analog

length

1 byte

04

4 bytes

value

1 byte

00002710

0x2710 == 10000 (10,000ms == 10s)

Receiving an ADC reading

You receive the following payload:

Which encodes the following:

field name

length

value

explanation

field name

length

value

explanation

control byte

1 byte

00

 

id byte

1 byte

06

 

command

1 byte

05

NOTIFICATION (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

type

1 byte

00

0 = raw samples (see table "Sample/Report notification" of http://www.linear.com/docs/42453, pdf page 198)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

02

1 byte

value

1 byte

0400

analog/A0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

timestamp

12 bytes

12 bytes

000000003d226e5a0009047d

timestamp when the measurement was taken

rate

4 bytes

00002710

0x2710 == 10000 (10,000ms == 10s)

num samples

1 byte

01

 

sample size

1 byte

10

16-bit sample

sample

2 bytes

0603

0x0603 == ‭1539‬ (1539 mV == 1.539 V)

Disabling periodic ADC readings

Send the following payload:

Which encodes the following:

field name

length

value

explanation

field name

length

value

explanation

control byte

1 byte

05

 

id byte

1 byte

00

 

command

1 byte

02

PUT (see "Command field" of http://www.linear.com/docs/42453, pdf page 186)

channel

type

1 byte

ff

address (see Section "Address representation" of http://www.linear.com/docs/42453, pdf page 188)

length

1 byte

02

1 byte

value

1 byte

0400

analog/A0 (see Section "Addressable Elements and Pinout" of http://www.linear.com/docs/42453, pdf page 191)

value

type

1 byte

00

variable “enable“ for /analog

length

1 byte

01

1 byte

value

1 byte

00

0=disabled