/** * \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.

Table: General format of command protocol packets
Actual Interface Interface HeaderCommand PacketInterface Tail
  handled by the command interfacehandled by command or protocol handlershandled by the command
  Interface HeaderCommand HeaderArgumentsInterface Tail
\ref cmd_l1_radio Radio Packet Header
(#nwheader_t)
Command Header
(#cmd_header_t)
ArgumentsInterface Tail
(CRC16)
\ref cmd_l1_serial Serial Command Header
(cmd_serialheader_t)
Command Header
(#cmd_header_t)
Arguments-
\section cmd_l1_radio Radio Interface

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 Interface

The 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.

Table: Serial Interface, Inbound line classification
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.

Table: Serial Interface, Inbound line classification
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.

Table: ASCII-Mode Command Request String 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
\subsection cmd_l1_serial_out Outbound ASCII-Mode Command Reply

Outbound ASCII-Mode command responses have the following format. If no source address is given, the response was sent by the connected node.

Table: ASCII-Mode Command Reply String Format
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
\subsection cmd_l1_serial_binary In-/Outbound Binary-Mode Command Packet

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.

Table: Serial Interface Binary-Mode Header Packet Format
Offset: 0 1 2 3 .. ..n n+1
Field: Marker Address Payload size Command Arguments (optional) Checksum

\see cmd_serialheader_t, cmd_header_t

Table: Serial Interface Binary-Mode Header Packet Description
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
*/