WL1835/WL1837-Wireless-Sensor-Gateway-Processor-SDK2.0

This page describes a project that implements a BLE sensor network gateway on an AM335x and WL1835MOD/WL1837MOD based on Processor SDK 2.0. As this is based on a 4.1.6 kernel the R8.5 WiLink drivers are already in the kernel. It will run on an AM335x EVM + WL1835MODCOM8/WL1837MODCOM8I or a BeagleBone Black + WL8 cape (WL1835 from CircuitCo or WL1837 from E14). The previous release with SDK8 is here

The AM335x runs the TI Bluetopia stack version 4.0.3 to provide a connection to up to 10 CC2650 BLE SensorTags which are periodically sending temperature and humidity data which are 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. The webserver runs a javascript that will visualise the sensor data in a browser. The webserver also has a page to enable headless provisioning of a Wi-Fi station to an existing AP using WiLink8's Multi-Role capability.

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.

This is version 2.1 for SDK2.0 which adds the browser based Wi-Fi provisioning interface.

History

v2.0 upgraded to latest Bluetopia release 4.0.3.0.1.0.

Creating the demo

The demo will be built from scratch using the supplied build scripts and patches on top of SDK 2.0.

Building the demo from scratch

The presumption for building this is that Linux Processor SDK2.0 has been installed to a Ubuntu build machine and that the Production License version of Bluetopia Bluetooth Stack (v4.0.3.0.1.0) has also been installed into the top level SDK directory. If this is a fresh install ensure that the SDK setup script ( ./setup.sh) is run to configure paths correctly. 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 overall build script for the system which includes the linux kernel and filesystem as well as the Bluetooth Low Energy sensor demo.

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.

There are two variables used to control the build process

E14CAPE

• Set to 1 to patch the kernel for E14 WL1837 Cape device tree
• Set to 0 to patch the kernel for CircuitCo WL1835 Cape device tree

If building for an EVM this variable is don't care as the default device tree file for the EVM supports the COM8 card.

ROOTFS_ON_SD

• Set to 0 to create a tar ball of the complete rootfs. This will be used first time in order to create the SD card.
• Set to 1 to get the build to update an existing SD card that is mounted in the host. This is a much faster process than writing the entire contents of the rootfs. Note that the variable FS must be changed to the correct mount point used by the host from the current /media/iain/rootfs.

Wi-fi

Processor SDK 2.0 uses a 4.1.6 kernel which has the mainline Wilink8 drivers. This means that the kernel space drivers for WL183x are built natively in the kernel. In order to get the appropriate user space tools such as crda, wpa_supplicant etc it is necessary to use the full SDK Arago rootfs image. The only change to the kernel build is to add support for one of the WiLink8 capes to the Beagle Bone Black Device Tree file.

Bluetooth Stack

The Bluetopia 4.0.3.x.y.z stack uses the device tree entry tibt to define the COM port, speed and GPIO used for the BT_EN signal.

As background 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.

Creating the sensor application code

The application code is created by copying and then patching one of the example applications in the directory ~/ti-processor-sdk-linux-am335x-evm-02.00.00.00/AM335xBluetopiaLinuxProduction-4.0.3.0.1.0. It runs the script

./create_ble_manager.sh

which will do following actions.

On the first run it will

• update the Bluetopia build/setup-bt and build/proj/toolchain-defs.mak files to ensure the paths and toolchain correspond to the Processor SDK2.0.
• update the build/proj files to add the new application to the makefiles and create all the environment variables required to build it

If the ble-app.created file has been deleted in the top level SDK directory it will

• create new application directory BluetopiaPM/sample/LinuxSensorGateway
• copy and rename the LinuxGATM_CLT.c file as ConnectionManage.c then patch it to create the core of the Sensor Gateway application. The patch file also contains the new source files BLE_App.c and OSLinux.x

Build the BLE Sensor Application

The application is now build as part of a full rebuild of Bluetopia. This will generate the executable bin/LinuxSensorGateway which is then copied to the target filesystem along with the bluetooth firmware file and configuration file systemConfig.txt.

In order to use the application in a customer system the target file /opt/ss1/Bluetopia/bin/systemConfig.txt must be edited. This is the file which defines which SensorTags can connect to the gateway 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 IR Temperature service has the 128 bit UUID F000AA00-0451-4000-B000-000000000000. The 16 bit UUID is AA00.

Install the run time scripts

Install the main shell script run.sh and its supporting configuration files. The script carries out the following tasks

• stops any existing lighttpd or thttpd service and restarts lighttpd 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 and the password “sensortag”.
• 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. This takes with the argument –f the file systemConfig.txt which lists all the Sensortags that are to be allowed to connect and which sensors on each are to be read.

Install the webpage to view the sensor data

The main web page index.html uses the open source plotly.js libraries to view the temperature and humidity values from up to 6 SensorTags. There is no limitation of 6, it just happens to be the number of sensortags listed in the supplied systemConfig.txt.

SensorTag

The demo was tested with CC2650SensorTags hw version 1.2.0 and SW v0.89.

Programming the SD card

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

$sudo ./bin/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 enter the FULL path to the built boot partition. eg /home/iain/ti-processor-sdk-linux-am335x-evm-02.00.00.00/tar-sensor-gateway-filesystem-e14/boot_partition.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 rootfs partition. eg /home/iain/ti-processor-sdk-linux-am335x-evm-02.00.00.00/tar-sensor-gateway-filesystem-e14/rootfs_partition.tar.gz

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

1. ./run.sh

The script calls LinuxSensorGateway 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 a 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 sequence of messages on the target similar to the following

LE Device Discovery Started.

Remote Device Found.
Bluetooth device found B0B448BE9805
Found B0B448BE9805 in configlist
DEVM_ConnectWithRemoteDevice() - in whitelist

Local Device Properties Changed. 

LE Device Discovery Stopped.

Remote Device Connection Status: B0B448BE9805, 0 (SUCCESS)

Remote Device Properties B0B448BE9805 Changed 1 mask 0x1008.
Flags: 40048001
Device is now connected but services not known
DEVM_QueryRemoteDeviceServices() succeed: 0, 0 bytes returned.

Remote Device B0B448BE9805 Services Status: LE, SUCCESS.

Remote Device Properties B0B448BE9805 Changed 1 mask 0x10008.
Flags: 40049001
Device is now connected and services known
DEVM_QueryRemoteDeviceServices() succeed: 1968, 1968 bytes returned.
3:C:78821
Found UUID AA20 at handle 39 valid 1
Found UUID AA00 at handle 31 valid 1
StartSensorMeasurements(): 39
DEVM_StartDeviceScan() Success: 0. 

• Open the webpage on the PC http://10.4.30.34 which will open the following page which graphs the data from the sensors. If a sensor stops sending data then the javascript will force the value back to 0 to highlight that the connection to that sensor is lost.

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. If the MAC address is listed in the systemConfig.txt file then a connection request is made.

A successful connection will be shown by another DEVM callback this time with the event detRemoteDevicePropertiesChanged. If this callback is for a device in the connected state then a call is made to query the device's services (ie report its GATT table). This is either a one or two step process depending upon whether the stack's cache already holds the list of services. If it doesn't, then the first call to DEVM_QueryRemoteDeviceServices() is to fill the cache with a second call to read the data out the cache into the application. Once the application has the Services Data it then calls the function GetGATTHandlesForRequestedUUIDs() which will take requested UUIDs from systemConfig.txt for that MAC address and then parse the Service Data to get the specific GATT addresses for each sensor UUID on that device. This abstracts the application from having to know the underlying GATT handles for any connected sensor. The GATT handles are then used to start the desired sensors on the device.

The example systemConfig.txt in the demo requests Temperature (AA00) and Humidity (AA20) data from each SensorTag

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 to write the data and a timestamp to the data table.

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 Javascript on the webpage.

Running the Provisioning Demo

This demo shows how the Multirole capability of WiLink8 provides a simple method for the provisioning of a headless system to a home Access Point. The WiLink8 is able to run an Access Point that the user can connect to called "SensorGateway" and with the password "sensortag". This connection is used to access the Provisioning web interface on the link http://10.4.30.34/provision.php. This web interface can then be used to scan and select the user Access Point that the WiLink8 station role should connect to in the normal mode of operation. This gives the page below.

Press the SCAN button. When the status "Scan completed" is shown then use the SSID drop down box to select the desired AP, enter its password and press CONNECT. Note that at the moment the webpage automatically refreshes every 10 seconds. This means that the data must be entered and the CONNECT button pressed within the 10s window otherwise the data is not written to file.

Once CONNECT button has been pressed the bottom box will show the status of the connection to the AP. When the association is completed the status will show that the station has connected to the selected AP and has been allocated an IP address by DHCP.

The Multi-Role capability allows the user's phone or tablet to maintain connection to the web server on the BBB during the time the BBB is trying to connect to the AP. This means that the user can get definitive feedback on whether the connection succeeded or failed as as well as information on where the failure occurred.