[DOCS] Improbe BLE gateway guide (#1530)
Add images, intro and reorganize sections
This commit is contained in:
Florian authored and GitHub committed
1 parent
50e80f0239
commit
3ceb19f7be
5 files changed
+89
-91
No files matched your search
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 106 KiB |
@@ -84,7 +84,7 @@ Added to that it retrieves the measures from the devices below. By default the d
|
||||
| ThermoPro|TP393|temperature/humidity|
|
||||
| TPMS|TPMS|temperature/pressure/battery/alarm/count|
|
||||
| Vegtrug||temperature/moisture/luminance/fertility|
|
||||
| XIAOMI Mi Flora|HHCCJCY01HHCC|temperature/moisture/luminance/fertility/battery(c)|
|
||||
| XIAOMI Mi Flora|HHCCJCY01HHCC|temperature/moisture/luminance/fertility/battery(c) firmware >3.1.8|
|
||||
| XIAOMI Ropot|HHCCPOT002|temperature/moisture/fertility|
|
||||
| XIAOMI Mi Jia|LYWSDCGO|temperature/humidity/battery|
|
||||
| XIAOMI Mi Jia|LYWSD02|temperature/humidity/battery|
|
||||
|
||||
+88
-90
@@ -1,69 +1,33 @@
|
||||
# BLE gateway
|
||||
|
||||
::: warning
|
||||
We strongly encourage the use of a white-list (see below) so as to collect data from your devices only and not from other MAC addresses.
|
||||
By default the gateway scans the advertizing BLE devices nearby with their MAC addresses. Depending on your country, it may be illegal to monitor networks for MAC addresses, especially on networks that you do not own. Please check your country's laws (for US Section 18 U.S. Code § 2511) - [discussion here](https://github.com/schollz/howmanypeoplearearound/issues/4).
|
||||
:::
|
||||
The manufacturer agnostic BLE gateway acts as a powerful BLE scanner of devices and decoder, allowing you to visualize and analyze information from a wide range of BLE devices.
|
||||
It can also act as a presence detection gateway by reading the nearby BLE tags or tracker devices.
|
||||
|
||||
## Receiving signals from BLE beacon devices for Presence detection
|
||||
Data are transmitted to an MQTT broker, where it can be used to trigger events and rules, as well as displayed, stored and processed in your favorite controller.
|
||||
|
||||
Subscribe to all the messages with mosquitto or open your MQTT client software:
|
||||
With the ability to monitor and analyze data such as temperature, humidity, moisture, luminance, weight, pressure, fine particles, and more, the BLE gateway provides a flexible and customizable solution for integrating BLE technology into your control and monitoring systems.
|
||||
|
||||
` sudo mosquitto_sub -t +/# -v`
|
||||
|
||||
_NOTE: HM-10 or HM-11 module needed if you are not using ESP32; configure in `User_config.h`_
|
||||
|
||||
The BT gateway module for OpenMQTTGateway enables the detection of BLE beacons and their signal strength. Generally BLE devices will not broadcast if they are paired so you may need to ensure your beacons is unpaired before it will be seen by the gateway.
|
||||
|
||||
If beacons are detected the gateway will periodically publish messages to MQTT (beacons must not be paired, see above):
|
||||
|
||||
```
|
||||
home/OpenMQTTGateway/BTtoMQTT/45E174126E00 {"id":"45:e1:74:12:6e:00","rssi":-89,"distance":21.51847,"servicedata":"fe0000000000000000000000000000000000000000"}
|
||||
```
|
||||
```
|
||||
home/OpenMQTTGateway/BTtoMQTT/C7FaaD132C00 {"id":"c7:fa:ad:13:2c:00","rssi":-68,"distance":2.799256,"servicedata":"drfgdrgdsrgesrdgdrgdregesrgtrhtyhtfyhdtyhh"}
|
||||
```
|
||||
|
||||
The subtopic after `home/BTtoMQTT/` is the MAC address of the Bluetooth low energy beacon. The rssi value is the [RSSI signal level](https://www.metageek.com/training/resources/understanding-rssi.html) from which you may deduce the relative distance to the device.
|
||||
Consider the distance as a beta feature as currently we are not retrieving the emitting power of the beacon to make it more accurate.
|
||||
|
||||
Note that you can find apps to simulate beacons and do some tests like [Beacon simulator](https://play.google.com/store/apps/details?id=net.alea.beaconsimulator)
|
||||
|
||||
iOS version >=10 devices advertise without an extra app MAC address, nevertheless this address [changes randomly](https://github.com/1technophile/OpenMQTTGateway/issues/71) and cannot be used for presence detection. You must install an app to advertise a fixed MAC address.
|
||||
|
||||
|
||||
|
||||
## Receiving signals from BLE devices Mi Flora, Mi jia, LYWDS02, LYWSD03MMC, ClearGrass, Mi scale and [many more](https://compatible.openmqttgateway.com/index.php/devices/ble-devices/)
|
||||
So as to receive BLE sensors data you need a simple ESP32
|
||||
The mi flora supported firmware is >3.1.8
|
||||
## Receiving signals from [compatible BLE sensors](https://decoder.theengs.io/devices/devices_by_brand.html) to publish it to an MQTT broker.
|
||||
To receive data from BLE sensors you can use an ESP32-based device with a programming USB port or use a Serial adapter.
|
||||
|
||||
Verify that your sensor is working with the App and update it with the last software version.
|
||||
You should see in your MQTT broker the following data:
|
||||
|
||||
OpenMQTTGateway is also available preloaded and configured with the [Theengs plug](https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption), a smart plug that acts as a BLE gateway and energy monitoring device.
|
||||
|
||||
Note that the gateway return one or two measurement value each time. The different measures depending on the devices are:
|
||||
* Lux
|
||||
* Temperature
|
||||
* Moisture
|
||||
* Fertilization
|
||||
* Humidity
|
||||
* Pressure
|
||||
* Steps
|
||||
* Weight
|
||||
* Impedance
|
||||
* Battery
|
||||
* Voltage
|
||||
* Open
|
||||
* Presence
|
||||
1. Follow the [Upload](../upload/web-install.md) and [Configuration](../upload/portal.md) steps.
|
||||
|
||||
The infos will appear like this on your MQTT broker:
|
||||
1. Download an MQTT client like MQTT explorer.
|
||||
|
||||
`home/OpenMQTTGateway/BTtoMQTT/4C33A6603C79 {"hum":"52.6","tempc":"19.2","tempf":"66.56"}`
|
||||
1. You should see data coming in your broker.
|
||||
|
||||
More info are available on [my blog](https://1technophile.blogspot.fr/2017/11/mi-flora-integration-to-openmqttgateway.html)
|
||||
|
||||
|
||||
::: tip
|
||||
OpenMQTTGateway publish the servicedata field of your BLE devices.
|
||||
:::
|
||||
Once the data has been transmitted to the MQTT broker, it can be easily integrated with your preferred controller. For example, the data can be automatically discovered and made available within popular controllers, example below with Home Assistant.
|
||||
|
||||
|
||||
|
||||
Examples of compatible sensors among [our list](https://decoder.theengs.io/devices/devices_by_brand.html: Mi Flora, Mi jia, LYWDS02, LYWSD03MMC, ClearGrass, Mi scale, iBBQ, TPMS
|
||||
|
||||
## Setting a white or black list
|
||||
A black list is a list of MAC addresses that will never be published by OMG
|
||||
@@ -194,6 +158,33 @@ If you want to change this characteristic:
|
||||
With Home Assistant, this command is directly available through MQTT auto discovery as a switch into the HASS OpenMQTTGateway device entities list.
|
||||
:::
|
||||
|
||||
## Receiving signals from BLE beacon devices for Presence detection
|
||||
|
||||
Subscribe to all the messages with mosquitto or open your MQTT client software:
|
||||
|
||||
` sudo mosquitto_sub -t +/# -v`
|
||||
|
||||
_NOTE: HM-10 or HM-11 module needed if you are not using ESP32; configure in `User_config.h`_
|
||||
|
||||
The BT gateway module for OpenMQTTGateway enables the detection of BLE beacons and their signal strength. Generally BLE devices will not broadcast if they are paired so you may need to ensure your beacons is unpaired before it will be seen by the gateway.
|
||||
|
||||
If beacons are detected the gateway will periodically publish messages to MQTT (beacons must not be paired, see above):
|
||||
|
||||
```
|
||||
home/OpenMQTTGateway/BTtoMQTT/45E174126E00 {"id":"45:e1:74:12:6e:00","rssi":-89,"distance":21.51847,"servicedata":"fe0000000000000000000000000000000000000000"}
|
||||
```
|
||||
```
|
||||
home/OpenMQTTGateway/BTtoMQTT/C7FaaD132C00 {"id":"c7:fa:ad:13:2c:00","rssi":-68,"distance":2.799256,"servicedata":"drfgdrgdsrgesrdgdrgdregesrgtrhtyhtfyhdtyhh"}
|
||||
```
|
||||
|
||||
The subtopic after `home/BTtoMQTT/` is the MAC address of the Bluetooth low energy beacon. The rssi value is the [RSSI signal level](https://www.metageek.com/training/resources/understanding-rssi.html) from which you may deduce the relative distance to the device.
|
||||
Consider the distance as a beta feature as currently we are not retrieving the emitting power of the beacon to make it more accurate.
|
||||
|
||||
Note that you can find apps to simulate beacons and do some tests like [Beacon simulator](https://play.google.com/store/apps/details?id=net.alea.beaconsimulator)
|
||||
|
||||
iOS version >=10 devices advertise without an extra app MAC address, nevertheless this address [changes randomly](https://github.com/1technophile/OpenMQTTGateway/issues/71) and cannot be used for presence detection. You must install an app to advertise a fixed MAC address.
|
||||
|
||||
|
||||
## Setting if the gateway publish into Home Assistant Home presence topic
|
||||
|
||||
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).
|
||||
@@ -248,43 +239,6 @@ you can also accept all the devices by the following command:
|
||||
|
||||
The default value is set into config_BT.h
|
||||
|
||||
## ADVANCED: Setting up an external decoder
|
||||
|
||||
This advanced option is used to publish raw radio frames on a specific topic to be decoded by an external decoder instead of the integrated one.
|
||||
|
||||
To enable external decoder:
|
||||
|
||||
`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"extDecoderEnable":true}'`
|
||||
|
||||
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
|
||||
|
||||
[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: Publishing advertisement and advanced data (default: false)
|
||||
|
||||
If you want to enable this feature:
|
||||
|
||||
`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"pubadvdata":true}'`
|
||||
|
||||
This will publish extensive information about the device:
|
||||
```json
|
||||
{"id":"11:22:33:44:55:66","mac_type":0,"adv_type":0,"name":"Qingping Motion & Light","rssi":-93,"servicedata":"88121122334455660201520f0126090403000000","servicedatauuid":"0xfdcd","brand":"Qingping","model":"Motion & Light","model_id":"CGPR1","lux":3,"batt":82}
|
||||
```
|
||||
|
||||
## ADVANCED: Not publishing advertisement data
|
||||
|
||||
To stop publishing advertisement data:
|
||||
|
||||
`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"pubadvdata":false}'`
|
||||
|
||||
## Store BLE configuration into the gateway
|
||||
|
||||
Open MQTT Gateway has the capability to save the current configuration and reload it at startup.
|
||||
@@ -386,3 +340,47 @@ Response (assuming success):
|
||||
"state":"on"
|
||||
}
|
||||
```
|
||||
|
||||
## ADVANCED: Setting up an external decoder
|
||||
|
||||
This advanced option is used to publish raw radio frames on a specific topic to be decoded by an external decoder instead of the integrated one.
|
||||
|
||||
To enable external decoder:
|
||||
|
||||
`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"extDecoderEnable":true}'`
|
||||
|
||||
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
|
||||
|
||||
[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)
|
||||
|
||||
If you want to enable this feature:
|
||||
|
||||
`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"pubadvdata":true}'`
|
||||
|
||||
This will publish extensive information about the device:
|
||||
```json
|
||||
{"id":"11:22:33:44:55:66","mac_type":0,"adv_type":0,"name":"Qingping Motion & Light","rssi":-93,"servicedata":"88121122334455660201520f0126090403000000","servicedatauuid":"0xfdcd","brand":"Qingping","model":"Motion & Light","model_id":"CGPR1","lux":3,"batt":82}
|
||||
```
|
||||
|
||||
To stop publishing advertisement data:
|
||||
|
||||
`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoBT/config -m '{"pubadvdata":false}'`
|
||||
|
||||
::: warning Note
|
||||
All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.
|
||||
:::
|
||||
|
||||
::: warning
|
||||
We strongly encourage the use of a white-list (see below) so as to collect data from your devices only and not from other MAC addresses.
|
||||
By default the gateway scans the advertizing BLE devices nearby with their MAC addresses. Depending on your country, it may be illegal to monitor networks for MAC addresses, especially on networks that you do not own. Please check your country's laws (for US Section 18 U.S. Code § 2511) - [discussion here](https://github.com/schollz/howmanypeoplearearound/issues/4).
|
||||
:::
|
||||
Reference in new issue
Block a user