TI Wi-SUN FAN NWP Interface Guide¶
Introduction¶
TI Wi-SUN FAN Network Processor (NWP) mode uses Spinel Host Control Protocol as defined in the Spinel Host-Controller Protocol. The Spinel interface specifies a generic host processor (HOST) to Network co-processor (NCP) interface for networking protocols over UART. (The specification also illustrates the use of Spinel interface for THREAD technology.)
TI Wi-SUN FAN NWP interface uses the generic SPINEL interface and extend its use for TI Wi-SUN FAN Technology. This document specifies the changes to the SPINEL specification for TI Wi-SUN FAN technology. For specifics, see the chapter on TI Wi-SUN FAN NWP vs. Spinel.
TI-WISUN FAN solution supports the SPINEL interface over UART interface (no SPI).
Clone the Repository¶
The repository can be cloned directly from github. (Link: TI Wi-SUN FAN pySpinel GitHub repo.) Alternatively, a script in the SDK can be used for automatic setup.
Run Automatic Setup in Windows¶
Within the tools folder of the SDK, there is a file called setup_pyspinel.bat.
Running this file will automatically clone and setup the TI git repository that
contains the NWP python files for your use.
- Open the SDK and navigate to the tools folder
<SDK_INSTALL_DIR>\\tools. - Run the file called
setup_pyspinel.batto setup the TI git repo. Click on the file to start running it, and the repository will be setup inside of the tools folder in your SDK.
Run Automatic Setup in Linux¶
Within the tools folder of the SDK, there is a file called setup_pyspinel.sh.
Running this file will automatically clone and setup the TI git repository that
contains the NWP python files for your use.
Open the SDK and navigate to the tools folder
<SDK_INSTALL_DIR>\\tools.Run the file called
setup_pyspinel.batto setup the TI git repo. Run the following command in a terminal to ensure that the execute permission is set correctly on the script:chmod +x setup_pyspinel.sh
Then run the script, and the repository will be automatically setup and cloned into your SDK.
./setup_pyspinel.sh
Packet Format¶
A detailed specification of SPINEL implementation can be found at the Spinel Host-Controller Protocol web page. A brief overview is provided here for reference.
The SPINEL interface encodes command and properties into a HDLC-Lite format to be transferred over UART:
Figure 18. UART packet format
Spinel Header¶
The spinel header has the following fields:
| Field | Length | Value |
|---|---|---|
| Flag (FLG) | 2 bits | Always set to 0x2. |
| Network Line Identifier (NLI) | 2 bits | Always set to 00. |
| Transaction Identifier (TID) | 4 bits | Transaction ID*. |
* For unsolicited and asynchronous messages, TID is set to 0. Other TIDs can be used for matching request from Host to response from NCP. It is recommended to keep only one TID active at any time with the NCP.
Spinel Command¶
The following commands are supported in TI Wi-SUN NWP. The direction column
specifies which layer (HOST or NCP) can issue a command. All commands are used
in a request/response manner. (In addition, CMD_PROP_VALUE_SET and
CMD_PROP_VALUE_IS can be used by Host and NCP to send asynchronous messages
from each other respectively.)
| Nr | Spinel Command | Direction |
|---|---|---|
| CDM 0 | CMD_NOOP |
Host->NCP |
| CMD 1 | CMD_RESET |
Host->NCP |
| CMD 2 | CMD_PROP_VALUE_GET |
Host->NCP |
| CMD 3 | CMD_PROP_VALUE_SET |
Host->NCP |
| CMD 4 | CMD_PROP_VALUE_INSERT |
Host->NCP |
| CMD 5 | CMD_PROP_VALUE_REMOVE |
Host->NCP |
| CMD 6 | CMD_PROP_VALUE_IS |
NCP->Host |
| CMD 7 | CMD_PROP_VALUE_INSERTED |
NCP->Host |
| CMD 8 | CMD_PROP_VALUE_REMOVED |
NCP->Host |
Command Payload¶
The command payload is encoded based on specified encoding format as defined in the Spinel Host-Controller Protocol. The encoded format is assumed to be known to both Host and NCP and hence is not transmitted over UART.
Spinel Properties¶
Properties are used to exchange information between the Host and the NCP. They are encoded either as basic types (uint16, EUI-64, IPv6 address etc..) or as Array or structure of basic types. The basic types supported as defined in SPINEL specification document is presented in the Spinel Host-Controller Protocol chapter 3.1 Primitive Types.
Each Property has the following specified:
- Property Id - To uniquely identify the property (encoded as a packed integer format that enables ID with value < 127 to be sent as 1 byte while using more bytes for higher values)
- Type - Read only, Write only, read-write, Insertable (adding value to an array of parameters, e.g., adding EUI-64 to the list of MAC address to be filtered)
- Encoding - Specifies how the property value will be encoded
- Required Capability - Supported by Router, Border Router or Any type of devices
- Description - Specifies what the property represents and how it can be used.
TI Wi-SUN FAN NWP Properties¶
The table lists all available properties in TI Wi-SUN FAN NWP.
| Property Category | Property (ID) | Description | Role | Encoding | Type |
|---|---|---|---|---|---|
| CORE | PROP_PROTOCOL_VERSION (1) | Major and Minor version of the protocol. Only supported value = 1.0. | BR and RN | “ii” | Read-only |
| PROP_NCP_VERSION (2) | Describes the firmware currently running on the NCP. STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME Example: o “TIWISUNFAN/1.0d26-25-gb684c7f; DEBUG; May 9 2016 18:22:04” |
BR and RN | “U” | Read-only | |
| PROP_INTERFACE_TYPE (3) | Identifies the network protocol for the NCP . Will always return 4 (Wi-SUN FAN). | BR and RN | “i” | Read-only | |
| PROP_HWADDR (8) | Eight byte HW Address (EUI-64). | BR and RN | “E” | Read-only | |
| PHY generic | PROP_PHY_CCA_THRESHOLD (36) | Value will be rounded to the nearest supported value. | BR and RN | “c” (int8) | Read-write SysConfig or NWP. |
| PROP_PHY_TX_POWER (37) | PHY transmit power. | BR and RN | “c” | Read-write SysConfig or NWP. | |
| PHY TI Wi-SUN specific | PROP_PHY_REGION (80) | 1 - NA, 2 - JP, 3 - EU, 7 - BZ. | BR and RN | “C” (uint8) | Read-only |
| PROP_PHY_MODE_ID (81) | Supported values: 1-7. (If a PHY Mode Id is not supported for the chosen Region a PROP_LAST_STATUS will be thrown with INVALID_PARAMETER) | BR and RN | “C” (uint8) | Read-only | |
| PROP_PHY_UNICAST_CHANNEL_LIST (82) | Bit mask of max size 17 bytes (representing 129 channels). Each bit represents if the channel is present or not. | BR and RN | “D” | Read-write SysConfig or NWP. | |
| PROP_PHY_BROADCAST_CHANNEL_LIST (83) | Bit mask of max size 17 bytes (representing 129 channels). Each bit represents if the channel is present or not. | BR | “D” | Read-write SysConfig or NWP. | |
| PROP_PHY_ASYNC_CHANNEL_LIST (84) | Bit mask of max size 17 bytes (representing 129 channels). Each bit represents if the channel is present or not. | BR and RN | “D” | Read-write SysConfig or NWP. | |
| PROP_PHY_CH_SPACING (5376) | Channel spacing in MHz. (If a channel spacing is not supported for the chosen Region/PhyModeId, a PROP_LAST_STATUS will be thrown with INVALID_PARAMETER) | BR and RN | “S” (uint6) | Read-only | |
| PROP_PHY_CHO_CENTER_FREQ (5377) | Channel 0 center frequency structure with value {Ch0-MHz, Ch0-KHz}. E.g. a ch0 center frequency of 902.2 MHz will be encoded as a structure of {902,200}. | BR and RN | “t(SS)” | Read-only | |
| MAC generic | PROP_MAC_15_4_PANID (54) | MAC PAN ID of the device. For Wi-SUN networks, this needs to be set only on the BR. Router devices will select network based on Network Name. | BR and RN | “S” | Read-write SysConfig or NWP. |
| MAC TI Wi-SUN specific | PROP_MAC_UC_DWELL_INTERVAL (5462) | Unicast dwell interval (0 - 255 ms). | BR and RN | “C” | Read-write SysConfig or NWP. |
| PROP_MAC_BC_DWELL_INTERVAL (5463) | Broadcast dwell interval (0 - 255 ms). | BR | “C” | Read-write SysConfig or NWP. | |
| PROP_MAC_BC_INTERVAL (5464) | Broadcast interval (0 - 0xFFFFFF ms). | BR | “L” | Read-write SysConfig or NWP. | |
| PROP_MAC_UC_CHANNEL_FUNCTION (5465) | 0 - Fixed, 1 - Hopping based on DH1CF (other values are reserved). | BR and RN | “C” | Read-write SysConfig or NWP. | |
| PROP_MAC_BC_CHANNEL_FUNCTION (5466) | 0 - Fixed, 1 - Hopping based on DH1CF (other values are reserved). | BR | “C” | Read-write SysConfig or NWP. | |
| PROP_MAC_MAC_FILTER_LIST (5467) | When read, it provides an array of EUI Address. CMD_VALUE_INSERTED return value of EUI-64 inserted or “all zeros” to inform that operation failed. | BR and RN | A(E) | Read-write NWP only. | |
| PROP_MAC_FILTER_MODE (5468) | 0 - Disabled, 1 - Whitelist, 2 - Blacklist | BR and RN | “C” | Read-write NWP only. | |
| NET generic | PROP_NET_IF_UP (65) | Network interface up/down status. Non-zero (set to 1) indicates up, zero indicates down. | BR and RN | “b” | Read-write NWP only. |
| PROP_NET_STACK_UP (66) | Wi-SUN stack operational status. Non-zero (set to 1) indicates up, zero indicates down. | BR and RN | “b” | Read-write NWP only. | |
| PROP_NET_ROLE (67) | Indicates router or border router role. 0 - Border Router, 1 - Router | BR and RN | “C” | Read-only | |
| PROP_NET_NETWORK_NAME (68) | UTF8 encoded string. Max size 32 bytes. | BR and RN | “U” | Read-write SysConfig or NWP. | |
| NET TI Wi-SUN specific | PROP_NET_STATE (91) | Router device join state:
|
BR and RN | “C” | Read-only |
| IPv6 | PROP_IPV6_ADDRESS_TABLE (99) | Array of structures containing:
|
BR and RN | “A(t (6CLLC)” | Read-only |
| Stream | PROP_STREAM_NET (114) | Received IPv6 Packet or IPv6 packet to be sent. Currently, only support for ping command. See TI Wi-SUN FAN pyspinel host scripts to test this command. | BR and RN | “dD” | Read-write NWP only. |
Example Sessions¶
Refer to README.md in the TI Wi-SUN FAN pySpinel GitHub repo for a walk-through of commands provided to be run on the host. These pyspinel commands get translated to spinel commands and properties described in this document, to facilitate host NWP communication.
Init Sequence¶
The initialization sequence with Wi-SUN stack NCP is referenced from the “Attaching to a network” sequence (Section C.2) of the Spinel Host-Controller Protocol . We make the assumption that the NCP is not currently associated with a network. (If there is a need to clear up network information in the NV area, refer to 2. Erasing the NV)
1. NCP Initialization¶
Check the protocol version to see whether it’s supported. Expected return is 1.0.
CMD_VALUE_GET:PROP_PROTOCOL_VERSION CMD_VALUE_IS:PROP_PROTOCOL_VERSION
Check the NCP version to see if a firmware update may be necessary:
CMD_VALUE_GET:PROP_NCP_VERSION CMD_VALUE_IS:PROP_NCP_VERSION
Check interface type to make sure that it is what we expect. Expected return is 4.
CMD_VALUE_GET:PROP_INTERFACE_TYPE CMD_VALUE_IS:PROP_INTERFACE_TYPE
Read the HW address of the device:
CMD_VALUE_GET:PROP_HWADDR CMD_VALUE_IS:PROP_HWADDR
2. Erasing the NV¶
NV is used to store security related information like different keys and network
information. If there is a need to clear up the NV before the device joins the
network for a fresh start, CMD_NV_ERASE from host to NCP can be issued.
Note that CMD_NV_ERASE will only clear the NV content and not the
router/border router image. To achieve this, do a mass erase of internal flash
then flash the image again.
3. Setting the network properties¶
Note
For TI Wi-SUN stacks running as NCP, SysConfig can be used to set certain network parameters before compiling the router and Border router images. Some properties, as shown in the sequence below, can be set to a different value through NWP interface if needed, before bringing up the Wi-SUN stack interface and Wi-SUN stack up. Some properties can only be set through NWP interface.
If a different configuration than given in SysConfig is used, network properties can be set with the following commands:
CMD_VALUE_GET:PROP_XYZ
CMD_VALUE_SET:PROP_XYZ
CMD_VALUE_IS:PROP_XYZ:TRUE
Where PROP_XYZ can be replaced with one of the properties in
Table 2.. Please note that properties need to be set before
the network interface is started (PROP_NET_IF_UP).
| Property Category | Property | Configuration mode | Role |
|---|---|---|---|
| PHY - generic | PROP_PHY_CCA_THRESHOLD | SysConfig or NWP interface during initialization | BR and RN |
| PROP_PHY_TX_POWER | SysConfig or NWP interface during initialization | BR and RN | |
| PHY - Wi-SUN specific | PROP_PHY_UNICAST_CHANNEL_LIST | SysConfig or NWP interface during initialization | BR and RN |
| PROP_PHY_BROADCAST_CHANNEL_LIST | SysConfig or NWP interface during initialization | BR | |
| PROP_PHY_ASYNC_CHANNEL_LIST | SysConfig or NWP interface during initialization | BR and RN | |
| MAC - generic | PROP_MAC_15_4_PANID | SysConfig or NWP interface during initialization | BR |
| MAC - Wi-SUN specific | PROP_MAC_UC_DWELL_INTERVAL | SysConfig or NWP interface during initialization | BR and RN |
| PROP_MAC_BC_DWELL_INTERVAL | SysConfig or NWP interface during initialization | BR | |
| PROP_MAC_BC_INTERVAL | SysConfig or NWP interface during initialization | BR | |
| PROP_MAC_UC_CHANNEL_FUNCTION | SysConfig or NWP interface during initialization | BR and RN | |
| PROP_MAC_BC_CHANNEL_FUNCTION | SysConfig or NWP interface during initialization | BR | |
| PROP_MAC_MAC_FILTER_LIST | NWP interface only | BR and RN | |
| PROP_MAC_FILTER_MODE | NWP interface only | BR and RN | |
| Net | PROP_NET_NETWORK_NAME | SysConfig or NWP interface during initialization | BR and RN |
4. Bring the Wi-SUN (network) interface up¶
This process is common for BR and RN and must be done on all devices.
CMD_VALUE_SET:PROP_NET_IF_UP:TRUE
CMD_VALUE_IS:PROP_NET_IF_UP:TRUE
5. Bring the Wi-SUN stack up¶
This process is common for BR and RN and must be done on all devices.
CMD_VALUE_SET:PROP_NET_STACK_UP:TRUE
CMD_VALUE_IS:PROP_NET_STACK_UP:TRUE
On a RN device, getting an immediate response of True means the NCP received the
command and is in the process of connecting to the border router. You can follow
the PROP_NET_STATE value to get an indication of the connection process.
6. Accessing the globally unique DHCP address and link local IPv6 address¶
Prompt the NCP to send information of the IPv6 addresses to the host. Subsequently the pySpinel host script parses the information and displays the same.
More information about this command is found in the README.md in the TI Wi-SUN FAN pySpinel GitHub repo.
CMD_VALUE_SET:PROP_IPV6_ADDRESS_TABLE:TRUE
7. Pinging a device in the network¶
Once the network is established we can send a ping.
CMD_VALUE_SET:PROP_STREAM_NET
CMD_VALUE_IS:PROP_STREAM_NET:TRUE
CMD_VALUE_IS:PROP_STREAM_NET
If the received command has the fail status, the device is not yet ready.
TI Wi-SUN FAN NWP vs. Spinel¶
The specification is based on the Spinel Host-Controller Protocol with the following changes.
Notations used:
- Normative, implies that the specification is used as such
- Modified, implies section has been modifies for use in TI Wi-SUN FAN
- Not relevant, implies that the section is not relevant for TI Wi-SUN FAN
- New, newly introduced for TI Wi-SUN FAN
| Section No | Section Name | Status |
|---|---|---|
| 1 | Introduction | Normative |
| 2 | Frame Format | Normative |
| 3 | Data Packing | Normative |
| 4 | Commands | Modified |
| 4.1 | CMD_NOOP |
Normative |
| 4.2 | CMD_RESET |
Normative |
| 4.3 | CMD_PROP_VALUE_GET |
Normative |
| 4.4 | CMD_PROP_VALUE_SET |
Normative |
| 4.5 | CMD_PROP_VALUE_INSERT |
Normative |
| 4.6 | CMD_PROP_VALUE_REMOVE |
Normative |
| 4.7 | CMD_PROP_VALUE_IS |
Normative |
| 4.8 | CMD_PROP_VALUE_INSERTED |
Normative |
| 4.9 | CMD_PROP_VALUE_REMOVED |
Normative |
CMD_NV_ERASE |
New | |
| 4.10-4.15 | CMD 18-23 | Not relevant |
| 5 | Properties | Modified |
| 5.1 | Property Methods | Normative |
| 5.2 | Property Types | Normative |
| 5.3 | Property Numbering | Modified |
| 5.4 | Property Sections | Modified |
| 5.5-5.11 | Properties | Modified |
| 6 | Status Codes | Modified |
| 7-13 | Technology: Thread - Security Considerations | Not relevant |
| Appendix A | Framing Protocol | Normative |
| Appendix B | Test Vectors | Modified |
| B.1 | Test Vector: Packet Unsigned Integer | Normative |
| B.2 | Test Vector: Reset Command | Normative |
| B.3 | Test Vector: Reset Notification | Normative |
| B.4-B.12 | Other Test Vectors | Not relevant |
| Appendix C | Example Sessions | Not relevant |
| Appendix D | Glossary | Normative |
| Appendix E | Acknowledgments | Normative |
Property Numbering¶
The property numbering Strategy used is based on current defined property numbering as per the Spinel Host-Controller Protocol. Properties that are common with Wi-SUN are reused with the same numbering. Additional properties specific to Wi-SUN or Modified to suit needs to TI Wi-SUN FAN solution have been assigned numbers from the Technology Specific section. This means that all Thread technology specific parameters defined in specification will not be valid for Wi-SUN and will be replaced to those corresponding to Wi-SUN FAN.
Property Sections¶
All core property sections are retained and the technology specific section are reallocated to Wi-SUN as defined below. The Primary range is allocated to more frequently needed parameters to save bytes transferred through UART in accordance with the Spinel specification.