Skip to content
This repository has been archived by the owner on Sep 16, 2021. It is now read-only.

Commit

Permalink
core: Octets->Bytes, OS->AP
Browse files Browse the repository at this point in the history
  • Loading branch information
@darconeous
darconeous committed Nov 1, 2017
1 parent b224fdb commit 4e3dbd4
Show file tree
Hide file tree
Showing 19 changed files with 125 additions and 130 deletions.
2 changes: 1 addition & 1 deletion core/appendix-examples.md
View file
Expand Up @@ -19,7 +19,7 @@ Check interface type to make sure that it is what we expect:
* CMD_VALUE_GET:PROP_INTERFACE_TYPE
* CMD_VALUE_IS:PROP_INTERFACE_TYPE

If the OS supports using vendor-specific commands, the vendor should be verified before using them:
If the AP supports using vendor-specific commands, the vendor should be verified before using them:

* CMD_VALUE_GET:PROP_VENDOR_ID
* CMD_VALUE_IS:PROP_VENDOR_ID
Expand Down
36 changes: 18 additions & 18 deletions core/appendix-framing.md
View file
Expand Up @@ -16,11 +16,11 @@ The recommended default UART settings are:

These values may be adjusted depending on the individual needs of the application or product, but some sort of flow control **MUST** be used. Hardware flow control is preferred over software flow control. In the absence of hardware flow control, software flow control (XON/XOFF) **MUST** be used instead.

We also **RECOMMEND** an Arduino-style hardware reset, where the DTR signal is coupled to the `RES` pin through a 0.01 micro-Farad capacitor. This causes the NCP to automatically reset whenever the serial port is opened. At the very least we **RECOMMEND** dedicating one of your OS host pins to controlling the `RES` pin on the NCP, so that you can easily perform a hardware reset if necessary.
We also **RECOMMEND** an Arduino-style hardware reset, where the DTR signal is coupled to the `RES` pin through a 0.01 micro-Farad capacitor. This causes the NCP to automatically reset whenever the serial port is opened. At the very least we **RECOMMEND** dedicating one of your AP host pins to controlling the `RES` pin on the NCP, so that you can easily perform a hardware reset if necessary.

### UART Bit Rate Detection ###

When using a UART, the issue of an appropriate bit rate must be considered. 115200 bits/s is the conventional baud rate for many serial peripherals. This rate, however, is slower than the theoretical maximum bitrate of many relevant network interfaces, e.g. the 802.15.4 2.4GHz PHY (250kbit). In most circumstances this mismatch is not significant because the overall bitrate will be much lower than either of these rates, but there are circumstances where a faster UART bitrate is desirable. Thus, this document proposes a simple bitrate detection scheme that can be employed by the OS to detect when the attached NCP is initially running at a higher bitrate.
When using a UART, the issue of an appropriate bit rate must be considered. 115200 bits/s is the conventional baud rate for many serial peripherals. This rate, however, is slower than the theoretical maximum bitrate of many relevant network interfaces, e.g. the 802.15.4 2.4GHz PHY (250kbit). In most circumstances this mismatch is not significant because the overall bitrate will be much lower than either of these rates, but there are circumstances where a faster UART bitrate is desirable. Thus, this document proposes a simple bitrate detection scheme that can be employed by the AP to detect when the attached NCP is initially running at a higher bitrate.

The algorithm is to send successive NOOP commands to the NCP at increasing bitrates. When a valid `CMD_LAST_STATUS` response has been received, we have identified the correct bitrate.

Expand All @@ -40,55 +40,55 @@ To transmit a frame with HDLC-lite, the 16-bit CRC must first be appended to the

[KERMIT CRC]: http://reveng.sourceforge.net/crc-catalogue/16.htm#crc.cat.kermit

Individual frames are terminated with a frame delimiter octet called the 'flag' octet (`0x7E`).
Individual frames are terminated with a frame delimiter byte called the 'flag' byte (`0x7E`).

The following octets values are considered *special* and should be escaped when present in data frames:
The following bytes values are considered *special* and should be escaped when present in data frames:

Octet Value | Description
Byte Value | Description
:-----------|:----------------------
0x7E | Frame Delimiter (Flag)
0x7D | Escape Byte
0x11 | XON
0x13 | XOFF
0xF8 | Vendor-Specific

When present in a data frame, these octet values are escaped by prepending the escape octet (`0x7D`) and XORing the value with `0x20`.
When present in a data frame, these byte values are escaped by prepending the escape byte (`0x7D`) and XORing the value with `0x20`.

When receiving a frame, the CRC must be verified after the frame is unescaped. If the CRC value does not match what is calculated for the frame data, the frame MUST be discarded. The implementation MAY indicate the failure to higher levels to handle as they see fit, but MUST NOT attempt to process the deceived frame.

Consecutive flag octets are entirely legal and MUST NOT be treated as a framing error. Consecutive flag octets MAY be used as a way to wake up a sleeping NCP.
Consecutive flag bytes are entirely legal and MUST NOT be treated as a framing error. Consecutive flag bytes MAY be used as a way to wake up a sleeping NCP.

When first establishing a connection to the NCP, it is customary to send one or more flag octets to ensure that any previously received data is discarded.
When first establishing a connection to the NCP, it is customary to send one or more flag bytes to ensure that any previously received data is discarded.

## SPI Recommendations ###
## SPI Recommendations ##

We **RECOMMEND** the use of the following standard SPI signals:

* `CS`: (OS-to-NCP) Chip Select
* `CLK`: (OS-to-NCP) Clock
* `CS`: (AP-to-NCP) Chip Select
* `CLK`: (AP-to-NCP) Clock
* `MOSI`: Master-Output/Slave-Input
* `MISO`: Master-Input/Slave-Output
* `INT`: (NCP-to-OS) Host Interrupt
* `RES`: (OS-to-NCP) NCP Hardware Reset
* `INT`: (NCP-to-AP) Host Interrupt
* `RES`: (AP-to-NCP) NCP Hardware Reset

The `INT` signal is used by the NCP to indicate to the OS that the NCP has frames pending to send to it. When asserted, the OS SHOULD initiate a SPI transaction in a timely manner.
The `INT` signal is used by the NCP to indicate to the AP that the NCP has frames pending to send to it. When asserted, the AP SHOULD initiate a SPI transaction in a timely manner.

We RECOMMEND the following SPI properties:

* `CS` is active low.
* `CLK` is active high.
* `CLK` speed is larger than 500 kHz.
* Data is valid on leading edge of `CLK`.
* Data is sent in multiples of 8-bits (octets).
* Octets are sent most-significant bit first.
* Data is sent in multiples of 8-bits (bytes).
* Bytes are sent most-significant bit first.

This recommended configuration may be adjusted depending on the individual needs of the application or product.

### SPI Framing Protocol ####

Each SPI frame starts with a 5-byte frame header:

Octets: | 1 | 2 | 2
Bytes: | 1 | 2 | 2
--------|-----|----------|----------
Fields: | HDR | RECV_LEN | DATA_LEN

Expand All @@ -109,7 +109,7 @@ The `HDR` byte is defined as:
* `RESERVED`: These bits are all reserved for future used. They MUST be cleared to zero and MUST be ignored if set.
* `PATTERN`: These bits are set to a fixed value to help distinguish valid SPI frames from garbage (by explicitly making `0xFF` and `0x00` invalid values). Bit 6 MUST be set to be one and bit 7 MUST be cleared (0). A frame received that has any other values for these bits MUST be dropped.

Prior to a sending or receiving a frame, the master MAY send a 5-octet frame with zeros for both the max receive frame size and the the contained frame length. This will induce the slave device to indicate the length of the frame it wants to send (if any) and indicate the largest frame it is capable of receiving at the moment. This allows the master to calculate the size of the next transaction. Alternatively, if the master has a frame to send it can just go ahead and send a frame of that length and determine if the frame was accepted by checking that the `RECV_LEN` from the slave frame is larger than the frame the master just tried to send. If the `RECV_LEN` is smaller then the frame wasn't accepted and will need to be transmitted again.
Prior to a sending or receiving a frame, the master MAY send a 5-byte frame with zeros for both the max receive frame size and the the contained frame length. This will induce the slave device to indicate the length of the frame it wants to send (if any) and indicate the largest frame it is capable of receiving at the moment. This allows the master to calculate the size of the next transaction. Alternatively, if the master has a frame to send it can just go ahead and send a frame of that length and determine if the frame was accepted by checking that the `RECV_LEN` from the slave frame is larger than the frame the master just tried to send. If the `RECV_LEN` is smaller then the frame wasn't accepted and will need to be transmitted again.

This protocol can be used either unidirectionally or bidirectionally, determined by the behavior of the master and the slave.

Expand Down
2 changes: 1 addition & 1 deletion core/appendix-test-vectors.md
View file
Expand Up @@ -2,7 +2,7 @@

## Test Vector: Packed Unsigned Integer

Decimal Value | Packet Octet Encoding
Decimal Value | Packet Byte Encoding
-------------:|:----------------------
0 | `00`
1 | `01`
Expand Down
46 changes: 23 additions & 23 deletions core/detail-commands.md
View file
Expand Up @@ -2,8 +2,8 @@

This section defines the standard commands used in all Spinel protocol interactions. Each command is defined for one of the following two contexts:

* OS -> NCP: commands sent by the operating system (OS) to the network control processor (NCP).
* NCP -> OS: commands sent by the network control processor (NCP) to the operating system (OS).
* AP -> NCP: commands sent by the Application Processor (AP) to the Network Co-Processor (NCP).
* NCP -> AP: commands sent by the Network Co-Processor (NCP) to the Application Processor (AP).

A conforming implementation MAY transmit any command defined for its operating context, and MUST process any command received for its operating context, according to the operational semantics defined in this section.

Expand All @@ -17,7 +17,7 @@ CMD Number | Reservation policy
16,384 - 1,999,999 | Unassigned
2,000,000 - 2,097,151 | Experimental Use

## CMD 0: (OS -> NCP) CMD_NOOP {#cmd-noop}
## CMD 0: (AP -> NCP) CMD_NOOP {#cmd-noop}

~~~
0 1
Expand All @@ -35,7 +35,7 @@ The command payload for this command SHOULD be empty. The receiver MUST ignore a

There is no error condition for this command.

## CMD 1: (OS -> NCP) CMD_RESET {#cmd-reset}
## CMD 1: (AP -> NCP) CMD_RESET {#cmd-reset}

0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
Expand All @@ -44,13 +44,13 @@ There is no error condition for this command.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure: Structure of CMD_RESET

Reset NCP. Commands the NCP to perform a software reset. Due to the nature of this command, the TID is ignored. The OS should instead wait for a `CMD_PROP_VALUE_IS` command from the NCP indicating `PROP_LAST_STATUS` has been set to `STATUS_RESET_SOFTWARE` (see (#status-codes)).
Reset NCP. Commands the NCP to perform a software reset. Due to the nature of this command, the TID is ignored. The AP should instead wait for a `CMD_PROP_VALUE_IS` command from the NCP indicating `PROP_LAST_STATUS` has been set to `STATUS_RESET_SOFTWARE` (see (#status-codes)).

The command payload SHOULD be empty, and it SHOULD NOT be processed.

If an error occurs, the value of the emitted `PROP_LAST_STATUS` will be set accordingly to the status code for the error.

## CMD 2: (OS -> NCP) CMD_PROP_VALUE_GET {#cmd-prop-value-get}
## CMD 2: (AP -> NCP) CMD_PROP_VALUE_GET {#cmd-prop-value-get}

~~~
0 1 2 3
Expand All @@ -67,7 +67,7 @@ The payload for this command is the property identifier encoded in the packed un

If an error occurs, the value of the emitted `PROP_LAST_STATUS` will be set accordingly to the status code for the error.

## CMD 3: (OS -> NCP) CMD_PROP_VALUE_SET {#cmd-prop-value-set}
## CMD 3: (AP -> NCP) CMD_PROP_VALUE_SET {#cmd-prop-value-set}

~~~
0 1 2 3
Expand All @@ -86,7 +86,7 @@ The payload for this command is the property identifier encoded in the packed un

If an error occurs, the value of the emitted `PROP_LAST_STATUS` will be set accordingly to the status code for the error.

## CMD 4: (OS -> NCP) CMD_PROP_VALUE_INSERT {#cmd-prop-value-insert}
## CMD 4: (AP -> NCP) CMD_PROP_VALUE_INSERT {#cmd-prop-value-insert}

~~~
0 1 2 3
Expand All @@ -107,7 +107,7 @@ If the type signature of the property specified by `PROP_ID` consists of a singl

If an error occurs, the value of the emitted `PROP_LAST_STATUS` will be set accordingly to the status code for the error.

## CMD 5: (OS -> NCP) CMD_PROP_VALUE_REMOVE {#cmd-prop-value-remove}
## CMD 5: (AP -> NCP) CMD_PROP_VALUE_REMOVE {#cmd-prop-value-remove}

~~~
0 1 2 3
Expand All @@ -130,7 +130,7 @@ If the type signature of the property specified by `PROP_ID` consists of a singl

If an error occurs, the value of the emitted `PROP_LAST_STATUS` will be set accordingly to the status code for the error.

## CMD 6: (NCP -> OS) CMD_PROP_VALUE_IS {#cmd-prop-value-is}
## CMD 6: (NCP -> AP) CMD_PROP_VALUE_IS {#cmd-prop-value-is}

~~~
0 1 2 3
Expand All @@ -143,11 +143,11 @@ If an error occurs, the value of the emitted `PROP_LAST_STATUS` will be set acco
~~~
Figure: Structure of CMD_PROP_VALUE_SET

Property value notification. This command can be sent by the NCP in response to a previous command from the OS, or it can be sent by the NCP in an unsolicited fashion to notify the OS of various state changes asynchronously.
Property value notification. This command can be sent by the NCP in response to a previous command from the AP, or it can be sent by the NCP in an unsolicited fashion to notify the AP of various state changes asynchronously.

The payload for this command is the property identifier encoded in the packed unsigned integer format described in (#packed-unsigned-integer), followed by the current value of the given property.

## CMD 7: (NCP -> OS) CMD_PROP_VALUE_INSERTED {#cmd-prop-value-inserted}
## CMD 7: (NCP -> AP) CMD_PROP_VALUE_INSERTED {#cmd-prop-value-inserted}

~~~
0 1
Expand All @@ -162,15 +162,15 @@ The payload for this command is the property identifier encoded in the packed un
~~~
Figure: Structure of CMD_PROP_VALUE_INSERTED

Property value insertion notification. This command can be sent by the NCP in response to the `CMD_PROP_VALUE_INSERT` command, or it can be sent by the NCP in an unsolicited fashion to notify the OS of various state changes asynchronously.
Property value insertion notification. This command can be sent by the NCP in response to the `CMD_PROP_VALUE_INSERT` command, or it can be sent by the NCP in an unsolicited fashion to notify the AP of various state changes asynchronously.

The payload for this command is the property identifier encoded in the packed unsigned integer format described in (#packed-unsigned-integer), followed by the value that was inserted into the given property.

If the type signature of the property specified by `PROP_ID` consists of a single structure enclosed by an array (`A(t(...))`), then the contents of `VALUE` MUST contain the contents of the structure (`...`) rather than the serialization of the whole item (`t(...)`). Specifically, the length of the structure MUST NOT be prepended to `VALUE`. This helps to eliminate redundant data.

The resulting order of items in the list is defined by the given property.

## CMD 8: (NCP -> OS) CMD_PROP_VALUE_REMOVED {#cmd-prop-value-removed}
## CMD 8: (NCP -> AP) CMD_PROP_VALUE_REMOVED {#cmd-prop-value-removed}

~~~
0 1
Expand All @@ -185,7 +185,7 @@ The resulting order of items in the list is defined by the given property.
~~~
Figure: Structure of CMD_PROP_VALUE_REMOVED

Property value removal notification command. This command can be sent by the NCP in response to the `CMD_PROP_VALUE_REMOVE` command, or it can be sent by the NCP in an unsolicited fashion to notify the OS of various state changes asynchronously.
Property value removal notification command. This command can be sent by the NCP in response to the `CMD_PROP_VALUE_REMOVE` command, or it can be sent by the NCP in an unsolicited fashion to notify the AP of various state changes asynchronously.

Note that this command operates *by value*, not by index!

Expand All @@ -195,7 +195,7 @@ If the type signature of the property specified by `PROP_ID` consists of a singl

The resulting order of items in the list is defined by the given property.

## CMD 18: (OS -> NCP) CMD_PEEK {#cmd-peek}
## CMD 18: (AP -> NCP) CMD_PEEK {#cmd-peek}

~~~
0 1 2 3
Expand All @@ -209,7 +209,7 @@ The resulting order of items in the list is defined by the given property.
Figure: Structure of CMD_PEEK


This command allows the NCP to fetch values from the RAM of the NCP for debugging purposes. Upon success, `CMD_PEEK_RET` is sent from the NCP to the OS. Upon failure, `PROP_LAST_STATUS` is emitted with the appropriate error indication.
This command allows the NCP to fetch values from the RAM of the NCP for debugging purposes. Upon success, `CMD_PEEK_RET` is sent from the NCP to the AP. Upon failure, `PROP_LAST_STATUS` is emitted with the appropriate error indication.

Due to the low-level nature of this command, certain error conditions may induce the NCP to reset.

Expand All @@ -219,7 +219,7 @@ The implementation of this command has security implications. See (#security-con

This command requires the capability `CAP_PEEK_POKE` to be present.

## CMD 19: (NCP -> OS) CMD_PEEK_RET {#cmd-peek-ret}
## CMD 19: (NCP -> AP) CMD_PEEK_RET {#cmd-peek-ret}


~~~
Expand All @@ -240,7 +240,7 @@ This command contains the contents of memory that was requested by a previous ca

This command requires the capability `CAP_PEEK_POKE` to be present.

## CMD 20: (OS -> NCP) CMD_POKE {#cmd-poke}
## CMD 20: (AP -> NCP) CMD_POKE {#cmd-poke}

~~~
0 1 2 3
Expand All @@ -263,7 +263,7 @@ The implementation of this command has security implications. See (#security-con

This command requires the capability `CAP_PEEK_POKE` to be present.

## CMD 21: (OS -> NCP) CMD_PROP_VALUE_MULTI_GET {#cmd-prop-value-multi-get}
## CMD 21: (AP -> NCP) CMD_PROP_VALUE_MULTI_GET {#cmd-prop-value-multi-get}

* Required Capability: `CAP_CMD_MULTI`

Expand All @@ -283,13 +283,13 @@ This command requires the capability `CAP_PEEK_POKE` to be present.
~~~
Figure: Structure of CMD_PROP_VALUE_MULTI_GET

Fetch the value of multiple properties in one command. Arguments are a list of property IDs. If all properties are fetched successfully, a `CMD_PROP_VALUES_ARE` command is sent back to the OS containing the property identifier and value of each fetched property. The order of the results in `CMD_PROP_VALUES_ARE` match the order of properties given in `CMD_PROP_VALUE_GET`.
Fetch the value of multiple properties in one command. Arguments are a list of property IDs. If all properties are fetched successfully, a `CMD_PROP_VALUES_ARE` command is sent back to the AP containing the property identifier and value of each fetched property. The order of the results in `CMD_PROP_VALUES_ARE` match the order of properties given in `CMD_PROP_VALUE_GET`.

Errors fetching individual properties are reflected as indicating a change to `PROP_LAST_STATUS` for that property's place.

Not all properties can be fetched using this method. As a general rule of thumb, any property that blocks when getting will fail for that individual property with `STATUS_INVALID_COMMAND_FOR_PROP`.

## CMD 22: (OS -> NCP) CMD_PROP_VALUE_MULTI_SET {#cmd-prop-value-multi-set}
## CMD 22: (AP -> NCP) CMD_PROP_VALUE_MULTI_SET {#cmd-prop-value-multi-set}

* Required Capability: `CAP_CMD_MULTI`

Expand Down Expand Up @@ -341,7 +341,7 @@ Not all properties can be set using this method. As a general rule of
thumb, any property that blocks when setting will fail for that
individual property with `STATUS_INVALID_COMMAND_FOR_PROP`.

## CMD 23: (NCP -> OS) CMD_PROP_VALUES_ARE {#cmd-prop-values-are}
## CMD 23: (NCP -> AP) CMD_PROP_VALUES_ARE {#cmd-prop-values-are}

* Required Capability: `CAP_CMD_MULTI`

Expand Down

0 comments on commit 4e3dbd4

Please sign in to comment.