Choosing a hardware toolchain for a cloud connected sensor (microcontroller based)

I want to connect wireless sensor nodes to the IBM IoT Watson cloud infrastructure IBM Bluemix based on the TI Design SimpleLink™ Sub-1 GHz Sensor to Cloud Gateway Reference Design for TI-RTOS Systems. The reference document is TI Designs:TIDC-01002 Sub-1GHz Embedded Sensor to Cloud Industrial Internet of Things(IoT) Gateway Reference Design. Related source code can be cloned from the compagnion repo. I use Linux Mint 19.2 Tina and Code Composer Studio 9.2.0 (CCS).

The software architecture described in the TI Design is now part of the official SimpleLink CC13x2 26x2 SDK (3.40.00.02) documentation and I will follow the recommended learning path of the SimpleLink Academy (3.30.03.00). However the TI Design has more details and is still a useful resource for understanding the TI 15.4 example projects. More importantly, part of the software - the gateway project - is not available in the SDK and must be cloned from a git repository hosted by TI.

1. Introduction

The proposed architecture for connecting wireless sensors to the Internet is based on the following components:

one or more sensors
a collector that manages and interacts with sensors
a coprocessor that combines the collector function with a host communication interface
a gateway that relays data between an internet-based application like a webserver
a cloud service that allows for two way commmunication between an internet user and a set of sensors/actuators

The reference document [r31], called TI Design in this memo, contains a detailed description of each component.

So why this memo when there is a comprehensive document by TI ?

The TI Design

tries to minimize the T.T.H.W ( Time To Hello World) by flashing prebuilt binaries
covers two alternative cloud services, Bluemix (IBM) and (AWS) Amazon, including details on how to create a cloud-enabled account
presents alternative apps for Android and iOS to configure the gateway part

Whereas in this memo, I

proceed in small steps with verifiable results in order to gain at least a superficial understanding of each component
focus on IBM bluemix without going into details, which are the subject of a previous memo
do not mention any apps, since I could not get them to work as advertised (on Android)
compile everything from source, rather than using prebuilt binaries
adapt my host development environment to a workflow where several LaunchPads are connected to the host computer simultaneously
summarize a couple of speed bumpers which increased the T.T.H.W

Again, the T.T.H.W. is still unknown because I am currently unable to build the gateway application from source [e2e3].

2. Preparation

I summarize a couple of steps that helped me to streamline the development and testing workflow. I also present a couple of error messages, some of which I am unable to reproduce, that occurred when I tried to flash a binary to the MCU during a CCS debug session. I believe that having seen the error message in this memo up front, it becomes less frightening when it shows up in the IDE.

2.1. The companion repo

While one part of the source code of the TI Design is now in the official SKD [r12], the other part involving the gateway and the cloud/web front ent must be obtained from the tidc01003 git repo hosted by TI. Since I am likely to make changes to the TI repo, it is useful to add it to the compagnion repo of this memo as a git submodule:

$ git submodule add https://git.ti.com/git/tidc01002/tidc01002.git
$ git submodule update --init
$ git remote rename origin ti
$ git remote add origin git@github.com:vittali/vittali.ch-5-TIR-1002-tidc01002.git

I can then clone the submodule:

$ git clone --recurse-submodules https://git.ti.com/git/tidc01002/tidc01002.git

I then need to checkout a branch before I make changes:

$ cd tidc01002
$ git checkout master
<make changes>
$ git add .
$ git commit -m"my changes"
$ git push origin master

2.2. Disambiguating LaunchPads

Since at least two LaunchPads are connected simultaneously, I must ensure that:

when programming a LaunchPad with CCS, the flash utility knows which LaunchPad is supposed to receive the binary,
when testing the application components, the user knows which serial port corresponds to each LaunchPad in order to be able to open a terminal session.

2.2.1. Setting a unique serial number for each LaunchPad.

The first step is to give each LaunchPad^[1] a unique serial number.

I first label the LaunchPad board (see hardware setup) with the desired unique serial number (a non negative integer). I then connect the LaunchPad (and only this one) to the host and use the xdsdfu utility^[2] to write the choosen number to the LaunchPad. Here is an example session:

cd $CCS_INSTALLDIR/ccs/ccs_base/common/uscif/xds110
$ ./xdsdfu -e  (1)

USB Device Firmware Upgrade Utility
Copyright (c) 2008-2019 Texas Instruments Incorporated.  All rights reserved.

Scanning USB buses for supported XDS110 devices...


<<<< Device 0 >>>>

VID: 0x0451    PID: 0xbef3
Device Name:   XDS110 Embed with CMSIS-DAP
Version:       3.0.0.5
Manufacturer:  Texas Instruments
Serial Num:    6
Mode:          Runtime
Configuration: Standard

Found 1 device.

$ ./xdsdfu -m  (2)
$ ./xdsdfu -s 1 -r (3)

1	enumerate (list) all currently connected devices. Only one device must be connected at this time.
2	set the device into DFU mode (required)
3	set the serial number to 1 (replacing 6) and reset the device

The new serial number is persistently stored.

2.2.2. Targeting a serial number in a CCS project

Each CCS contains a target configuration file with the extension *.ccxml.

The connection properties page needs to be populated with the serial number of the target LaunchPad:

Figure 1. Both target configurations are populated with the choosen serial numbers (shown is the collector project).

2.3. Controlling serial port enumeration

After the installation of CCS, a driver installation script must be run to complete the installation. Under linux, the script $CCS_HOME/ccs/ccs_base/common/uscif/install/ti_permissions_install.sh will install the udev^[3] rules file 71-ti-permissions.rules under /etc/udev/rules.d.

When I connect a LaunchPad to the host via USB, udev will load the required driver and allocate two port names, for example ttyACM0 and ttyACM1. The first one is the one I need to choose in my terminal host program.

A second LaunchPad will then enumerate for example as ttyACM2 and ttyACM3.

If I disconnect/reconnect a LaunchPad - something that happens during development work - a new the port name will be assigned. Since the old port name is still available, I might be tempted to resuse it in my terminal application. This results in an an error message. This is extremely annoying as I am forced to discover the new port name by trial and error. It also prevents me from using default configurations for my terminal program.

A couple of hints on how to solve this problems can be found here [r41], [r42], [r43]

Here is my rules file:

# Minimal extract from TI: $CCS_HOME/ccs920/ccs/ccs_base/common/uscif/install/71-ti-permissions.rules
# perms are 644

# mandatory
SUBSYSTEM=="usb",ENV{DEVTYPE}=="usb_device",ATTRS{idVendor}=="1cbe",ATTRS{idProduct}=="00fd",MODE:="0666"
SUBSYSTEM=="usb",ENV{DEVTYPE}=="usb_device",ATTRS{idVendor}=="1cbe",ATTRS{idProduct}=="00ff",MODE:="0666"

# all my launchpads have idProduct bef3
SUBSYSTEMS=="usb",ATTRS{idVendor}=="0451",ATTRS{idProduct}=="bef3",MODE:="0666",SYMLINK+="ti%E{ID_SERIAL_SHORT}%E{ID_USB_INTERFACE_NUM}"

The combination of properties ID_SERIAL_SHORT and ID_USB_INTERFACE_NUM is a unique key for each serial channel. The first property is the serial number I set at the beginning of this chapter.

The last rule will enumerate the first channel on a LaunchPad with serial number 5 as dev/ti500, the second channel as dev/ti503. Currently, I don’t know if the second channel is of any importance to the user.

Here is an example where two LaunchPads with serial numbers 2 and 6 are connected to the host:

$ ls /dev/ti*
lrwxrwxrwx 1 root root  7 Apr 15 21:43 /dev/ti -> hidraw4
lrwxrwxrwx 1 root root 15 Apr 15 21:43 /dev/ti2 -> bus/usb/002/025
lrwxrwxrwx 1 root root  7 Apr 15 21:43 /dev/ti200 -> ttyACM2
lrwxrwxrwx 1 root root  7 Apr 15 21:43 /dev/ti203 -> ttyACM3
lrwxrwxrwx 1 root root 15 Apr 15 19:39 /dev/ti6 -> bus/usb/002/024
lrwxrwxrwx 1 root root  7 Apr 15 19:39 /dev/ti600 -> ttyACM0
lrwxrwxrwx 1 root root  7 Apr 15 19:39 /dev/ti603 -> ttyACM1

I used the following commands to write these rules:

$ udevadm info -a /dev/ttyACMx
$ udevadm test /sys/class/tty/ttyACMx

2.4. Connection problems

In no particular order a grab bag of problems I encountered.

2.4.1. Force-clearing the flash

On one occasion, the collector binary flashed to the LaunchPad produced scrambled output on the terminal connection. I reflashed, recompiled the program, to no avail. I then used UniFlash to clear the entire flash and this solved the problem:

Figure 2. Clearing the flash with UniFlash

2.4.2. Error connecting to the target: (Error -260 @ 0x0)

When I try to run the first debug session for the network_terminal_CC3220SF_LAUNCHXL_tirtos_ccs project from CCS , I got this:

Figure 3. Error message when opening a debug session to the CC3220SF LaunchPad.

I am not sure what finally allowed me to connect, but I suppose I needed to unpluck/repluck the micro USB connector. Presumably, the Uniflash application that I used to flash the binaries still kept a connection to the board. I did not need to change jumper positions on the board.

2.4.3. Debug Configuration: Auto Run and Launch Options

I encountered different error messages (that I failed to write down), when the option

Connect to target on debugger startup

is not checked in the Debug Configuration.

Figure 4. Debug Configuration with the 'Auto Run and Launch Options'

2.5. Other problems

I had to deactivate Remote System Explorer Operation to speed up compilation, see [e2e4]

3. Sensor and Collector - TI 15.4-Stack Project Zero

To familiarize myself with the sensor and collector hardware, I follow the lab exercise Sensor and Collector - TI 15.4-Stack Project Zero. I use GTKTerm from the Mint/Ubuntu distribution.

I use two SimpleLink™ Multi-Band CC1352R Wireless MCU LaunchPad™ Development Kit LaunchPads:

Figure 5. Two CC1352P1 launch pads programmed as Sub-1 Ghz sensor and collector

3.1. Copy the example projects

I import the following projects into the CCS workspace as described in the SimpleLink CC13x2 26x2 SDK (3.40.00.02) documentation of the [r13]

sensor_CC1352P1_LAUNCHXL_tirtos_ccs_syscfg
collector_CC1352P1_LAUNCHXL_tirtos_ccs_syscfg
coprocessor_CC1352P1_LAUNCHXL_tirtos_ccs_syscfg

Within CCS, I then copy the projects into compagnion repo, with the following abbreviated names:

sensor
collector
coprocessor

3.2. Task 1

I can’t set the Sub-1 Ghz Frequency to 868 Mhz as I expected, the only choice for the european band seems to be 863 Mhz. This might be related to the channel selection, I need to read [r11].

Figure 6. Configure the TI 15.4 Stack Sub 1-Ghz Frequency

3.3. Task 3

I set the serial numbers of the sensor and collector to 1 and 2. Therefore, I can open terminal sessions on port /dev/ti100 and /dev/ti200.

As mentioned in step 6 of the lab exercise, I press and hold Button 2 and then the Reset button (while Button 2 is held down) on either board, see hardware setup.

Figure 7. Collector (top) and sensor (bottom) terminal output after factory reset.

After pressing Button 2 again on the collector, the sensor is allowed to join and a network is created:

Figure 8. Collector (top) and sensor (bottom) terminal output after the sensor joined the network.

4. Coprocessor

4.1. Copy the example project

I import the project coprocessor_CC1352P1_LAUNCHXL_tirtos_ccs_syscfg into the CCS workspace.

Within CCS, I then copy the project as coprocessor-uart into the compagnion repo.

4.2. UART configuration

According to the TI Design, I need to modifiy the UART configuration:

When re-compiling the Mac CoP firmware, the pin configuration for the UART needs to be modified since the default Mac CoP example in the CC13xxSDK uses IOID3 and IOID2 pins for UART and the gateway uses IOID11 and IOID9.

— 3.2.1.1.4.3 Compiling the Mac-CoP fromSource

However, the CC1352P1 LaunchPad uses DIO12 and DIO13 corresponding to J4/J3 on the BoosterPack Standard Header Pin Assignment, just like the CC3220 LaunchPad for the gateway. No modification is required on either board, other than the Jumper adjustements explained in 3.2.1.1.5 Connecting the MAC-CoP and the CC3220SFLaunchPad™.

5. Gateway

To familiarize myself with the gateway hardware SimpleLink™ Wi-Fi® CC3220SF wireless microcontroller LaunchPad™ development kit, I follow the lab exercise Meet the CC3220x LaunchPad Development Kit.

5.1. Task 1

I could not complete this task with the LaunchPad as shipped.

I first followed CC3220 SimpleLink™ Wi-Fi® and Internet of Things Solution,a Single-Chip Wireless MCU Getting Started Guide to flash the latest service pack and the MCU binary network_terminal_CC3220SF_LAUNCHXL_tirtos_ccs.

Figure 9. Terminal output for the network terminal demo.

I then flashed the out_of_box_CC3220SF_LAUNCHXL_tirtos_ccs demo project as described.

The default target configuration is correct (I set the serial number for the gateway LaunchPad to 3):

Figure 10. Default target with the custom serial number

While I was able to start a debug session for the out_of_box_CC3220SF_LAUNCHXL_tirtos_ccs project, the loaded program was not persisted to flash, rather the previsiouly flashed network terminal demo would run upon reset. Also, I did not get any terminal output, so there seems to be a difference between the binaries I flashed in Task 1 and the one I created with CCS.

5.2. Task 6

I was unable to provision the LaunchPad with the android app: the scan for devices to configure always times out. Instead, I created a profile from the website running on the LaunchPad.

Upon reset, the board connects automatically to the AP APSchuppen:

Figure 11. Provisioning via internal webserver seems to be succesfull.

5.3. Recompiling from source

I import the example projects

15_4_Stack_Gtway_IBM_CC3220SF_LAUNCHXL_tirtos_ccs
tirtos_builds_CC3220SF_LAUNCHXL_release_ccs

from

vittali.ch-5-TIR-1002/tidc01002/examples/cc3220sf_gateway_app

where vittali.ch-5-TIR-1002 is the compagnion repo and tidc01002 the source code repo of the TI Design (used as a git submodule). I then copied these projects to

gateway
gateway-base

in the companion repo.

The project won’t compile because of issues with virtual folders and paths. Also, the following header files are missing [e2e3]:

Table 1. Missing header files for the gateway project
missing file in TI Design	replacement	comment
ti/drivers/i2s/I2SCC32XXDMA.h	I2CC32XX.h	renamed
ti/drivers/net/wifi/bsd/sys/socket.h	ti/net/bsd/sys/socket.h
ti/drivers/SDSPI.h	-	no longer supported, can be removed
wolfssl/ssl.h	wolfssl/ssl.h	seperate installation

In turns out that this is just the tip of the iceberg, a lot of changes are required to get the project to compile. Unfortunately, I still get plenty of linking errors and I am not able to build the project. The companion repo contains the current unfinished state of the project.

6. IBM cloud demo software

After a couple of modifications inside the ibm_cloud_application directory (see log of the git submodule), I am able to push the application to the IBM cloud:

$ cd vittali.ch-5-TIR-1002/tidc01002/examples/ibm_cloud_application
$ ibmcloud login
$ ibmclound target --cf
$ ibmcloud push --cf

I am unable to open the network as explained in Figure 67 of the reference document [e2e2].

I suspect the reason is a communication problem between coprocessor and gateway or/and the coprocessor and the sensor. Clearly, the coprocessor must be configured to use the european 863 Mhz band, but it is not clear to me how this configuration can be performed.