Poking at TI SensorTag CC2541 (Bluetooth LE devboard/gadget) from Linux

[RoGeorge]

Got a Bluetooth LE devboard from TI, back in the days when Bluetooth LE4.0 was still young.  The demo App was not running on my PC/phone, and the plethora of BLE specific acronyms was intimidating, and my mobile was not heaving BLE4.0 yet.  TL;DR never used it.

Last week I was looking for anything with a Bluetooth LE chip, and found this long forgotten SensorTag.  Attached 2xNiMH recheargeables instead of a CR2032, and got blink:



Nowadays BLE is ubiquitous, but getting docs and software for a gadget from 10 years ago will look more like an investigation then like a download. 

To make it more complicated, there were 2 similar devboards/gadgets from TI, both called SensorTag, with different SoC, first with CC2541, and the newer one with CC2560.  And the wiki TI website was discontinued, and the tools and/or examples were for Windows or iOS, not Linux.


The next applies for the first version of the TI SensorTag, the one with CC2541, and used from Linux (Kubuntu 22.04 LTS).

SensorTag is a small Bluetooth LE 4.0 gadget disguised as a TI devboard, so fully programmable and with published schematics, but also has a nice small enclosure to attach it to a key chain.  Powered from a CR2032 coin cell, and packed with sensors:
- gyroscope
- accelerometer
- magnetometer
- infra red thermometer (remote, non contact)
- hygrometer
- atmospheric pressure


Most of the TI links are all dead now, which is a shame.

Happily, some of the essential docs were captured by the Wayback Machine crawlers, and still available.  Got from there the SensorTag wiki page and a pdf with the GATT tables, which was just enough to read the sensors from Linux.


1.  Identify any BLE capable hardware on the computer

Code: [Select]

    # list usb BT dongles
    lsusb | grep -i blue

    # for more info
    lsusb -tvv

    # identify interface, mine was hci0
    ls -lA /sys/class/bluetooth/

    # list the capabilities of hci0
    sudo hciconfig -a hci0 features


2.  Plug a CR2032 battery into the SensorTag, press the lateral button (S1), and the SensorTag should start advertising its presence over Bluetooth LE 4.0 (also the green LED on the SensorTag should flash fast, after a while the SensorTag will stop advertising by itself).


3.  While the green LED on the SensorTag is keep flashing, scan for BLE devices

Code: [Select]

    sudo hcitool -i hci0 lescan
    # LE Scan...
    #     BC:6A:29:xx:xx:xx (unknown)
    #     BC:6A:29:xx:xx:xx SensorTag

BC:6A:29:xx:xx:xx is the Bluetooth LE MAC address of the SensorTag, it is a unique identifier of all the BLE devices ever made.  First 3 numbers tells the vendor, here BC:6A:29 means TI (Texas Instruments).  Last 3 (here masqueraded as xx:xx:xx for anonymity) is the not vendor specific, just a serial number.

Usually the computer will see many BLE devices at once.  The MAC address will be used later, to specify to which BLE device to connect to.  The xx:xx:xx has to be replaced with the numbers specific to your SensorTag while trying to connect, so to form the correct 6 bytes MAC address of your SensorTag.


4.  Connect to the sensor tag and interact with it

Code: [Select]

    gatttool -b BC:6A:29:xx:xx:xx --interactive
           [BC:6A:29:xx:xx:xx][LE]> connect
            Attempting to connect to BC:6A:29:AE:CE:3D
        # make sure the green LED on the SensorTag is flashing (advertising its presence)
        #       or else you won't see the next message and it won't work, if the LED is off, press the lateral button S1 on the SensorTag
            Connection successful

        # enable IR temperature sensor
        #       see the list of wat's available at
        #       /home/muuu/wd8TB/2019/Z/_hobby/devboards/SensorTag/TI/_BLE_SensorTag_GATT_Server.pdf
               
            [BC:6A:29::xx:xx:xx][LE]> char-write-cmd 0x29 01
       
        # read the IR temperature sensor (once), first 2 bytes are from the IR temperature
            [BC:6A:29::xx:xx:xx][LE]> char-read-hnd 0x25
            Characteristic value/descriptor: ac fe 80 0f
           
        # /* The IR Temperature sensor produces two measurements;
        # * Object ( AKA target or IR) Temperature,
        # * and Ambient ( AKA die ) temperature.
        # *
        # * Both need some conversion, and Object temperature is dependent on Ambient temperature.
        # *
        # * They are stored as [ObjLSB, ObjMSB, AmbLSB, AmbMSB] (4 bytes)
        # * Which means we need to shift the bytes around to get the correct values.
        # */           
           
        # eneble event notification from the IR temperature sensor (default is 1 read/second)
        #       the sensor was already enabled (char-write-cmd 0x29 01), so it will keep reading
       
            [BC:6A:29:xx:xx:xx][LE]> char-write-cmd 0x26 0100
            Notification handle = 0x0025 value: 95 fe 80 0f
            Notification handle = 0x0025 value: 96 fe 80 0f
            Notification handle = 0x0025 value: ac fe 80 0f
            Notification handle = 0x0025 value: f0 fe 80 0f
            Notification handle = 0x0025 value: b3 fe 80 0f
            Notification handle = 0x0025 value: a9 fe 80 0f
        #   ...
           
        # disable event notification from the IR temperature sensor       
            [BC:6A:29:xx:xx:xx][LE]> char-write-cmd 0x26 0000
            [BC:6A:29:xx:xx:xx][LE]> exit


5.  To do the same with gatttool in non-interactive mode (from the command line)

Code: [Select]

    sudo gatttool -i hci0 -b BC:6A:29:xx:xx:xx --char-write-req -a 0x26 -n 0100;   sudo gatttool -i hci0 -b BC:6A:29:xx:xx:xx --char-write-req -a 0x29 -n 01 --listen
            ...
            Characteristic value was written successfully
            Characteristic value was written successfully
            Notification handle = 0x0025 value: 73 fe a0 0f
            Notification handle = 0x0025 value: 84 fe a0 0f
            Notification handle = 0x0025 value: 94 fe a0 0f
            Notification handle = 0x0025 value: 84 fe a0 0f
            Notification handle = 0x0025 value: 86 fe a0 0f
            Notification handle = 0x0025 value: 81 fe a0 0f
            Notification handle = 0x0025 value: 80 fe a0 0f
            ^C


6.  Might be useful to take a peek at what it is exchanged, so at any time another terminal with a sniffer may be left running while issuing the above commands

Code: [Select]

    sudo btmon

Similar can be done with 'hcidump'

Code: [Select]

        sudo apt install bluez-hcidump
        sudo hcidump


Wayback Machine links to wiki and GATT table:
https://web.archive.org/web/20180918194512/http://processors.wiki.ti.com/index.php/SensorTag_User_Guide
https://web.archive.org/web/20181105060152/http://processors.wiki.ti.com/images/a/a8/BLE_SensorTag_GATT_Server.pdf

https://www.ti.com/lit/ug/swru324b/swru324b.pdf