Bluetooth Low Energy and sub1GHz Sensor Gateway

From Texas Instruments Wiki
Jump to: navigation, search

Introduction

The purpose of this document is to describe the setup and build of a Sensor Gateway which is able to connect to both Bluetooth Low Energy (CC2650) and sub-1GHz (CC1350) IEEE802.15.4 sensorTags. It is based on an AM335x based BeagleBoneBlack Linux processor using an E14 Wireless Gateway cape to provide the Bluetooth radio on a WL1837MOD and a USB connected CC1350 LaunchPad to provide the IEEE802.15.4 radio. This demo supports a “large scale” implementation of the Bluetooth Low Energy network as it connects to sensors one at a time in a round robin manner to overcome the WiLink8 limit of 10 concurrent connections. The trade off in this architecture is that data can only be sampled from each sensor node periodically rather than continuously. An alternative Bluetooth Low Energy architecture with up to 10 continuous connections is described here. The IEEE802.15.4 nodes broadcast their data periodically and one at a time with the ability to support a large network. The data from both types of sensor networks are stored in a common SQL database.


The gateway provides the following functionality and enhancements to standard TI deliveries.

  • Bluetooth Low Energy based gateway built with Bluetopia which will connect to CC2650 Sensortags one at a time and read out GATT based sensor data and store it to a shared SQL database on the gateway.
  • Enhance CC2650 Sensortag so that it will also capture short bursts of raw 16 bit audio data on the PDM microphone at 16k and 46.875k and export them as a GATT service.
  • Enhance TI 802.15.4 MAC gateway application so that it can store received data into the shared SQL database.
  • Port CC1350 802.15.4 sensor example from CC1350 Launchpad to CC1350 Sensortag and also add real sensor values for Temp, Humidity, Light and Battery level. Add collector and gateway support for these additional data values to Linux application.
  • Provides Python based visualisation tools to view data from both Bluetooth Low Energy and sub 1GHz Sensortags in the shared SQL database.


The image below shows a test setup with:

GatewayBeagle Bone Black + E14 Wireless Cape + CC1350 Launchpad

Bluetooth Low Energy Sensor Nodes – 2 x CC2650 Sensortags

Sub 1GHz Sensor Nodes – 2 x CC1350 Sensortags

System hardware.jpg


Hardware Requirements

The Bluetooth Low Energy gateway/hub is based on a Beagle Bone Black (BBB) Single Board computer running Linux (TI Processor SDK 3.02) with an Element14 Wireless Connectivity Cape and a CC1350 Launchpad. To simplify Linux development it is recommended to use an FTDI TTL to USB cable (TTL-232R-3V3) to provide a terminal console. This is an easier alternative than logging in via SSH.

The Sensor Nodes use the CC2650 SensorTag for Bluetooth Low Energy and CC1350 SensorTag for sub-1GHz. In order to debug both types of SensorTag with Code Composer Studio and programme the custom firmware a Debugger DevPack is required.

Software Requirements

If you would like to the source packages for this code please ask on e2e.

Gateway

In order to create an SD card with the Linux image for the BBB a Ubuntu PC is required (can be native or in a Virtual Machine). In this Ubuntu machine the TI Processor SDK is installed which contains all the components to build the SD card. The SensorTag code is built using Code Composer Studio as an IDE on either Windows or Linux (CC1350 SDK only) to build the CC26xx SDK and CC1350 SDK.

Building the Gateway

1. Download and Install TI Processor SDK 3.02 to the Ubuntu machine.

2. Run the setup script to set up paths

$cd ti-processor-sdk-linx-am335x-evm-03.02.00.05
~/ti-processor-sdk-linx-am335x-evm-03.02.00.05$./setup.sh

3. Download the TI Bluetopia Bluetoooth stack and install to the base directory of the SDK. This should give you a directory ~/ti-processor-sdk-linx-am335x-evm-03.02.00.05/AM335xBluetopiaLinuxProduction-4.2.1.0.1.0

4. Download the TI 802.15.4 SDK and install to the base directory of the SDK. This should give you a directory ~/ti-processor-sdk-linx-am335x-evm-03.02.00.05/ti-15.4stack-2.01.00.10

5. Extract the build package (am335x-sdk03.02-large-sg-v1.5.tar.gz) for the sensor gateway to the base directory of the SDK.

6. Install git (if not already installed) to manage the application of patches and then create your user

$sudo apt-get update
$sudo apt-get install git
$git config –-global user.email “you@example.com”
$git config –-global user.name “Your Name” 

7. Run the build script to build linux kernel and uboot, build the Sensor Gateway application and configure the filesystem.

~/ti-processor-sdk-linux-am335x-evm-03.02.00.05$./build-sensor-gateway-sql.sh

The script will create two tar balls that contain the boot and rootfs partitions that are to be programmed to the microSD card. They are in tar-sg-sql-large-filesystem-e14 in the SDK base directory.

Programming the Gateway SD card

1. Insert the microSD card into an MMC slot on the Linux machine. 2. Run the programming tool as described here. Choose the custom images option as described in this section and enter the paths for the boot and rootfs tarballs mentioned previously. They will usually be at ~/ti-processor-sdk-linx-am335x-evm-03.02.00.05/tar-sg-sql-large-filesystem-e14. However the full path must be entered and not ~ for the home directory.

Preparing the Gateway

First step is to assemble the gateway hardware. If using TTL to USB cable then connect the 6 way connector to J1 on the BBB. The black cable (pin 1) should be at the end of J1 marked with a dot on the PCB closest to the 5V barrel connector. Gently push the 6 way connector down to 45 degrees towards the centre of the BBB to minimise its height. Out of the box the BBB contains a full image in the eMMC. Holding switch S2 down during power insertion will force the AM335x ROM to boot from microSD card. This is inconvenient and so next step is to modify the eMMC contents to prevent it being seen by the boot ROM as a valid boot image and so force microSD card boot.

1. Without an SD card inserted insert power and let the board boot from the pre-installed Debian image in the eMMC. If it does not boot then skip steps 2-5.

2. Insert FTDI cable USB into a PC and note the COM port that it enumerates. Use a terminal programme such as PuTTY or Teraterm and open as a serial port at 115200baud. Below is an example configuration for PuTTY on COM110.

Putty example.JPG

3. When terminal opens there should be a terminal prompt. Log in as user root with password root.

4. Enter the following command to erase the uboot image stored at the start of the eMMC.

root@beaglebone:~# sudo dd if=/dev/zero of=/dev/mmcblk1 bs=1M count=10

This means the eMMC can no longer be used. To reflash the eMMC with a Debian image follow these instructions.

5. Next step is to mount the Wireless Connectivity cape on top of the BBB. Use the cut out for the Ethernet connector to orientate the cape. The combination should look as shown below when assembled.

Gateway board jpeg-v2.JPG

6. Insert the microSD in the slot underneath the BBB.


Configuring the Gateway for Bluetooth Low Energy nodes

Now power on the gateway and log into the terminal as user root. The file ~/systemConfig.txt is used to control the system. It defines a list of Bluetooth MAC addresses that the gateway can connect to and which sensors are requested for each SensorTag. The sensor application is designed to query the GATT table for each connected SensorTag and then start the requested sensors. The configuration file has the following format for each possible SensorTag.

<12 character MAC address>
<16 bit UUID for sensor #1>
<16 bit UUID for sensor #1>
NULL

The 16 bit UUID for each sensor is the unique element of the 128 bit UUID which defines the Primary Service Characteristic in the SensorTag GATT Table. As an example the Humidity service has the 128 bit UUID F000AA20-0451-4000-B000-000000000000. The 16 bit UUID is AA20.

The main loop in BLE_App,c now handles the following UUIDs in systemConfig.txt.

AA20

This is humidity. The Humidity sensor also calculates ambient temperature as well. This allows the App to write to the database the ambient temperature under the UUID AA00. Currently AA00 in systemConfig.txt is returning 0 from the TMP007 and so should not be used.

AA80

This is the accelerometer. It reads one set of samples from the MPU9250. In order to simplify storage of the X,Y and Z values they are stored in the database under three UUIDs

AA80 – X axis
AA81 – Y axis
AA82 – Z axis

180F

This is the 16 bit characteristic for the Bluetooth Battery service.

B000

This requests a stream of audio from the PDM microphone at 16kHz. Typically 20ms of data will be captured and streamed.

B010

This requests a stream of audio from the PDM microphone at 46.875kHz. Typically 6ms of data will be captured and streamed in this mode. It is actually requested in GATT by B000 UUID with a specific start value of 0x3.

The correspondence between UUIDs used in systemConfig.txt, in Sensortag and in SQL is summarised below.

systemConfig.txt By GATT In SQL
Humidity AA20 AA20 AA20
Ambient Temp AA20 AA20 AA00
Accelerometer - X AA80 AA80 AA80
Accelerometer - Y AA80 AA80 AA81
Accelerometer - Z AA80 AA80 AA82
Battery 180F 180F 180F
16k Audio B000 B000 B000
46.875k Audio B010 B010 B010


In order to handle additional sensor values from the SensorTag or a custom sensor it will only be necessary to add a new if statement to this loop to convert the UUID raw data value into the readable value.

The easiest way to identify the MACs for the SensorTags is to use the Android or IoS SensorTag app Switch the SensorTags on one at a time noting the MAC address for each.

The file ~/systemConfig.txt can be edited either through the terminal using the vi editor or by mounting the microSD card on the Ubuntu machine and using gedit (must be run as sudo as SD card is read only).

At a high level the Gateway software operates as follows

  • Parses systemConfig.txt to populate a SensorTable which holds all possible Bluetooth Low Energy Sensor Nodes (by MAC address) and individual sensors (by UUID).
  • Creates SQLite3 database to store the captured data
  • Creates connection manager thread which handles the TI Bluetooth stack calls
  • Sends a message to connection manager to initialise Bluetooth stack.
  • Power on Bluetooth in WL183x and configure stack
  • Sends a message to connection manager to scan for advertising BLE devices.
  • If advertising device matches a MAC in SensorTable mark this node as available.
  • Sends a message to connection manager to stop scanning and read all available nodes.
  • Connect to first available node in SensorTable
  • When connected read the available services (ie UUIDs) from the node.

A more precise explanation using a Message Sequence Chart is given in the file ble-sensor-gateway-msc-large-network-v1-5.xls.


Bluetooth Low Energy Sensor Node

Building the Bluetooth Low Energy Sensortag Firmware

The SensorTag firmware has been built in both CCS v6.2.0 or 7.1.0. Download and install latest CC2650 SDK BLE-STACK-2-2-1 (in the example it is installed to C:\ti\simplelink\ble_sdk_2_02_01_18). There is only a Windows installer for this version of the stack.

There are three separate projects that are involved in the SensorTag.

  • bim_extflash – this is the bootloader for the CC2640 and is not changed for this project.
  • sensortag_audio_cc2650stk_stack – this is the bluetooth stack and is not changed for this project.
  • sensortag_audio_cc2650stk_app – this is the application and for this project it is a patched version of the standard SDK application.

Also install TI-RTOS version 2.21 as an upgrade to 2.21 from 2.20 is required for one of the patches.


Install Python

The final step of the build is to run a python script to combine all three projects into a single Intel Hex format file that can be flashed by Flash Programmer 2 to the SensorTag. In order to do this python must be installed on the build machine. In the examples Python v2.7 was installed into c:\Python27

To install intelhex run in a Windows cmd shell

cd c:\Python27\Scripts
c:\Python27\Scripts> pip install intelhex

Patch Application

Apply the following GIT patches from ble_sdk_2_02_01_18–v1.5.zip to the SDK using the generic instructions here to set up a GIT repository and then apply the patches. This zip file also contains a pre-built image sensortag_audio_cc2650stk_all.hex which can be directly programmed using RF Programmer 2.

Also use the same approach to apply patches from tirtos_cc13xx_cc26xx_2_21_00_06-v1.5.zip to C:\ti\tirtos_cc13xx_cc26xx_2_20_01_08. One of the patches in the BLE SDK pulls in the modified file from the TI-RTOS and builds it as part of the application. This only works if BLE and TI-RTOS are in their default locations.

Do this before opening the projects in CCS as the .cproject file controls CCS configurations and is not a source file.


Build Application

Open CCS. When asked create a new workspace as shown below

Create-workspace-ccs7.JPG

When workspace is opened click Import Project button which brings up following dialogue box.

Import-project-1.JPG

Use browse to point to the SDK directory to set the Search-directory.

Import-project-2.JPG

There are three projects that need to be imported. The image above shows the sensortag_audio_cc2650stk_app and sensortag_audio_cc2650stk_stack projects selected for import. The image below shows the third which is the bim_extflash boot loader.

Import-project-3.JPG

Then press Finish to import these three projects into the workspace.

The bim_extflash and sensortag_audio_cc2650stk_stack projects need to be built first so that the final hex image including these projects can be built by the application project. Do this in the project explorer window by right clicking on the project and select rebuild all.

The build order should be bim_extflash, sensortag_audio_cc2650stk_stack and then finally sensortag_audio_cc2650stk_app.


Programming the CC2650 SensorTag

The SensorTag is programmed using the Flash-Programmer v2 utility. This uses a USB connection from the PC to a Dev-Debug pack mounted on the SensorTag (with the red sleeve removed) as shown below. Battery should be inserted in SensorTag even when powered by USB.

Dev-debug.JPG

Run Flash Programmer 2 to get the screen below.

Flash-programmer.JPG

There are several steps to programme

1. Press Refresh button

2. Click on the CC2650

3. Browse to the firmware image to be loaded (only needs to be done when file location changes)

4. Press Play button to carry out the Actions requested – in this case Erase, Programme and Verify.


Sub 1GHz Sensor Node

Building the sub1GHz Sensortag Firmware in Windows

The SensorTag firmware has been built in both CCS v6.2.0 and CCS 7.1.0 Download and install latest CC1350 SDK 1.30 (in the example it is installed to C:\ti\simplelink_cc13x0_sdk_1_30_00_06). There is one project that is involved in the SensorTag.

  • Sensor_cc1350lp – this project is for the CC1350 Launchpad and patches are applied to move it to the CC1350 SensorTag and add the drivers for the sensors on the SensorTag.

The SDK 1.30 projects are set up so that the source code is copied into the CCS workspace rather than being built from the install directory. This means that the git repository must be configured to manage the workspace.

Open CCS and create workspace C:\ti\workspace-cc7-1-cc1350-sensortag.

Import the project sensor_cc1350lp into this workspace. The project is setup to copy the sources from the SDK directory into the workspace directory.

Cc1350-project-open.JPG

Follow these instructions to create a git repository in C:\ti\workspace-cc7-1-cc1350-sensortag. Apply the patches from workspace-cc7-1-cc1350-sensortag-v1.5.tar.gz with git am.

The build settings for the project are held in the .cproject file in the workspace. This file has different content on every creation and so cannot be patched using git. The modifications must be made via project properties in CCS. So, reopen the project in CCS and open Project Properties, then open Build -> ARM Compiler-> Predefined symbols option and make following modifications:

- Add defines BATTERY_LEVEL, LIGHT_SENSOR, HUMIDITY_SENSOR, CC1350_STK and CC1310EM_7ID

- Remove defines CC13XX_LAUNCHXL, SET_CCFG_BL_CONFIG_BL_LEVEL, SET_CCFG_BL_CONFIG_BL_ENABLE, SET_CCFG_BL_CONFIG_BL_PIN_NUMBER, SET_CCFG_BL_CONFIG_BOOTLOADER_ENABLE

Cc1350-project-defines.JPG

In the project explorer window it is also necessary to exclude two files (Application/Launchpad/CC1350_LAUNCHXL.c and Application/PALNA/board_palna.c) from the build as shown below.

Cc1350-exclude-from-build.JPG

Build the project and the final executable will be found in C:\ti\workspace-cc7-1-cc1350-sensortag\sensor_cc1350lp\sensor_cc1350lp\sensor_cc1350lp.hex

Use the same procedure to programme CC1350STK as used earlier for CC2650STK.


Building the sub1GHz Sensortag Firmware under Linux

The SensorTag firmware has been built in CCS 7.1.0. Download and install Linux installer for CC1350 SDK 1.30 (in the example it is installed to /home/<user>/ti/simplelink_cc13x0_sdk_1_30_00_06). There is one project that is involved in the SensorTag.

  • Sensor_cc1350lp – this project is for the CC1350 Launchpad and patches are applied to move it to the CC1350 SensorTag and add the drivers for the sensors on the SensorTag.

The SDK 1.30 projects are set up so that the source code is copied into the CCS workspace rather than being built from the install directory. This means that the git repository must be configured to manage the workspace.

Open CCS and create workspace /home/<user>/ti/workspace-cc7-1-cc1350-sensortag. Import the project sensor_cc1350lp into this workspace. The project is setup to copy the sources from the SDK directory into the workspace directory.

Cc1350-project-open.JPG

Now close CCS workspace.

Use following command line instructions to create a git repository for the workspace before it is built.

$ cd workspace-cc7-1-cc1350-sensortag
~/workspace-cc7-1-cc1350-sensortag$ git init

Once the repository is created need to set a local git parameter to ignore differences in file permissions. The patches created in windows have source file permissions of 0x644 but when SDK 1.30 installs to Linux they have 0x755. By default git will not apply a patch for a 0x644 file to a 0x755. Setting filemode to false tells git to ignore the permissions when it is testing whether it can apply a patch. This only applies to the local git repository.

~/workspace-cc7-1-cc1350-sensortag$ git config core.filemode false

Now add the imported files to the repo and commit them

~/workspace-cc7-1-cc1350-sensortag$ git add sensor_cc1350lp
~/workspace-cc7-1-cc1350-sensortag$ git commit –a –m “initial SDK project”

The next stage is to add all the patches from workspace-cc7-1-cc1350-sensortag-v1.5.tar.gz so extract them to workspace. As these patches were created in windows the whitespace characters are different. To apply these on a Linux build git must be told to ignore them with the --ignore-whitespace option.

~/workspace-cc7-1-cc1350-sensortag$ git am -–ignore-whitespace 0001-set-to-european-frequency.patch

Use this command to apply all patches one by one.

The build settings for the project are held in the .cproject file in the workspace. This file has different content on every creation and so cannot be patched using git. The modifications must be made via project properties in CCS. So, reopen the project in CCS and open Project Properties, then open Build -> ARM Compiler-> Predefined symbols option and make following modifications:

- Add defines BATTERY_LEVEL, LIGHT_SENSOR, HUMIDITY_SENSOR, CC1350_STK and CC1310EM_7ID

- Remove defines CC13XX_LAUNCHXL, SET_CCFG_BL_CONFIG_BL_LEVEL, SET_CCFG_BL_CONFIG_BL_ENABLE, SET_CCFG_BL_CONFIG_BL_PIN_NUMBER, SET_CCFG_BL_CONFIG_BOOTLOADER_ENABLE

Cc1350-project-defines.JPG

In the project explorer window it is also necessary to exclude two files (Application/Launchpad/CC1350_LAUNCHXL.c and Application/PALNA/board_palna.c) from the build as shown below.

Cc1350-exclude-from-build.JPG

Build the project and the final executable will be found in ~/workspace-cc7-1-cc1350-sensortag/sensor_cc1350lp/sensor_cc1350lp/sensor_cc1350lp.hex

Use the same procedure to programme CC1350STK as used earlier for CC2650STK. This must be done on a Windows machine as flash programmer does not have a Linux version.


Flash the CC1350 Launchpad with Co-Processor Application

The CC1350 Launchpad is connected to the Beagle Bone Black via USB and runs the sub 1G radio for the gateway. It uses a standard project from the SDK and so no building is required. Use Flash Programmer 2 to programme the pre-built hex file C:\ti\simplelink_cc13x0_sdk_1_30_00_06\examples\rtos\CC1350_LAUNCHXL\ti154stack\hexfiles\coprocessor_cc13xx_lp.hex Once programmed connect the CC1350LP with the Co-Processor application to a USB port on the BBB.


Running the System

Starting the Gateway

By default the gateway is not run on boot. To run the gateway manually log in as user root

#./run-gateway.sh

This script will start an http server and then run separate scripts to independently start the Bluetooth Low Energy and Sub1GHz applications.

To enable an auto start of the gateway on boot by systemd use the following command to disable the gateway service and then reboot

#systemctl enable gateway.service
#reboot

To disable the auto start use

#systemctl disable gateway.service
#reboot

When using systemd the output from the gateway application can be read with the following command as it does not come to STDOUT. In this case it is the last 100 lines.

#systemctl status gateway.service –n 100
 

If started manually with run-gateway.sh then the output does come to STDOUT.


The CC2650STKs are enabled to join the gateway by the MAC addresses in the systemConfig.txt file.

The CC1350STKs are prevented from joining at boot. To enable joining of the sub1G Sensortags to the gateway open the web interface on the gateway using IP address of BeagleBone Black and port 1310.

http://<gateway-ip>:1310 

and click on the Open button as shown below. This will open the network to allow any CC1350STK to join.


Sub1g-gateway-setup.png


Both types of SensorTags can then be started by pushing the ON button or inserting the battery.


Once CC1350STKs start connecting to the network the web interface will show the latest data sent from each node.

Sub1g-gateway-webinterface.png


The gateways stores the data from both types of SensorTag in the same SQL database located at /var/www/sensors-<date>. As this is the lighttpd base directory the SQL database can be accessed remotely using

$wget http://<gateway ip>/sensors-07-03-2017

The database has three tables which were created as follows:

node_data – this contains the single sample data from SensorTag. For each sample value it stores the MAC address from which it came, the uuid of the sample and the time it was captured. The UUID from Bluetooth Low Energy is also used to identify the same data type when it comes from sub 1G node. So for example Battery voltage is identified by 0x180F.

CREATE TABLE node_data(mac TEXT, uuid TEXT, value REAL, time INTEGER)

stream_data – this contains the streamed data from SensorTag. For each sample buffer it stores the device_index from which it came, the uuid of the sample and the time it was captured.

CREATE TABLE node_data(device_index INTEGER, uuid TEXT, buffer BLOB, time INTEGER)

rssi_data – this contains the RSSI from SensorTag when it connected. For each connection to device_index it stores the rssi and and the time it was connected.

CREATE TABLE rssi_data(device_index INTEGER, rssi INTEGER, time INTEGER)


Viewing the data

The directory python is the SDK contains some python scripts that can be used to visualise the data held in the SQL data base. These are run on the host which is assumed to be on same network as the gateway so that it can fetch the SQL data file from the web server on the gateway.

The script show-data.py is used to visualise one UUID value across multiple sensor nodes. To use this there are three parameters that need to be set in the script.

#Set file name
dayFileName=”sensors-19-05-2017”
# and IP address of the gateway
serverIP=”192.168.10.12”
#set UUID to plot
#AA00 is temperature
#AA20 is humidity
#180F is battery
uuidToPlot=”AA00”

To run this on the host from SDK directory

$python python/show_data.py 

Will produce the following plot of the temperatures across four sensor nodes – two Bluetooth Low Energy (36 bit MACs) and two sub 1GHz (48 bit MACs).

Temperature-capture-4-nodes.png

Similarly the extract-stream-16k.py script will display all the audio buffers sampled. In the script it is possible to select the MAC address whose data should be extracted from the database. The script does not attempt to use the time stamp for each buffer to show a 3-D plot of samples over time.

Audio-16k-visualisation.png


Bluetooth Low Energy Connection Timings

In the Bluetooth Low Energy network the limitation on the number of nodes supported is primarily the length of time it takes to do a connect, read and disconnect cycle. To eliminate the additional time involved in starting sensors on the sensortag the test involved reading only the battery voltage from the sensortag. In the test there were 4 Bluetooth Low Energy SensorTags being used with an advertising interval of 1s. The following stages of the cycle were measured separately.

  • Connection to SensorTag
  • Service Discovery – there is the initial step when data is actually read from Sensortag, subsequently it is read from stack.
  • Changing Connection Interval to 10ms
  • Reading one data value (Battery)
  • Disconnection

These were measured over multiple cycles and the mean and standard deviation calculated

Mean (ms) Standard Deviation
Connection 1810 1031
Initial SDP 1675 1339
Subsequent SDP 1 1
Set Connection Interval 1651 491
Data Read 32 8
Disconnection 30 19


The connection interval time is impacted by the advertising period of 1second in use to save power.

The initial SDP read is impacted by the default 100ms Connection Interval used by the Bluetopia stack and the fact it is reading 1436 bytes.