WL1835/WL1837-Wireless-Sensor-Gateway SDK8

This page describes a project that implements a BLE sensor network gateway on an AM335x and WL1835MOD/WL1837MOD based on SDK8. It will run on an AM335x EVM + WL1835MODCOM8/WL1837MODCOM8I or a BeagleBone Black + WL8 cape. The build script in this project can also be used in isolation as an example on how to build R8.5 Wi-Fi drivers against SDK8. The previous release with SDK7 is here

The AM335x runs the TI Bluetopia stack in SDK8.0 to provide a connection to up to 10 CC2541 or CC2650 BLE SensorTags which are periodically sending temperature data which is then written to file. The AM335x is also running a Lighttpd web server which can be accessed by a remote PC over wifi to access the sensor data. This remote PC runs an application using Python and MatPlotLib to read the data from the server and display it in a 3D graph which updates in real time.

When running on a BeagleBoneBlack ensure that an external 5V power supply is also used as the USB is not capable of supplying the extra power needed by WL18xx.

The system diagram is shown below.

Creating the demo

The demo can run either from pre-built boot and rootfs partitions that can be written directly to an SD card or it can be built from scratch.

Using pre-built filesystems

This is the simplest way to get the demo running. Use the standard SDK8.0 tool /bin/create-sd.sh to write the boot and rootfs partition tar balls. This build will boot on the AM335x EVM or BeagleBone Black.

The script to create the SD card must be run as sudo

$cd bin
$sudo ./create-sd.sh

Once the partitioning steps have been done select the custom file paths option

2) Enter in custom boot and rootfs file paths

and the path to the downloaded boot partition sensor-gateway-boot_partition-sdk8-v1.0.tar.gz. At the next option select Kernel and device tree from rootfs.

1) Reuse kernel image and device tree files found in the selected rootfs

and the path to the downloaded rootfs partition sensor-gateway-rootfs_partition-sdk8-v1.0.tar.gz

For reference the tar balls were built with a script as described in the following sections. The script builds the individual components and then installs them into a filesystem called sensor-gateway-filesystem. It then creates tarballs of the boot and rootfs partitions which are found in /tar-files-sensor-gateway-demo

Building the demo from scratch

The presumption for building this is that SDK8.0 has been installed and that the Production License version of Bluetopia Bluetooth Stack (v4.1.0.4.2U) has also been installed into the top level SDK directory. There are two source packages that need to be extracted to the the top level of the SDK: Wi-Fi and system and BLE Application (this file has patches that are licensed under the terms of the Bluetopia package).

The "Wi-Fi and system" package contains the build script for the WiLink8 Wi-Fi drivers and so it can be used standalone to just build the R8.5 drivers against SDK8. The "BLE Application" package is only required to generate this demo.

Ensure that the paths in the file patches/wifi-build-patches/setup-env match those of your installation.

Run the script

./build-sensor-gateway.sh

which will then do all the following stages of the build which are now described in more detail.

This script can be used as an reference for all the steps involved in rebuilding R8.5 Wi-Fi drivers.

Wi-fi

SDK8.0 comes with the R8.5 version of the WiLink8 driver pre-installed in the filesystem. These instructions explain how to build the kernel and rebuild the latest R8.5 WiLink8 drivers as modules before installing them in a basic Arago filesystem (as included in SDK8.0). The base arago filesystem was chosen to provide a minimal filesystem which can be added to as required.

Build Kernel

The only change to the kernel build is to add support for WiLink8 cape for the Beagle Bone Black Device Tree file.

Build WL8 drivers

The Wilink R8.5 drivers are build by following the process here. The drivers are build from the tag R8.5. In the R8.5 build environment all the scripts and source packages are within the build-utilites directory in base directory of the SDK.

The download of all the source files for the Wi-Fi drivers and utilities is done by

./build_wl18xx.sh update R8.5

As the rootfs being used is owned by root, the sudo version of the Wi-Fi build script must be used to ensure that the final install stage of the build can write to the rootfs

./sudo_build_wl18xx.sh clean

Bluetooth Stack

We use Production version as we are using WL1835MODCOM8/WL1837MODCOM8i. There is a single package for all boards as SDK8 uses UIM/KIM to generate a virtual tty_hci port with the DTS file allocating actual pins and ports for each board type.

The installation instructions for Bluetopia are found here. The script downloads the latest WL8 Bluetooth firmware file and saves it to /lib/firmware on the target filesystem.

Building the sensor application code

The application code is created by copying and then patching one of the example applications in the directory ~/ti-sdk-am335x-evm-08.00.00.00/AM335xBluetopiaLinuxProduction-4.0.1.4.2U.

Run the script

./create_ble_manager.sh

which will create a new directory (BLEManager), copy the source files for the LinuxGATM app from the sample folder and then patch it to create the new BLEManager code.

Build the BLE Sensor Application

Run the application make file and copy executable to target file system

cd ~/ti-sdk-am335x-evm-08.00.00.00/AM335xBluetopiaLinuxProduction-4.0.1.4.2U/BLEManager

make CC=${CROSS_COMPILE}gcc -f BLE_App.mak

sudo cp BLE_App ~/ti-sdk-am335x-evm-08.00.00.00/sensor-gateway-filesystem/opt/ss1/BluetopiaPM/bin

The sensor application is designed to run with TI's CC2541 or CC2650 SensorTags. It has been hardcoded from the GATT tables for CC2541 GATT Server and [ CC2650] properties for Temperature and Humidity.

Install the run time scripts

Extract the file patches/ble-app-patches/sensor-gateway-scripts-v1.6.tar.gz to home directory of the target filesystem. The main script run.sh carries out the following tasks

• stops any existing lighttd service and restarts it with the local configuration file lighttpd-sensor-server.conf which will export /opt/ss1/BluetopiaPM/bin/ as the document-root.
• brings up interface wlan0 with address 10.4.30.34
• starts hostapd to create the softAP. It uses the local configuration file hostapd_minimal.conf which brings the AP up with the SSID SensorGateway.
• starts udhcpc with local configuration file udhcpc_only.conf which will assign IP addresses in the range 10.4.30.40-48.
• starts Bluetooth Platform manager SS1BTPM in the background and then the actual sensor application BLE_App. BLE_App is started without the optional argument -w ble-whitelist.txt. When the MAC addresses of the SensorTags in use are known they can be added to whitelist.txt. This forces the gateway to only accept connections from known devices.

SensorTag

The demo was tested with CC2541 SensorTags with the latest firmware v1.5 and CC2650SensorTags hw version 1.2.0 and SW v0.89.

Install the GUI on the Linux PC

On the Linux PC the python based 2D plotting tool matplotlib is used to display the sensor values from the gateway. Install matplotlib with

$ sudo apt-get install python-matplotlib 

Create a new directory on the host ~/sensor-gui. Extract the perl script gui.sh from patches/ble-app-patches/gui-v1.1.tar.gz to this directory.

The script gui.sh is responsible for reading sensor data from the gateway, parsing the data and then every 10 seconds updating the data plot. Some key points in this scripts are

• Location to fetch sensor data

The address of the sensor data in the gateway is contained the variable

sensorURL = "http://10.4.30.34/sensors/sensor-data.txt" 

• Mapping the sensor MACs to a location the plot

The concept behind the plotting is that each sensor has a physical location in (x,y) space and that the temperature is the y dimension.

The array NetworkStructureSize defines the number of points in the sensor network. In this case there are 8 sensors in a 4x2 grid. The array NetworkStructureLocation ties the MAC address of each sensor to a physical location. These two arrays must therefore be edited to match the number and MAC addresses of the SensorTags available.

The script has a run time failure if only 1 sensor tag is connected. It requires at least 2 to be connected.

NetworkStructureSize=(4,2) 
NetworkStructureLocation=(['34B1F7D4FFBF',3,1],
                         ['78C5E56EE9B6',3,0],
                         ['34B1F7D13501',2,1],
                         ['34B1F7D4F814',2,0],
                         ['34B1F7D133DC',1,1],
                         ['34B1F7D50169',1,0],
                         ['34B1F7D50231',0,1],
                         ['34B1F7D133EF',0,0]
    )

When the script is run it will draw a plot as shown below. Matplotlib allows the plot to be rotated by holding down the left mouse button over the plot.

In order for the Linux PC to access the sensor gateway all proxies need to be disabled. Typical symptom of this is that a browser can open "http://10.4.30.34" and it is possible to "ping 10.4.30.34" but the script gui.sh fails with an http_open error.

Running the demo

The following sequence of steps needs to be taken to run the demo

• On the target start the wifi AP and the BLE Sensor application

cd sensor-gateway

./run.sh

The script calls BLE_App with an optional parameter "-w ble-whitelist.txt". This option allows you to create a file with the MAC addresses of all the known BLE devices to connect to. It consists of a txt file with each line containing a 12 character string of device MAC addresses. It is useful for environments where there may be other SensorTags visible that are not part of the demo. Initially edit the run.sh file to remove this argument. Then once demo environment is setup add the whitelist file.

• On the Linux PC connect to the Access Point "SensorGateway" with the password "sensortag".

• Switch on each of the SensorTags. As each is switched on there should be a message shown on the target

DEVM_ConnectWithRemoteDevice() Success: 0. 

• On the Linux PC start the gui

$cd sensor-gui 

$./gui.sh

Architecture of BLE_App

This section describes in detail the architecture of the system. The message sequence chart below shows how the system connects to any number of BLE devices (upto 10).

The lighttpd service is started by the script run.sh before it starts BLE_App.

When it starts BLE_App creates the ConnectionManager thread and sends it an INIT message. The ConnectionManager thread is responsible for managing all the BLE connections, handling the sensor measurements and keeping a table of all the most recent measurements for each active sensor. After starting the ConnectionManager thread the BLE_App periodically (every 10 seconds) asks the ConnectionManager for the latest table of sensor information and writes it to the file sensor/sensor-data.txt as shown in the Message Sequence Chart below. This is the file that the PC app reads when it makes an http request.

When ConnectionManager receives the INIT message it will configure the WL1835/WL1837 as a BLE device using the Bluetopia APIs and start scanning for BLE devices. It also registers callbacks for the DEVM_Events which in this application are the Device Found and Properties Changed (on a connection) events as well as one for the GATT events which is the Handle Data event when a sensor measurement is received. The logic of the application is driven by these callbacks which will now be examined in more detail.

When the DEVM callback receives a detRemoteDeviceFound event it means a new BLE device MAC address has been found. There is a logical check that it is a SensorTag by checking that either it reports its DeviceName as "SensorTag" for CC2541 version or "CC2650 SensorTag" for CC2650 version. If this is true then a connection request is made.

A successful connection will be shown by another DEVM callback this time with the event detRemoteDevicePropertiesChanged. If the device is now marked as connected then it is added to the list of active sensors with function AddConnectedDeviceToSensorTable(). Now the sensor is connected a request is made to the sensor tag to start measurements on both the temperature and humidity sensors - the humidity data is currently reported to the PC but not plotted by the gui. The measurement requests are made using the information in the CC2541 GATT Server or from the CC2650 GATT Server.

The Temperature sensor is started with the following GATM writes

• 0x01 to address 0x29 to start temperature sensor

• 30 to address 0x2C to request a 100x10ms interval between measurements

• 0x00 0x01 to address 0x26 to request notifications every measurement - 1000ms in this case

The Humidity sensor is started with the following GATM writes

• 30 to address 0x42 to request a 100x10ms interval between measurements

• 0x01 to address 0x3F to start humidity sensor

• 0x00 0x01 to address 0x3C to request notifications every measurement - 1000ms in this case

Finally the callback restarts a background scan process which was stopped by the connection process. This allows new BLE devices to be added to the network via the same process

When the stack receives data events containing the requested sensor measurement data it triggers a GATM event. On the getGATTHandleValueData event the function AddSensorValueToSensorTable() uses the MAC of the BLE device and the GATT attribute of the data (temperature is 0x25 and humidity is 0x3B) to write the data and a timestamp to the correct location.

The BLE_App asks the ConnectionManager every 10 seconds for a copy of the sensor table so that it can write it to a formatted comma separated filed for parsing by the PC gui.