Introduction

This workshop is an introduction to the TI Wi-SUN FAN Stack in the SimpleLink™ CC13xx and CC26xx Software Development Kit (SDK). The 4 tasks in this lab session are targeted to be completed within a 2-hour time frame. An intermediate level of knowledge of the C programming language and some experience with embedded software development is needed to be able to complete the tasks.

In task one, you will learn how to set up a Border Router device and how to send commands over the pyspinel interface. In task two, set up a Router Node. In the third task the network is started and the connection is formed. In the fourth task, you learn how to send a ping over the network. The lab will take about one hour and a half to complete.

It is recommended to read the TI Wi-SUN FAN User's Guide alongside this lab for details and further information.

Prerequisites

Hardware

For this lab, you need one board to run the Border Router application. Supported development boards are:

• SimpleLink™ CC1312R7 LaunchPad
• SimpleLink™ CC1352P7-1 LaunchPad

In addition, you need one board to run the Router Node application. Supported development boards are:

• SimpleLink™ CC1312R7 LaunchPad
• SimpleLink™ CC1352P7-1 LaunchPad

You will also need a computer to act as the host to the network processor. You can use Windows or Linux. You will need git on your computer.

Software

• Python v.3.6.8 or later (including pip)
• CCS installed with support for CC13xx/CC26xx devices.
• SimpleLink™ CC13xx/CC26xx SDK
• TI Wi-SUN FAN pySpinel GitHub repo

Recommended reading

• TI Wi-SUN FAN User's Guide
• TI Wi-SUN FAN NWP Guide

Getting started – Desktop

Install the SDK

• CCS Resource Explorer
• Installer

Open Resource Explorer via View → Resource Explorer and find the SDK you want to install.

On the right side, you will see a download icon. Click this to install the SDK and all its dependencies.

1. Download the off line installer from the SDK links above under Prerequisites

2. Run the SimpleLink CC13XX-CC26XX SDK installer: simplelink_cc13xx_cc26xx_sdk_x_xx_xx_xx.exe. These instructions assume you have installed to the default directory: C:\ti\

Install Python 3.x

Python 3.x is needed for the network processor interface. Python can be installed directly from www.python.org. If asked, make sure to include pip with the installation.

Install the TI Wi-SUN FAN pySpinel GitHub Repo

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.

1. Open the SDK and navigate to the tools folder <SDK_INSTALL_DIR>\tools\ti_wisunfan.

   

2. 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.

3. After running the .bat file, a folder pyspinel_repo is created. In this folder, another folder is created for the actual repo: ti-wisunfan-pyspinel. The release tag corresponding to your SDK release is already checked out.

4. Depending on your Python setup, running the .bat file may give you a pip error:

   If this happens, follow the recommendation to update pip and then install the requirements.

   Select text

   $ pip install --upgrade pip
   

   Then install the requirements:

   Select text

   $ pip install -r requirements.txt
   

Wi-SUN Network

The Wi-SUN FAN mesh network consists of two types of logical devices: The Border Router (BR) device and the Router Node (RN) devices.

• Each PAN contains a BR providing WAN connectivity to the PAN. The BR maintains source routing tables for all nodes within its PAN, provides node authentication and key management services, and disseminates PAN wide information such as broadcast schedules.
• In addition there is one or more RNs, which provide upward and downward packet forwarding (within a PAN). An RN also provides services for relaying security and address management protocols.

Task 1 – Run the Border Router Project

In the first task we will set up a Border Router device. This device will be the root of the network.

Import in Code Composer Studio

Open Code Composer Studio and import the BR project:

• In CCS, open Project → Import CCS Projects...

  

• Navigate to the ns_br folder for your development board and press Select Folder. The path is: <SDK_INSTALL_DIR>\examples\rtos\<DEVELOPMENT_BOARD>\ti_wisunfan\ns_br

• Select the discovered project and press Finish.

  

• The project will appear in your Project Explorer window as shown below.

  

Connect the LaunchPad

Start by making sure your kit is assembled, turned on, and connected to the PC via the USB cable.

When the LaunchPad is connected, the Windows Device Manager (Start → Control Panel → Device Manager, or Win+X, M on Windows 10) will show you the following devices connected:

The Application/User UART serial port is used for application output in this example.

If you are using a Linux computer, use the dmesg | grep tty command to get a chronological list of all devices. The second to last is the one we want to use (e.g. /dev/ttyACM0).

Note down the COM or tty number, we will use it soon!

Build the Projects and Flash the Device

1. Build the project by right-clicking on it and selecting Build Project.
   • Alternatively build all projects by pressing Ctrl + B.
2. Program the project by right clicking on it and selecting Debug As → Code Composer Debug Session
3. When the IDE is halted at the main function, terminate debugging session by clicking Ctrl + F2 or the square red stop icon.

Connect the Network Processor Interface

We will use the spinel-cli.py file to control the Border Router device. To run a python script, open a command terminal or similar. Here, git bash is used.

1. Navigate to the location of spinel-cli.py, <SDK_INSTALL_DIR>\tools\ti_wisunfan\pyspinel_repo\ti-wisunfan-pyspinel

   Select text

   $ cd \c\ti\simplelink_cc13xx_cc26xx_sdk_6_10_00_29\tools\ti_wisunfan\pyspinel_repo\ti-wisunfan-pyspinel
   

2. Remember the USB port we found in the Section Connect the LaunchPad? We will use it now. Call the spinel-cli.py with the COM or tty port added as an argument:

   Select text

   $ python spinel-cli.py -u COM4
   spinel-cli >
   

   Select text

   $ python spinel-cli.py -u /dev/ttyACM0
   spinel-cli >
   

  $ python spinel-cli.py -u COM10
  Couldn't open COM10 module 'serial' has no attribute 'Serial'
  Traceback (most recent call last):
    File "spinel-cli.py", line 1839, in <module>
      main()
    File "spinel-cli.py", line 1816, in main
      options.baudrate, options.rtscts)
    File "C:\ti\simplelink_cc13x2_26x2_sdk_5_20_00_52\tools\pyspinel_repo\ti-wisunfan-pyspinel\spinel\stream.py", line 185, in StreamOpen
      return StreamSerial(dev, baudrate, rtscts)
    File "C:\ti\simplelink_cc13x2_26x2_sdk_5_20_00_52\tools\pyspinel_repo\ti-wisunfan-pyspinel\spinel\stream.py", line 55, in __init__
      self.serial = serial.Serial(port=dev,
  AttributeError: module 'serial' has no attribute 'Serial'

  $ python -m pip uninstall serial pyserial

  $ python -m pip install pyserial

  $ python spinel-cli.py -u /dev/ttyACM0
  Couldn’t open dev/ttyACM0 [Errno 13] could not open port dev/ttyACM0: [Errno 13] Permission denied: ‘dev/ttyACM0’
  ...

  $ sudo chmod 666 /dev/ttyACM0

Run Some Commands

Now that we have the network processor interface up and running, we can run some commands. For example, we can check the version of the image running on the LaunchPad:

  spinel-cli > ncpversion
  TIWISUNFAN/1.0.0; RELEASE; Jul  23 2021 13:54:01

Or we can ask for all available command to be displayed using help:

  spinel-cli > help

Task 2 – Run the Router Node Project

In this task we will set up a Router Node to connect with the Border Router. Here we will set up one, but in a real mesh network there will be many of these devices. The steps for programming a launchpad are the same as for the BR project.

Import in Code Composer Studio

Open Code Composer Studio and import the RN project, ns_coap_node. The steps are the same as for the BR project, but the path is different: <SDK_INSTALL_DIR>\examples\rtos\<DEVELOPMENT_BOARD>\ti_wisunfan\ns_coap_node.

When you have imported the project, it will show up in CCS as follows:

Connect the LaunchPad

Connect your second LaunchPad to the laptop via USB. Again, you can check that it appears in Windows Device Manager.

When you have two launchPads connected to your laptop, it's important to make sure the correct one is programmed by CCS when you press the Debug button. If not, you risk that one LaunchPad is never programmed while the other one is overwritten each time you press the debug button. One way to avoid this is to assign a specific LaunchPad to each CCS project. Instructions for this is found here.

Build the Projects and Flash the Device

Build the project, program it and terminate the debug session using the same steps as for the BR device.

Run the Project

The ns_coap_node project is a fully embedded implementation of the Router Node. This means we don't need to connect through the network processor interface. Instead, the CoAP node automatically looks for a Wi-SUN network to join after booting. If it finds a network with matching network parameters it will join it.

You will notice the green LED starts flashing when the CoAP node is running.

To see the connection status of the CoAP node, let's open a UART terminal.

Connect a Terminal Program

To see the serial output from the LaunchPad it is necessary to use a terminal emulator. There are several options. We will use PuTTy.

Set your terminal emulator settings to 115200 baud rate, 8 bit data, 1 stop bit, no parity, and no flow control.

When you press the power button on the LaunchPad (next to the micro USB connector), you will see the following print out in your terminal:

Task 3 – Form the Connection

1. Let's start by starting the network from the Border Router device. We will start by checking the network name and PAN ID:

   Select text

   spinel-cli > networkname
   Wi-SUN Network
   Done
   

   Select text

   spinel-cli > panid
   0xabcd
   Done
   

   You can use these commands to change the network name and PAN ID. However, make sure you change these parameters on the Router Node side as well or it won't be able to connect!

   How to change network name and PAN ID on the CoAP node

   Open SysConfig by double-clicking ti_wisunfan_router_node.syscfg.

   

   Select TI Wi-SUN FAN Stack and open the Network tab. Here you can select the PAN ID and Network name you wish.

   

   Save the .syscfg file, rebuild the project and reprogram the device.

   Don't forget to set the same PAN ID and network name on the BR!

   Select text

   spinel-cli > networkname Best Network
   Best Network
   Done
   spinel-cli > panid
   0xa1a1
   Done
   

2. It's time to start the network. The first command we need is the ifconfig up command which brings up the network interface:

   Select text

   spinel-cli > ifconfig up
   Done
   

3. The second command we need is wisunstack. This command tells you the status of the Wi-SUN FAN network. Call it with the start keyword to start the network.

   Select text

   spinel-cli > wisunstack start
   Done
   spinel-cli > wisunstack
   start
   Done
   

   Join time

   It can take several minutes for the router node to join the network. This is because both the BR and the RN are frequency hopping.

4. From the BR side, we can use the routerstate command to check the join status of this device. For the BR, we expect this to be 5 when the network is operational.

   Select text

    spinel-cli > routerstate
    5
    Successfully joined and operational
    Done
   

   I got a different status...

   If the return status is something other than 5, the network has not yet started. For example if you get a 0 status.

   In most cases this means you forgot to run the ifconfig up or the wisunstack start command. Rerun these and retry!

   We can use connecteddevices to check if any devices are connected yet.

   Select text

    spinel-cli > connecteddevices
    List of Connected Devices currently in routing table:
   
    No nodes currently in routing table.
   

5. After a few minutes the RN will join the network. The green LED will stop flashing. When this happens the RN will print out a message over UART.

   

   On the BR, you can send the connecteddevices command:

   Select text

    spinel-cli > connecteddevices
    List of Connected Devices currently in routing table:
   
    fd00:7283:7e00:0:212:4b00:14f7:d1b5
   
    Done
   

   We have a connection! At this point you can add more RNs to the network, or you can continue with the next task. If you choose to add more routers, you can use the connecteddevices command to get a list of all devices in the network.

   Select text

   spinel-cli > connecteddevices
   List of Connected Devices currently in routing table:
   
   fd00:7283:7e00:0:212:4b00:1ca1:727a
   
   fd00:7283:7e00:0:212:4b00:1ca6:17ea
   
   Done
   

Task 4 – Ping the Router Node

In this task, we will send a ping from the Border Router, to the Router Node.

1. First we need to know the DHCP address of this RN. If we only have one RN in the network, we can use the connecteddevices command on the BR. This will print out the address of all connected devices.

   Select text

    spinel-cli > connecteddevices
    List of Connected Devices currently in routing table:
   
    fd00:7283:7e00:0:212:4b00:14f7:d1b5
   
    Done
   

   If we have multiple RNs in the network, let's use the terminal display on the RN to see it's address. When the RN first connected to the network, it printed it's own address as the CON_STATUS_LOCAL_UP. Here, it's fd00:7283:7e00:0:212:4b00:14f7:d1b5.

   

2. Now we can use the ping command from the BR:

   Select text

   spinel-cli > ping fd00:7283:7e00:0:212:4b00:14f7:d1b5
   56 bytes from fd00:7283:7e00:0:212:4b00:14f7:d1b5: icmp_seq=50089 hlim=64 time=118ms
   

   In the return message you can even see the turnaround time.

3. That's ok.... but maybe there's a command we can use and see the effect on the RN side as well? A good starting point would be to check the pyspinel command documentation. You can find it in the README file in the TI Wi-SUN FAN pySpinel GitHub repo.

  spinel-cli > coap fdde:ad00:beef:0:558:f56b:d688:799 get con led
  CoAP packet received from fe80::212:4b00:10:50d4: type: 2 (Acknowledgement), token len: 0, code: 2.05 (Content), msg_id: 1
  CoAP options: Content-Format (12): b''
  RLED state: Off, GLED state: On

  spinel-cli > coap fdde:ad00:beef:0:558:f56b:d688:799 post con led --led_state r 1
  CoAP packet received from fe80::212:4b00:10:50d4: type: 2 (Acknowledgement), token len: 0, code: 2.04 (Changed), msg_id: 2
  CoAP options: Content-Format (12): b''
  No CoAP payload

  spinel-cli > coap fdde:ad00:beef:0:558:f56b:d688:799 get non led
  CoAP packet received from fe80::212:4b00:10:50d4: type: 2 (Acknowledgement), token len: 0, code: 2.04 (Changed), msg_id: 2
  CoAP options: Content-Format (12): b''
  No CoAP payload

  spinel-cli > coap fd00:7283:7e00:0:212:4b00:14f7:d1b5 post con led --led_state r 1
  spinel-cli >
  CoAP packet received from fd00:7283:7e00:0:212:4b00:14f7:d1b5: type: 2 (Acknowledgement), token len: 0, code: 2.04 (Changed), msg_id: 0
  CoAP options: Content-Format (12): b''
  No CoAP payload

Bonus Task – Set up a Sniffer

A sniffer log can be very useful for debugging, or if you're just curious about what's going over the air. In short, a sniffer will observe all the packets going back and forth in the network.

In this task we will set up a sniffer to keep track of the network. You will need one additional LaunchPad. The following are supported:

• CC1312R1 LaunchPad
• CC1352P1 LaunchPad
• CC1352R1 LaunchPad

We will keep the Border Router and Router Node(s) running, but some configuration is required.

To set up the sniffer, follow the steps in the TI Wi-SUN FAN User's Guide → Debugging → Packet Sniffer.

Pay attention to the final section, Application Setup. Here you can find the specific application changes needed.

References

TI Wi-SUN FAN User's Guide

TI Wi-SUN FAN NWP Guide

TI Wi-SUN FAN pySpinel GitHub repo

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.