The OpenWSN stack communicates with the OpenVisualizer over a serial connection. This pages describes the format of the serial frames whizzing back-and-forth between the mote and the computer. Note that all motes running the OpenWSN stack can communicate of their serial port, not just the DAGroot in the network.

General Format

Packet are framed using HDLC, defined in RFC1662:

A couple of points to note:

• The opening and closing flags are the same (0x7e). This is because this character can be used, in the HDLC standard, as "keep-alive" messages. A frame really starts when receiving a byte different from 0x7e.
• The CRC used is a 16-bit with generator polynomial: x^0 + x^5 + x^12 + x^16. You can see an implementation example in Appendix C of RFC1662.

Frames Sent by Mote

This section covers the format of the frames sent by the mote to the computer.

General Format

The payload of the HDLC frame has the following format:

The type field can take the following values:

SERFRAME_MOTE2PC_DATA Frame

This type of frame is generated by the DAGroot when it receives data from a mote in its network. The payload contains the data itself, prepended by the 6LoWPAN header.

The OpenVisualizer, which receives this frame, hand it off as is to the LBR which de-compacts the 6LoWPAN header and injects it into the IPv6 Internet. The OpenVisualizer does no do any form of checking on this packet, i.e. any payload with the "data" header type is forwarded to the LBR. The LBR ensures that the packet is a value 6LoWPAN packet, but does not do any validation on the payload, which it sends as-is into the IPv6 Internet.

On the mote side, a data frame is generated by calling the openserial_printData() function.

On the Python side, the data frame is handled by the ParserData module.

SERFRAME_MOTE2PC_STATUS Frame

This type of frame is used by the mote to continuously report the status of internal modules. The payload is parsed by the OpenVisualizer, the state of the different modules is stored and displayed in the "mote status" menu of the OpenVisualizer.

The format of a status frame is:

The type dictates the format of the payload. The format is giving by a (packet) C struct, as per the table below:

On the mote side, a status frame is generated by calling the openserial_printStatus() function. This is orchestrated by the openserial module.

On the Python side, status frames are handled by the ParserStatus module.

SERFRAME_MOTE2PC_INFO, SERFRAME_MOTE2PC_ERROR and SERFRAME_MOTE2PC_CRITICAL Frames

These frames are printed by the mote when it encounters some error case. They have the following format:

• The severity indicates the type of frame: INFO, ERROR or CRITICAL (see table above for value).
• The calling component indicates which component in the stack is reporting this error. The value is taken from the COMPONENT_* enum in the openwsn.h file.
• The error code is taken from the ERR_* enum in the openwsn.h file.
• The value of arg1 and arg2 depends on the error code passed. Refer to the comment in the corresponding in openwsn.h.

REQUEST Frame

This frame is used by the mote to indicate to the computer it is ready to receive data. Some hardware platform supported by OpenWSN are too constrained to be able to receive at all time. Instead, some slots in the schedule are of type SERIAL_RX. At the beginning of those, the mote sends out a request frame, indicating that it can now receive data. It is the responsibility of the computer to answer "fast", i.e. before the end of the (possible multiple) SERIAL_RX slots.

The request frame has no payload.

Frames Sent by Computer

This section details the format of the frames sent by the computer to the mote. The computer can only do so after receiving a request frame from the mote.

General Format

The payload of the HDLC frame has the following format:

The type field can take the following values:

SERFRAME_PC2MOTE_SETROOT Frame

The format of the SETROOT frame is as follows:

The action field can take the following values:

the prefix field contains the IPv6 prefix of the network. The DAGroot will announce this value in its DIOs.

SERFRAME_PC2MOTE_DATA Frame

DATA frame format:

This frame passes a 6LoWPAN message from a DAGroot mote into the mesh. The openbridge module performs minimal checking on the message, the sixtop module prepends the 802.15.4 header, and then the message is transmitted.

On the Python side, the OpenLbr module does the work of converting an incoming IPv6 message into the required 6LoWPAN format, including any source routing headers from the RPL module.

SERFRAME_PC2MOTE_TRIGGERSERIALECHO Frame

The format of the TRIGGERSERIALECHO frame is as follows:

When mote receives this frame with info STACKNAME, it sends back the name of stack, which is "OpenWSN".

SERFRAME_PC2MOTE_COMMAND_GD Frame