Skip to content
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.

Sign up for GitHub

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

Jump to bottom

[DISC] Add BT scan duration parameter auto discovery #1762

Merged
merged 2 commits into from
Sep 30, 2023
Merged

[DISC] Add BT scan duration parameter auto discovery #1762

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
29e02b8
[DISC] Add BT scan duration parameter auto discovery
1technophile Sep 28, 2023
727bfcd
Add doc
1technophile Sep 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 15 additions & 28 deletions docs/use/ble.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ So as to keep your white/black list persistent you can publish it with the retai
`mosquitto_pub -r -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"white-list":["01:23:14:55:16:15","4C:65:77:88:9C:79","4C:65:A6:66:3C:79"]}'`
:::

## Setting the time between BLE scans and force a scan
## Setting the time between BLE scans and force a scan (available with HA discovery)

If you want to change the time between readings you can change the interval by MQTT.
For example, if you want the BLE to scan every 66 seconds:
Expand Down Expand Up @@ -136,33 +136,29 @@ In this case you should deactivate the BLE connection mechanism to avoid concurr
For certain devices like LYWSD03MMC OpenMQTTGateway use a connection (due to the fact that the advertized data are encrypted), this connection mechanism is launched after every `TimeBtwConnect` per default, you can modify it by following the procedure below.
:::

## Setting the time between connection attempts
## Setting the time between connection attempts (default: 60min, available with HA discovery)

If you want to change the time between BLE connect you can change it by MQTT, if you want the BLE connect time to be every 300s:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"intervalcnct":300000}'`

## Setting if the gateway publishes all the BLE devices scanned or only the detected sensors (default: false)
## Setting if the gateway publishes all the BLE devices scanned or only the detected sensors (default: false, available with HA discovery)

If you want to change this characteristic:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"onlysensors":true}'`

::: tip
With Home Assistant, this command is directly available through MQTT auto discovery as a switch into the HASS OpenMQTTGateway device entities list.
:::

The gateway will publish only the detected sensors like Mi Flora, Mi jia, LYWSD03MMC... and not the other BLE devices. This is useful if you don't use the gateway for presence detection but only to retrieve sensors data.

## Setting if the gateway publishes known devices which randomly change their MAC address
## Setting if the gateway publishes known devices which randomly change their MAC address (default: false)

The default is false, as such changing MAC addresses cannot be related to specific devices.

If you want to change this characteristic:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"randommacs":true}'`

## Setting if the gateway use adaptive scanning
## Setting if the gateway use adaptive scanning (default: true, available with HA discovery)

Adaptive scanning lets the gateway decide for you the best passive `interval` and active `intervalacts` scan interval, depending on the characteristics of your devices.
The gateway retrieves your devices' information from [Theengs Decoder](https://decoder.theengs.io) and adapts its parameters accordingly if a device that requires it is detected.
Expand All @@ -174,10 +170,6 @@ If you want to change this characteristic (default:true):

Setting Adaptive scanning to `false` will automatically put the gateway to continuous active scanning if no additional manual changes have already been applied.

::: tip
With Home Assistant, this command is directly available through MQTT auto discovery as a switch into the HASS OpenMQTTGateway device entities list.
:::

An overview with background information to better understand the different setting used:

**Passive scanning:** With this scanning mode the gateway picks up any freely available broadcasts sent out by devices, without any interaction with the devices. The interval for this is set with [{"interval":66000}](#setting-the-time-between-ble-scans-and-force-a-scan)
Expand All @@ -190,31 +182,27 @@ If adaptive scanning is set to false and you want to manually set these interval

**"acts":true** - the device requires active scanning to broadcast all of it's data for decoding.

## Setting the time between active scanning
## Setting the time between active scanning (available with HA discovery)

If you have passive scanning activated, but also have some devices which require active scanning, this defines the time interval between two intermittent active scans.

If you want to change the time between active scans you can change it by MQTT. For setting the active scan interval time to every 5 minutes:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"intervalacts":300000}'`

## Setting the duration of a scan
## Setting the duration of a scan (available with HA discovery)

If you want to change the default 10 sec duration of each scan cycle to 5 seconds
If you want to change the default duration of each scan cycle to 5 seconds

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"scanduration":5000}'`

## Setting if the gateway connects to BLE devices eligibles on ESP32
## Setting if the gateway connects to BLE devices eligibles (default: true, available with HA discovery)

If you want to change this characteristic:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"bleconnect":false}'`

::: tip
With Home Assistant, this command is directly available through MQTT auto discovery as a switch into the HASS OpenMQTTGateway device entities list.
:::

## Setting if the gateway publish into Home Assistant Home presence topic
## Setting if the gateway publish into Home Assistant Home presence topic (default: false, available with HA discovery)

If you want to publish to Home Assistant presence topic, you can activate this function by the HASS interface (this command is auto discovered), [here is a yaml example](../integrate/home_assistant.md#mqtt-room-presence).
Or by an MQTT command.
Expand All @@ -235,7 +223,7 @@ To:
`{"id":"1de4b189115e45f6b44e509352269977","mac_type":1,"rssi":-78,"distance":7.85288,"brand":"GENERIC","model":"iBeacon","model_id":"IBEACON","mfid":"4c00","uuid":"1de4b189115e45f6b44e509352269977","major":0,"minor":0,"txpower":-66,"mac":"60:87:57:4C:9B:C2"}`
Note: the MAC address is put in "mac" field.

## Setting if the gateway uses iBeacon UUID as topic, instead of (random) MAC address
## Setting if the gateway uses iBeacon UUID as topic, instead of (random) MAC address (default: false)

By default, iBeacon are published like other devices, using a topic based on the MAC address of the sender.
But modern phones randomize their Bluetooth MAC address making it difficult to track iBeacon.
Expand All @@ -256,7 +244,7 @@ home/OpenMQTTGateway/BTtoMQTT/1de4b189115e45f6b44e509352269977 {"id":"52:10:A8:4
home/OpenMQTTGateway/BTtoMQTT/1de4b189115e45f6b44e509352269977 {"id":"7B:63:C6:82:DC:57","mac_type":1,"rssi":-83,"brand":"GENERIC","model":"iBeacon","model_id":"IBEACON","mfid":"4c00","uuid":"1de4b189115e45f6b44e509352269977","major":0,"minor":0,"txpower":-66}
```

## Setting the minimum RSSI accepted to publish device data
## Setting the minimum RSSI accepted to publish device data (default:-100)

If you want to change the minimum RSSI value accepted for a device to be published, you can change it by MQTT. For example if you want to set -80

Expand Down Expand Up @@ -345,9 +333,8 @@ Response:
::: tip
The `ttl` parameter is the number of attempts to connect (defaults to 1), which occur after the BLE scan completes.
`value_type` can be one of: STRING, HEX, INT, FLOAT. Default is STRING if omitted in the message.
:::

## SwitchBot Bot control
## SwitchBot Bot control (available with HA discovery)

SwitchBot Bot devices are automatically discovered and available as a device in the configuration menu of home assistant.

Expand Down Expand Up @@ -384,15 +371,15 @@ To change the default external decoder topic to "undecoded":

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"extDecoderTopic":"undecoded"}'`

## ADVANCED: Filtering out connectable devices
## ADVANCED: Filtering out connectable devices (default: false)

[With OpenHAB integration](../integrate/openhab2.md), this configuration is highly recommended, otherwise you may encounter incomplete data.

If you want to enable this feature:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"filterConnectable":true}'`

## ADVANCED: Advertisement and advanced data (default: false)
## ADVANCED: Advertisement and advanced data (default: false, available with HA discovery)

If you want to enable this feature:

Expand Down
9 changes: 9 additions & 0 deletions main/ZmqttDiscovery.ino
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1146,6 +1146,15 @@ void pubMqttDiscovery() {
"", "", "", "", false, // device name, device manufacturer, device model, device ID, retain
stateClassNone //State Class
);
createDiscovery("number", //set Type
subjectBTtoMQTT, "BT: Scan duration", (char*)getUniqueId("scanduration", "").c_str(), //set state_topic,name,uniqueId
will_Topic, "", "{{ value_json.scanduration/1000 }}", //set availability_topic,device_class,value_template,
"{\"scanduration\":{{value*1000}},\"save\":true}", "", "s", //set,payload_on,payload_off,unit_of_meas,
0, //set off_delay
Gateway_AnnouncementMsg, will_Message, true, subjectMQTTtoBTset, //set,payload_available,payload_not available,is a gateway entity, command topic
"", "", "", "", false, // device name, device manufacturer, device model, device ID, retain
stateClassNone //State Class
);
createDiscovery("button", //set Type
will_Topic, "BT: Force scan", (char*)getUniqueId("force_scan", "").c_str(), //set state_topic,name,uniqueId
will_Topic, "", "", //set availability_topic,device_class,value_template,
Expand Down
Loading