/** * \page cmd_exterior Command Engine, Exterior Interface Protocols This page describes the command engine exterior interface protocols between a ScatterWeb and the outside world.
At the lower layer, the command engine is connected to available hardware interfaces of the ScatterWeb node. After a command has been submitted through interface it will be converted to the standard binary representation documented in \ref cmd_spec. The lower layer needs to provide size information and optional addressing to the command engine.
Currently commands can be received and submitted through two hardware interfaces: radio and serial port. While the radio is used for forwarding and node to node communication, the serial port is used at gateways to allow human operators and applications access to the sensor network.
Actual Interface | Interface Header | Command Packet | Interface Tail | |
---|---|---|---|---|
handled by the command interface | handled by command or protocol handlers | handled by the command | ||
Interface Header | Command Header | Arguments | Interface Tail | |
\ref cmd_l1_radio | Radio Packet Header (#nwheader_t) | Command Header (#cmd_header_t) | Arguments | Interface Tail (CRC16) |
\ref cmd_l1_serial | Serial Command Header (cmd_serialheader_t) | Command Header (#cmd_header_t) | Arguments | - |
Command are sent in the standard binary representation through the radio interface. The radio packet addressing is used to determine target and response address. The type of the command packet (request/response) is determined by the protocol id used.
\see #packet_t, #CMD_REQ_PACKET, #CMD_RPL_PACKET \section cmd_l1_serial Serial InterfaceThe serial interface is the main human-machine and machine-machine interface to the network. Input is interpreted line-wise. Lines may not contain NUL characters and are terminated by CR or CRLF.
Inbound lines are classified by the first character.
Marker | Description |
---|---|
> |
Inbound Binary-Mode Command Request. All following characters until LF are hex-encoded |
\@ |
Inbound ASCII-Mode Command Request with destination address |
others | Inbound ASCII-Mode Command Request |
Outbound lines can be classified by the receiver by the the first character.
Marker | Description |
---|---|
< |
Outbound Binary-Mode Command Reply. All following characters until LF are hex-encoded |
[ |
Outbound ASCII-Mode Command Reply |
# | Informative ASCII output |
Multiline output can be grouped by using curly brackets. The example shows the startup screen marked as a single comment packet:
#=============================================================================={ DCO: 0xd3 BCS: 0xb7 RESET: 1 [SWRESET] Radio Channel: 1 Node address: 27 TX Power: 0x0f LogLevel: Runtime: 0x01 [LOW] Boot: 0x01 [LOW] Platform: MSB430 rev 1 FLASH[BLD]: none FLASH[EOS]: MSBEOS 1.2 2007-10-30#15:49:46|80|0x0 FLASH[APP]: SDDEMO 1.0 2007-10-30#15:52:51|00|0x6f56 ==============================================================================}\subsection cmd_l1_serial_in Inbound ASCII-Mode Command Request
Inbound ASCII command requests have the following format.
Forward address (optional) | Command String | Argument String (optional) | Comment (optional) |
@(\\*|[0-9]+)\\s |
[a-zA-Z0-9]+ |
\\s[^$]* |
\\s+#[^$]* |
Examples:
Example | Destination | Description |
---|---|---|
id |
directly connected node | Command request with no arguments |
id 1 |
directly connected node | Command request with one argument |
\@* id |
all nodes in network | Broadcast command request with no arguments |
\@11 echoargs 1 2 3 |
11 | Unicast commad request with three arguments |
Outbound ASCII-Mode command responses have the following format. If no source address is given, the response was sent by the connected node.
Start of header | Source address (optional) | Command String | End of header | Argument String (optional) |
---|---|---|---|---|
\\[ |
[0-9]+: |
[a-zA-Z0-9]+ |
\\]\\s |
[^$]* |
To separate multiple arguments it is good practice to separate them by one or more spaces (0x20). If name shall be supplied with the arguments these should be precede the argument.
Outbound responses can be sent without previous request making them unsolicited responses.
Example | Destination | Description |
---|---|---|
[id] 1 |
directly connected node | Command response with unnamed argument |
[11:echoargs] A:1 B:2 C:3 |
11 | Command response with three named arguments |
Binary-Mode command requests and responses on the serial interface are prepended by the following header. The command packet following this header can contain any command packet in binary or ascii mode.
Offset: | 0 | 1 | 2 | 3 | .. | ..n | n+1 |
---|---|---|---|---|---|---|---|
Field: | Marker | Address | Payload size | Command | Arguments (optional) | Checksum |
\see cmd_serialheader_t, cmd_header_t
Field | Size | Description |
---|---|---|
Marker | 8 | First character of line for input classification |
Address | 16 | Inbound requests: forward address (may be zero to address the connected
node) Outbound responses: address of responding node |
Payload size | 8 | Number of bytes following (size of command packet plus optional arguments) |
Command | variable | #cmd_header_t structure |
Arguments | variable | any binary argument data that is passed to the command handler |
Checksum | 1 | Checksum (XOR) over bytes 1-n |