Reading Bluetooth LE (BLE) sensor data advertisements in CircuitPython

 Bluetooth Sensors -- reading the Govee H5074 advertisement data

Reading Bluetooth LE (BLE) sensor data from CircuitPython isn't always obvious. In this example, I show how I pull data from the Govee H5074 Bluetooth sensor. The sensor is a small, battery-powered sensor that reads the temperate and humidity and transmits it inside of Bluetooth advertisements.

The code is all up on Github. You'll want to look in the code directory at the GoveeScanner.py file. There's also a Govee5074.py file which can parse an advertisement once it's been seen, and a GoveeDisplay.py file that can display the data to an E-Ink display.

Go look at the file now!

The key to the code is a pair of methods: the Scan() method and the ScanOnce() method. ScanOnce will start a scan ble.start_scan(timeout=...) . In practice, I use very short timeouts (.1 second) but then do a bunch of them in a loop in the Scan method. The start_scan returns a  generator, which is like a list but the contents will flow in over time. The contents will be both advertisements and advertisement scan responses. A scan response is like additional data in the advertisement, but it only comes in when it's requested. The request will be automatic; we don't have to do anything to request a scan_response.

The Govee sensor data is send in the scan_response, in what's called the "Manufacturer Data" section.

The critical thing to know is that the two values -- the advertisements and scan_responses -- aren't linked together by CircuitPython. We have to do that ourselves, and we do it by saving the advertisements in a dictionary that's indexed by the Bluetooth address.

  

The advertisements will have the name of the device. We're looking just for Govee H5074. In the code at about line 88 we look for the complete_name :

            name = advert.complete_name

            if (name is not None) and ("Govee_H5074" in name):

                # print("TRACE: 30: Found main govee advert", advert.address, name)

                goveeAdverts[advert.address] = advert

If the device is one we want, then we save away the advert in the goveeeAdverts dictionary, indexed by the Bluetooth address. This is critical because when we see an advertisement scan_response, we actually don't get the name but we do get the address.

The other part of the ScanOnce method is reading the scan responses. We filter first based on whether it's a response we want (we'll get lots of responses from lots of devices, but we only care about the Govee H5074 devices here).

            if advert.scan_response:

                # Check to make sure that this response address is in the list

                # of adverts that have the right name ("Govee_H5074...")

                # You can't tell from just the response advert; you need the

                # original advert, too.

                if advert.address not in goveeAdverts:

                    # very frequent -- set is only govee adverts, but the

                    # scan_response can be for anything

                    # print("TRACE: 15: not in set", advert.address)

                    continue

Once we know it's a scan_response we want, we pull out the manufacturer data and parse it. If it parses OK, then we prepare to return it.

                MANUFACTURER_SECTION = 0xFF  # Per Bluetooth SIG

                if (MANUFACTURER_SECTION in advert.data_dict):

                    annunciator.Found()

                    buffer = advert.data_dict[MANUFACTURER_SECTION]

                    g5074 = Govee5074(buffer)

                    if (g5074.IsOk):

                        annunciator.Read()

                        if retval is None:  # only print the first one

                            print("TRACE: 28: GOT DATA", g5074)

                        retval = g5074

The annunciator is the code that lets the user know what's going on. "Read" is an indication that we've read the data OK.

TL/DR: when reading Bluetooth advertisements, be sure to check the scan_responses too, because that's where the data might be.