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.bat to 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.bat to 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 22. 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. Returns stack name, version and build. Other info and build time. "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: 1: Scanning for Suitable Network, 2: Authentication In Progress, 3: Waiting for PAN Configuration 4: Routing layer - Parent Selection In Progress, Acquiring GUA IPv6 address through DHCPv6 5: Successfully Joined the Border router	BR and RN	“C”	Read-only
IPv6	PROP_DODAG_ROUTE_DEST (95)	In order to get the path of a destination from the border router, a route destination IPv6 address must exist.	BR	“6”	Read-write NWP only.
	PROP_DODAG_ROUTE (96)	Can be used by a border router host to read the entire path to a specific device in the network. When using with CMD_VALUE_GET, specify the path cost as 0 and specify the target device IP address. Return: Array of IPv6 addresses that serve as the path to the device and the total path cost. (First address is the BR address.) If no DODAG route exists, returns only the target device address and path cost of 0.	BR	“SA(6)”	Read-only
	PROP_IPV6_ADDRESS_TABLE (99)	Array of structures containing: “6”: IPv6 Address “C”: Network Prefix Length “L”: Valid Lifetime “L”: Preferred Lifetime “C”: Flags	BR and RN	“A(t (6CLLC)”	Read-only
	PROP_NUM_CONNECTED_DEVICES (101)	Returns the number of devices in the RPL tree associated with the BR.	BR	“S”	Read-only
	PROP_CONNECTED_DEVICES (102)	Returns a list of connected devices. See description below.	BR	“CA(6)”	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.

PROP_CONNECTED_DEVICES¶

To get the list of connected devices the HOST can issue a GET command to this property.

HOST:  CMD_VALUE_GET:PROP_CONNECTED_DEVICES
NCP: CMD_VALUE_IS:PROP_CONNECTED_DEVICES:[BLOCK_ID IPv6Address1 IPv6Address2 IPv6Address1 ..TargetIPv6Address]

In order to limit the max length of NCP messages, the BLOCK ID is used to keep tabs of the addresses. (Each IPv6 address is 16 bytes.)

BLOCK ID has two possible values (MSB):

0: Last block
1: Not last block. (Resend the PROP_CONNECTED_DEVICES command to get the next block.)

../_images/prop_connected_devices_example.png

Figure 23. Request blocks until last block has been sent.¶

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 4.. Please note that properties need to be set before the network interface is started (PROP_NET_IF_UP).

Table 4. Properties that can be set with `CMD_VALUE_SET`.¶
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.