Skip to content

ble-pasv-mqtt-gw overhaul #158

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

michalk-k
Copy link

@michalk-k michalk-k commented Jun 22, 2025

ble pasv mqtt gw overhaul

This PR introduces several changes, including fixes, refactors, and new features. All are focused on Discovery while BLE code remains untouched (almost... support of multi-button devices has required some touches)

Major changes:

New features

  1. Added support for Shelly Door/Window BLE, Buttons BLE (H&T, RC Button 4 etc.)
    • Buttons are reported with the use of MQTT events
  2. Added MACs filtering (incl option to use KVS)
  3. Added (optional) Manufacturer/Model,
  4. Added connections, identifiers, and via_device to the MQTT discovered device
  5. Debug to the console, helping in adding a new device (enabled by default, with an option to disable it)

Improvements

  1. Fixed Celsius units
  2. Fixed sensors possibly changing their topic (see breaking changes)
  3. Fixed window state and tilt turned unknown when restarting HA
    • It's because BLE devices don't always report these attributes, so after HA restart, they are missing from the retained message
  4. Rotation state renamed to Tilt
  5. Window state renamed to Contact, and window class renamed to Opening. Both to allow better flexibility (ie for doors)
  6. optimizations
    • The device is rendered for a processed device only once
    • More abbreviations used within MQTT discovery
  7. More detailed documentation

image

Breaking changes:

The data are no longer stored in sensor, telemetry, and status topics. The new common topic is data.

It will not impact users who rely on discovery

Click for details There are multiple reasons for that:
  1. Reported values may belong to different classes, for example, temperature -> sensor, RSSI -> telemetry.
  2. The first message determines creation of MQTT discovery objects incl. data topic. A different set of sensors in subsequent messages might cause pointing to a different topic
  3. Sensors don't guarantee that all their values are reported at once. For example, RSSI might be reported with a button, or with temperature (case of Shelly H&T BLE)

It turns out that depending on the combination of values in the event, particular values might got their topic changed as time goes by.

Changed naming schema

  • Devices will be named with the format: mac-model or mac if the model is not provided
  • Names of discovered entities will be set to device class, ie temperature. Then HA will create entity_id based on mac-model devclass , for example (sensor.xxxxxxxxx_ht_temperature)
  • unique_id of entities is set to mac-type (xxxxxxxxx-window) or mac-type-index (xxxxxxxxxxx-button-2)
Click for details Change to the naming aligns final device and entity names with Home Assistant standards.

HA will name the entity to devicename name, for example: 1a2b3c4d5e6f-H&T BLU Temperature. Then, renaming the device gives an option to automatically rename entities in order to follow the device name change. For example, changing the name of the device to PCROOM HT will (after confirmation) turn the entity name into PCROOM HT Temperature.

On top of that, some HA pages (ie, device view) can strip the device name out of the entity name, making them shorter and less cluttered.

michalk-k and others added 3 commits June 15, 2025 15:27
1. Fixed Celsius units. The correct is: °C
2. Added binary sensors supporting DW BLU and Motion BLU
3. DW State and tilt stored in dedicated, retained topics (to prevent unknown state after HA restart when most recent telementry didn't reported them)
4. Added option to process only devices provided in `allowed_devices` struct (incl. KVS)
5. The structure might contain a manufacturer and model, in order to store them into Discovery topics
6. Added via_device to the discovered device, reporting BLE proxy device mac address
7. Added mac address of BLE device to the discovered device
8. rotation renamed to tilt (in HA entities)
9. window class changed to opening to make it more universal (ie windows, doors)
10. window binary state named contact to support both doors and windows, otherwise HA generates senseless names,
11. changed default device name to macaddress[-modelname]
12. added debug (default: true). Helps to find mac of the new device
13. set mqtt_src to id-name (attributes of Shelly DEVICE_INFO)
option to report as mqtt_event (prefered) or device_trigger
1. Fixed Celsius units. The correct is: °C
2. Added binary sensors supporting DW BLU and Motion BLU
3. Added MQTT events to support buttons (incl. multi-button devices)
4. DW State and tilt are stored in dedicated, retained topics (to prevent unknown state after HA restart when the most recent telemetry didn't reported them)
5. Added option to process only devices provided in `allowed_devices` struct (within script and/or KVS)
6. The structure might contain the manufacturer and model names, in order to pass them in the Discovery topics
7. Added via_device to the discovered device, reporting the MAC address of the proxying device
8. Added the MAC address of BLE device to the discovered device
9. Rotation renamed to tilt (in HA entities)
10. Changed the window class to opening one, to make it more universal (ie windows, doors)
11. A window binary state named contact to support both doors and windows; otherwise, HA generates senseless names
12. changed default device name to macaddress[-modelname]
13. added debug (default: true). Helps to find the MAC of the new device
14. set mqtt_src to id-name (attributes of Shelly DEVICE_INFO)
@michalk-k michalk-k changed the title Ble pasv mqtt gw refactor ble-pasv-mqtt-gw overhaul Jun 22, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant