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

- \ref cmd_l1_radio
- \ref cmd_l1_serial

\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+#[^$]*`

- Multiple arguments are separated by one or more space (0x20) characters. The API provides functionality to handle these (:Cmd_SplitArgs, :Cmd_GetNextArg).
- On ASCII-Mode requests the response flag is always set.
- The forwared address is a node address (#address_t), a star (*) may be used as shortcut for the broadcast address (#SUBNET_BROADCAST).

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

*/