# Frame Format ##

A frame is defined simply as the concatenation of

 *  A header byte
 *  A command (up to three bytes, see (#packed-unsigned-integer) for format)
 *  An optional command payload

Octets: |    1   | 1-3 |    *n*
--------|--------|-----|-------------
Fields: | HEADER | CMD | CMD_PAYLOAD


## Header Format ###

The header byte is broken down as follows:

      0   1   2   3   4   5   6   7
    +---+---+---+---+---+---+---+---+
    |  FLG  |  IID  |      TID      |
    +---+---+---+---+---+---+---+---+

<!-- RQ -- Eventually, when https://github.com/miekg/mmark/issues/95
is addressed, the above table should be swapped out with this:

| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|---|---|---|---|---|---|---|---|
|  FLG ||  IID ||      TID   ||||
-->

### FLG: Flag

The flag field of the header byte (`FLG`) is always set to the value
two (or `10` in binary). Any frame received with these bits set to
any other value else MUST NOT be considered a Spinel frame.

This convention allows Spinel to be line compatible with BTLE HCI. By
defining the first two bit in this way we can disambiguate between
Spinel frames and HCI frames (which always start with either `0x01`
or `0x04`) without any additional framing overhead.

### IID: Interface Identifier

The Interface Identifier (IID) is a number between 0 and 3 which
identifies which subinterface the frame is intended for. This allows
the protocol to support connecting to more than one network at once.
The first subinterface (0) is considered the primary subinterface and
MUST be supported. Support for all other subinterfaces is OPTIONAL.

### TID: Transaction Identifier

The least significant bits of the header represent the Transaction
Identifier(TID). The TID is used for correlating responses to the
commands which generated them.

When a command is sent from the host, any reply to that command sent
by the NCP will use the same value for the TID. When the host receives
a frame that matches the TID of the command it sent, it can easily
recognize that frame as the actual response to that command.

The TID value of zero (0) is used for commands to which a correlated
response is not expected or needed, such as for unsolicited update
commands sent to the host from the NCP.

### Command Identifier (CMD) ####

The command identifier is a 21-bit unsigned integer encoded in up to
three bytes using the packed unsigned integer format described in
(#packed-unsigned-integer). This encoding allows for up to 2,097,152 individual
commands, with the first 127 commands represented as a single byte.
Command identifiers larger than 2,097,151 are explicitly forbidden.

CID Range             | Description
----------------------|------------------
0 - 63                | Reserved for core commands
64 - 15,359           | *UNALLOCATED*
15,360 - 16,383       | Vendor-specific
16,384 - 1,999,999    | *UNALLOCATED*
2,000,000 - 2,097,151 | Experimental use only

### Command Payload (Optional) ####

Depending on the semantics of the command in question, a payload MAY
be included in the frame. The exact composition and length of the
payload is defined by the command identifier.


