Bluetooth

February 1, 2025 · View on GitHub

This module contains three bluetooth sensors:

bt.btle_sensor.BtleSensor
bt.btscan_sensor.SimpleBtSensor
bt.govee_sensor.GoveeSensor

Find address for Bluetooth device

If the device address is unknown, select the method to determine it depending on the Bluetooth type.

Regular Bluetooth device

Make sure the Bluetooth device is visible (e. g. in pairing mode), then run:

hcitool scan

The output lists all visible Bluetooth devices as address / name pairs.

Bluetooth low energie device (BTLE)

Use this method for Bluetooth 4.0 devices. Make sure the Bluetooth device is active (switched on), then run:

sudo hcitool lescan

The output will be a address / name pairs for each BTLE message received. After discovering the desired address hit ctrl + c to stop the output.

A Polling Sensor that listens for BTLE broadcasts from devices with a given BT address for a short time on each poll. When a packet for a device of interest is received during that period, the ON value is published to the destination associated with the device address. When no packet is received for a device of interest, the OFF value is published.

Dependencies

This sensor uses bluepy to receive and parse the BTLE packets. It depends also on the packages libglib2.0-dev and bluetooth. Network capabilities must be granted to the bluepy-helper executable, so it can access the Bluetooth hardware.

cd /srv/sensorReporter
sudo ./install_dependencies.sh bt
sudo setcap 'cap_net_admin+ep' $(find -name bluepy-helper)

Parameters

Parameter	Required	Restrictions	Purpose
`Class`	X	`bt.btle_sensor.BtleSensor`
`Connections`	X	dictionary of connectors	Defines where to publish the sensor status for each connection. Look at connection readme's for 'Actuator / sensor relevant parameters' for details.
`Level`		DEBUG, INFO, WARNING, ERROR	When provided, sets the logging level for the sensor.
`Poll`	X	A number in seconds, greater than `Timeout`	How often to poll for broadcasts.
`Timeout`	X	A number in seconds	How long to listen for BTLE packets during a single poll.
`AddressX`	X	BT MAC address format (i.e A1:B2:C3:E4:F5:67)	The MAC address of a device to listen for broadcasts from. X must be a number starting from 1 and each subsequent address must be sequential in numbering.
`Values`		list of strings or dictionary	Values to replace the default state message for all outputs (default is ON, OFF). For details see below.

Values parameter

With this parameter the default state messages for all output can be overwrite. Two different layouts are possible. To override the state message for all defined connections, configure a list of two string items:

Values:
    - 'ON'
    - 'OFF'

The fist string will be send if the configured address is detected, the second if not.

If separate state messages for each connection are desired, configure a dictionary of connection names containing the string item list:

Values:
    <connection_name>:
        - 'ON'
        - 'OFF'
    <connection_name2>:
        - 'high'
        - 'low'

If a configured connection is not present in the Values parameter it will use the sensor default state messages (ON, OFF).

Output

The BtleSensor can have 1 or many outputs depending on how many addresses are defined. These can be configured within the 'Connections' section (Look at connection readme's for 'Actuator / sensor relevant parameters' for details). When using with the openHAB connection configure a switch/string item.

Output	Purpose
`DestinationX`	Where to send send the presence state (default send ON when the device is present and OFF when not). `X` is a number starting with 1 and incrementing to list more than one device.

Example Config

Logging:
    Syslog: yes
    Level: INFO

Connection1:
    Class: openhab_rest.rest_conn.OpenhabREST
    Name: openHAB
    URL: http://localhost:8080
    RefreshItem: Test_Refresh

SensorBtleScanner:
    Class: bt.btle_sensor.BtleSensor
    Poll: 10
    Connections:
        openHAB:
            Destination1:
                Item: dev1
            Destination2:
                Item: dev2
            Destination3:
                Item: dev3
    Timeout: 9
    Address1: aa:bb:cc:dd:ee:ff
    Address2: 11:22:33:44:55:66
    Address3: 77:88:99:aa:bb:cc
    Values:
        - present
        - away
    Level: DEBUG

`bt.btscan_sensor.SimpleBtSensor`

A Polling Sensor that polls BT devices by MAC address to determine if they are present or not.

Look at the PyBluez examples for inquiry.py for a script that can be used to discover the MAC address of a device. Run the script and put the device into pairing mode and the MAC address and device name will be printed out.

Dependencies

The sensor uses PyBluez to scan for BT devices. It depends also on the packages bluetooth and bluez

cd /srv/sensorReporter
sudo ./install_dependencies.sh bt

Parameters

Parameter	Required	Restrictions	Purpose
`Class`	X	`bt.btscan_sensor.SimpleBtSensor`
`Connections`	X	dictionary of connectors	Defines where to publish the sensor status for each connection. Look at connection readme's for 'Actuator / sensor relevant parameters' for details.
`Level`		DEBUG, INFO, WARNING, ERROR	When provided, sets the logging level for the sensor.
`Poll`	X	A number in seconds, greater than 25	How often to poll for devices, blocks for 25 seconds.
`AddressX`	X	BT MAC address format (i.e A1:B2:C3:E4:F5:67)	The MAC address of a device to scan for it's presence. `X` is a number starting with 1 and incrementing to list more than one device.

Output

The SimpleBtSensor can have 1 or many outputs depending on how many addresses are defined. These can be configured within the 'Connections' section (Look at connection readme's for 'Actuator / sensor relevant parameters' for details). When using with the openHAB connection configure a switch/string item.

Output	Purpose
`DestinationX`	Where to send send ON then the device is present and OFF when not. `X` is a number starting with 1 and incrementing to list more than one device.

Example Config

Logging:
    Syslog: yes
    Level: INFO

Connection1:
    Class: openhab_rest.rest_conn.OpenhabREST
    Name: openHAB
    URL: http://localhost:8080
    RefreshItem: Test_Refresh

SensorMyPhone:
    Class: bt.btscan_sensor.SimpleBtSensor
    Poll: 26
    Connections:
        openHAB:
            Destination1:
                Item: phone1
            Destination2:
                Item: phone2
    Address1: aa:bb:cc:dd:ee:ff
    Address2: 11:22:33:44:55:66
    Level: DEBUG

`bt.govee_sensor.GoveeSensor`

A Background Sensor that listens for and parses BTLE packets from Govee H5075 temperature and humidity sensors, publishing the readings and device status information.

Dependencies

This sensor uses the bleson library to listen for and parse the packets. Network capabilities must be granted to the python3 executable, so it can access the Bluetooth hardware.

cd /srv/sensorReporter
sudo ./install_dependencies.sh bt
sudo setcap 'cap_net_raw,cap_net_admin+ep' $(readlink -f $(find -name python3))

Parameters

Parameter	Required	Restrictions	Purpose
`Class`	X	`bt.govee_sensor.GoveeSensor`
`Connections`	X	dictionary of connectors	Defines where to publish the sensor status for each connection. This sensor has 5 outputs, see below. Look at connection readme's for 'Actuator / sensor relevant parameters' for details.
`Level`		DEBUG, INFO, WARNING, ERROR	When provided, sets the logging level for the sensor.
`TempUnit`		`F` or `C`	The temperature units. Default is `C`
`Address`	X	BT MAC address format (i.e a4:c1:38:e4:f5:67)	The MAC address of the Govee H5075 sensor. Should start with "a4:c1:38".

If the address is unknown use the example config and check the sensor_reporter log for debug messages with the UUID GV5072_

Outputs

The GoveeSensor has 5 outputs which can be configured within the 'Connections' section (Look at connection readme's for 'Actuator / sensor relevant parameters' for details).

Output	Purpose
`Temperature`	Where to publish the temperature.
`Humidity`	Where to publish the humidity.
`Battery`	Where to publish the battery charge (integer between 0 and 100)
`RSSI`	Where to publish the signal strength (integer between 0 and -100)
`DeviceName`	Where to publish the self reported name. Usually GVH5072_XXXX

Example Config

Logging:
    Syslog: yes
    Level: INFO

Connection1:
    Class: mqtt.mqtt_conn.MqttConnection
    Name: MQTT
    Client: test
    User: user
    Password: password
    Host: localhost
    Port: 1883
    Keepalive: 10
    RootTopic: sensor_reporter
    TLS: NO

SensorGoveeKitchen:
    Class: bt.govee_sensor.GoveeSensor
    Connections:
        MQTT:
            Temperature:
                StateDest: govee/temp
            Humidity:
                StateDest: govee/humid
            Battery:
                StateDest: govee/battery
            RSSI:
                StateDest: govee/rssi
            DeviceName:
                StateDest: govee/uuid
    TempUnit: F
    Address: a4:c1:38:00:00:00
    Level: DEBUG

Given the above configuration, the battery level would be reported to sensor_reporter/govee/battery.