# ble_monitor
**Repository Path**: esp8266/ble_monitor
## Basic Information
- **Project Name**: ble_monitor
- **Description**: Passively monitors BLE messages from Xiaomi Mijia BLE MiBeacon, Qingping, ATC, Xiaomi Scale, Kegtron and Thermoplus sensors
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-02-17
- **Last Updated**: 2024-02-17
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Passive BLE Monitor integration
### BLE Monitor for Xiaomi MiBeacon, Qingping, ATC, Xiaomi Scale, Kegtron and Thermoplus sensors
- [INTRODUCTION](#introduction)
- [SUPPORTED SENSORS](#supported-sensors)
- [HOW TO INSTALL](#how-to-install)
- [1. Grant permissions for Python to have rootless access to the HCI interface](#1-grant-permissions-for-python-to-have-rootless-access-to-the-hci-interface)
- [2. Install the custom integration](#2-install-the-custom-integration)
- [3. Add your sensors to the MiHome app if you haven’t already](#3-add-your-sensors-to-the-mihome-app-if-you-havent-already)
- [4. Configure the integration](#4-configure-the-integration)
- [4a. Configuration in the User Interface](#4a-configuration-in-the-user-interface)
- [4b. Configuration in YAML](#4b-configuration-in-yaml)
- [CONFIGURATION PARAMETERS](#configuration-parameters)
- [Configuration parameters at component level](#configuration-parameters-at-component-level)
- [Configuration parameters at device level](#configuration-parameters-at-device-level)
- [Configuration in the User Interface](#configuration-in-the-user-interface)
- [Configuraton in YAML](#configuraton-in-yaml)
- [Deleting devices and sensors](#deleting-devices-and-sensors)
- [FREQUENTLY ASKED QUESTIONS](#frequently-asked-questions)
- [CREDITS](#credits)
- [FORUM](#forum)
## INTRODUCTION
This custom component is an alternative for the standard build in [mitemp_bt](https://www.home-assistant.io/integrations/mitemp_bt/) integration that is available in Home Assistant and supports much more sensors than the build in integration. Unlike the original `mitemp_bt` integration, which is getting its data by polling the device with a default five-minute interval, this custom component is parsing the Bluetooth Low Energy packets payload that is constantly emitted by the sensor. The packets payload may contain temperature/humidity/battery and other data. Advantage of this integration is that it doesn't affect the battery as much as the built-in integration. It also solves connection issues some people have with the standard integration (due to passivity and the ability to collect data from multiple bt-interfaces simultaneously). Read more in the [FAQ](https://github.com/custom-components/ble_monitor/blob/master/faq.md#why-is-this-component-called-passive-and-what-does-it-mean).
## SUPPORTED SENSORS
This integration supports **Xiaomi MiBeacon, Qingping, ATC, Xiaomi Scale, Kegtron and Thermoplus** sensors at the moment. Support for additional sensors can be requested by opening an [issue](https://github.com/custom-components/ble_monitor/issues). Check the [Frequently Asked Questions (FAQ) page](https://github.com/custom-components/ble_monitor/blob/kegtron-v2/faq.md#my-sensor-from-the-xiaomi-ecosystem-is-not-in-the-list-of-supported-ones-how-to-request-implementation) on how to provide usefull information for adding new sensors.
|Name|Description|Picture|
|---|---|---|
|**LYWSDCGQ** ![]()
|**Xiaomi Hygro thermometer**
Round body, segment LCD, broadcasts temperature, humidity and battery level, about 20 readings per minute. ![]()
| ![]()
|
|**CGG1**|**Qingping Hygro thermometer**
Round body, E-Ink, broadcasts temperature, humidity and battery level, about 20 readings per minute, although expection have been reported with 1 reading per 10 minutes. Note that there are (at least) three versions, CGG1, CGG1-M (MiHome version) and CGG1-H (Homekit version). The CGG1-H (Homekit version) is not supported. The CGG1-M (MiHome version) works with encryption and has a `qingping` logo at the back (left picture), while the old CGG1 works without encryption and doesn't have a logo at the back (right picture).
For sensors with encryption, you will need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.
CGG1-M (MiHome version) also supports custom ATC firmware available [here](https://github.com/pvvx/ATC_MiThermometer). The old CGG1 does not support custom firmware. Custom firmware's broadcast temperature, humidity, battery voltage and battery level in percent. Broadcast interval can be set by the user and encryption can be used as an option. BLE monitor will automatically use the advertisement type with the highest accuracy, when setting the firmware to broadcast all advertisement types. ||
|**CGDK2**|**Qingping Temp & RH Monitor Lite**
Round body, E-Ink, broadcasts temperature, humidity and battery level, about 1 readings per 10 minutes, advertisements are encrypted, therefore you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**LYWSD02**|**Xiaomi Temperature and Humidity sensor**
Rectangular body, E-Ink, broadcasts temperature, humidity and battery level (battery level is available for firmware version 1.1.2_00085 and later), about 20 readings per minute.||
|**LYWSD03MMC**|**Xiaomi Hygro thermometer**
Small square body, segment LCD, broadcasts temperature and humidity once in about 10 minutes and battery level once in an hour (original firmware). With the original firmware, advertisements are encrypted, therefore you need to set an encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.
`ble_monitor` also supports custom ATC firmware (both the firmware by `ATC1441`, available [here](https://github.com/atc1441/ATC_MiThermometer), and the improved firmware by `pvvx` available [here](https://github.com/pvvx/ATC_MiThermometer)). Both custom firmware's broadcast temperature, humidity, battery voltage and battery level in percent. Broadcast interval can be set by the user and encryption can be used as an option. BLE monitor will automatically use the advertisement type with the highest accuracy, when setting the firmware to broadcast all advertisement types.||
|**CGC1**|**Qingping bluetooth clock**
Alarm clock, broadcasts temperature, humidity and (most likely) battery level (we do not have accurate periodicity information yet). The sensor sends BLE advertisements in Xiaomi MiBeacon format and Qingping format, but only MiBeacon format is supported currently. Xiaomi MiBeacon advertisements are most likely encrypted, if you want to receive both advertisements, you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.
Note. If you have information about update frequency, encryption key requirement, and/or a log with `report_unknown: "qingping"`, we can improve the documentation and implement qingping format support without encryption. Please open an issue with this information.||
|**CGD1**|**Qingping Cleargrass CGD1 alarm clock**
Segment LCD, broadcasts temperature and humidity (once in about 10 minutes), and battery level (we do not have accurate periodicity information yet). The sensor sends BLE advertisements in Xiaomi MiBeacon format and Qingping format. Qingping advertisements are not encrypted. Xiaomi MiBeacon advertisements are encrypted, if you want to receive both advertisements, you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**CGP1W**|**Qingping Cleargrass indoor weather station with Atmospheric pressure measurement**
Broadcasts temperature, humidity, air pressure and and battery level (we do not have accurate periodicity information yet).||
|**MHO-C303**|**Alarm clock**
Rectangular body, E-Ink, broadcasts temperature, humidity and battery level, about 20 readings per minute.||
|**MHO-C401**|**Alarm clock**
Small square body, E-Ink display, broadcasts temperature and humidity once in about 10 minutes and battery level once in an hour, advertisements are encrypted, therefore you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.
`ble_monitor` also supports custom ATC firmware available [here](https://github.com/pvvx/ATC_MiThermometer). Custom firmware's broadcast temperature, humidity, battery voltage and battery level in percent. Broadcast interval can be set by the user and encryption can be used as an option. BLE monitor will automatically use the advertisement type with the highest accuracy, when setting the firmware to broadcast all advertisement types.||
|**JQJCY01YM**|**Xiaomi Honeywell Formaldehyde Sensor**
OLED display, broadcasts temperature, humidity, formaldehyde (mg/m³) and battery level, about 50 messages per minute.||
|**JTYJGD03MI**|**Xiaomi Honeywell Smoke Detector (Bluetooth)**
Smoke detector, broadcasts smoke detected, button press and bettery level. Only the Bluetooth model is supported||
|**HHCCJCY01**|**MiFlora plant sensor**
Broadcasts temperature, moisture, illuminance, conductivity, 1 reading per minute, no battery info with firmware v3.2.1.||
|**GCLS002**|**VegTrug Grow Care Garden**
Similar to MiFlora HHCCJCY01.||
|**HHCCPOT002**|**FlowerPot, RoPot**
Broadcasts moisture and conductivity, 2 readings per minute, no battery info with firmware v1.2.6.||
|**WX08ZM**|**Xiaomi Mija Mosquito Repellent**
Smart version, broadcasts switch state, tablet resource, battery level, about 50 messages per minute.|
|**MCCGQ02HL**|**Xiaomi Mijia Window/Door Sensor 2**
Broadcasts opening state, light state and battery level. Advertisements are encrypted, therefore you need to set an encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option. Battery level is only send once in approximately 24 hours.||
|**CGH1**|**Qingping Window Door/Sensor**
Broadcasts opening state and battery level. Advertisements are encrypted, therefore you need to set an encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option. Battery level is broadcasted, but interval is currently not known.||
|**YM-K1501**|**Xiaomi Mijia Smart kettle**
Broadcasts temperature. The switch entity has an extra `ext_state` attribute, with the following values: `0` - kettle is idle, `1` - kettle is heating water, `2` - warming function is active with boiling, `3` - warming function is active without boiling.||
|**V-SK152**|**Viomi Smart Kettle**
Broadcasts temperature and `ext_state` attribute as in YM-K1501, data broadcasted every 30 seconds.||
|**SJWS01LM**|**Xiaomi Smart Water Leak Sensor**
Broadcasts moisture state (wet/dry), advertisements are encrypted, therefore you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**MJYD02YL**|**Xiaomi Motion Activated Night Light**
Broadcasts light state (`light detected/no light`), motion (`motion detected/clear`) and battery state, advertisements are encrypted, therefore you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.
Light state is broadcasted once every 5 minutes when no motion is detected, when motion is detected the sensor also broadcasts the light state. Motion state is broadcasted when motion is detected, but is also broadcasted once per 5 minutes. If this message is within 30 seconds after motion, it's broadcasting `motion detected`, if it's after 30 seconds, it's broadcasting `motion clear`. Additonally, `motion clear` messages are broadcasted at 2, 5, 10, 20 and 30 minutes after the last motion. You can use the [reset_timer](#reset_timer) option if you want to use a different time to set the sensor to `motion clear`. Battery is broadcasted once every 5 minutes.||
|**MUE4094RT**|**Xiaomi Philips Bluetooth Night Light**
Broadcasts motion detection (only `motion detected`, no light or battery state). The sensor does not broadcast `motion clear` advertisements. It is therefore required to use the [reset_timer](#reset_timer) option with a value that is not 0.||
|**RTCGQ02LM**|**Xiaomi Mi Motion Sensor 2**
Broadcasts light state (`light detected/no light`), motion (`motion detected/clear`), button press and battery state, advertisements are encrypted, therefore you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.
Light state is broadcasted upon a change in light in the room and is also broadcasted at the same time as motion is detected. The sensor does not broadcast `motion clear` advertisements. It is therefore required to use the [reset_timer](#reset_timer) option with a value that is not 0). The sensor also broadcasts `single press` if you press the button. After each button press, the sensor state shortly shows `single press` and will return to `no press` after 1 second. The sensor has an attribute which shows the `last button press`. You can use the state change event to trigger an automation in Home Assistant. Battery is broadcasted once every few hours.||
|**CGPR1**|**Qingping Motion and ambient light sensor**
Broadcasts illuminance (in lux), motion (`motion detected/clear`) and battery state, advertisements are encrypted, therefore you need to set the key in your configuration, see for instructions the [encryption_key](#encryption_key) option.
Illumination is broadcasted upon every 10 minutes and when motion is detected. Motion state is broadcasted when motion is detected. Additonally, `motion clear` messages are broadcasted at 1, 2, 5, 10, 20 and 30 minutes after the last motion. You can use the [reset_timer](#reset_timer) option if you want to use a different time to set the sensor to `motion clear`. Battery level is broadcasted, but interval is currently not known.||
|**MMC-T201-1**|**Xiaomi Miaomiaoce Digital Baby Thermometer**
Broadcasts temperature and battery state. The calculated body temperature is displayed in BLE Monitor, please note the disclaimer below. About 15-20 messages per minute.
**DISCLAIMER**
The sensor sends two temperatures in the BLE advertisements, that are converted to a body temperature with a certain algorithm in the original app. We tried to reverse engineering this relation, but we were only able to approximate the relation in the range of 36.5°C - 37.9°C at this moment. It has not been calibrated at elevated body temperature (e.g. if someone has a fever), so measurements displayed in Home Assistant might be different (wrong) compared to those reported in the app. It is therefore advised NOT to rely on the measurements in BLE monitor if you want to monitor your or other peoples body temperature / health). If you have additional measurements, especially outside the investigated range, please report them in this [issue](https://github.com/custom-components/ble_monitor/issues/264).||
|**M1S-T500**|**Xiaomi Mi Electric Toothbrush T500**
Broadcasts `toothbrush mode` and `battery state`. At the moment, we are looking into the meaning of the different states. If you have more info which state corresponds to what, please post a message in [this topic](https://github.com/custom-components/ble_monitor/issues/319)||
|**YLAI003**|**Yeelight Smart Wireless Switch**
Broadcasts `single press`, `double press` and `long press`. After each button press, the sensor state shows the type of press. It will return to `no press` after the time set with the [reset_timer](#reset_timer) option. It is advised to change the reset time to 1 second (default = 35 seconds). The sensor has an attribute which shows the `last button press`. You can use the state change event to trigger an automation in Home Assistant. Advertisements are encrypted, you need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**YLYK01YL**|**Yeelight Remote Control**
Broadcasts the remote button being used (`on`, `off`, `color temperature`, `+`, `M`, `-`) in combination with the type of press (`single press` or `long press`). The state of the remote sensor shows the combination of both, the attributes shows the button being used and the type of press individually. It will return to `no press` after the time set with the [reset_timer](#reset_timer) option. It is advised to change the reset time to 1 second (default = 35 seconds). Additinally, two binary sensors are generated (one for `short press`, one for `long press`), which is `True` when pressing `on`, `+` or `-` and `False` when pressing `off`. Advertisements are sometimes encrypted, you need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**YLYK01YL-FANCL**|**Yeelight Fan Remote Control**
Broadcasts the remote button being used (`fan toggle`, `light toggle`, `standard wind speed`, `color temperature`, `natural wind speed`, `brightness`) in combination with the type of press (`single press` or `long press`). The state of the remote sensor shows the combination of both, the attributes shows the button being used and the type of press individually. It will return to `no press` after the time set with the [reset_timer](#reset_timer) option. It is advised to change the reset time to 1 second (default = 35 seconds). Advertisements are (partly) encrypted, you need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**YLYK01YL-VENFAN**|**Yeelight Ventilator Fan Remote Control**
Broadcasts the remote button being used (`swing`, `power toggle`, `timer 30 minutes`, `timer 60 seconds`, `strong wind speed`, `low wind speed`) in combination with the type of press (`single press` or `long press`). The state of the remote sensor shows the combination of both, the attributes shows the button being used and the type of press individually. It will return to `no press` after the time set with the [reset_timer](#reset_timer) option. It is advised to change the reset time to 1 second (default = 35 seconds). Advertisements are (partly) encrypted, you need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**YLYB01YL-BHFRC**|**Yeelight Bathroom Heater Remote Control**
Broadcasts the remote button being used (`heat`, `air exchange`, `dry`, `fan`, `swing`, `speed -`, `speed +`, `stop` or `light`) in combination with the type of press (`short press` or `long press`). The state of the remote sensor shows the remote button being pressed, the attributes shows the type of press. It will return to `no press` after the time set with the [reset_timer](#reset_timer) option. It is advised to change the reset time to 1 second (default = 35 seconds). Advertisements are (partly) encrypted, you need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.|
|**YLKG07YL, YLKG08YL**|**Yeelight Rotating Dimmer**
Broadcasts the press type (`rotate`, `rotate (presses)`, `short press`, `long press`). For rotation, it reports the rotation direction (`left`, `right`) and how far you rotate (number of `steps`). For `short press` it reports how many times you pressed the dimmer, for `long press` it reports the time (in seconds) you pressed the dimmer. The dimmer sensor state will return to `no press` after the time set with the [reset_timer](#reset_timer) option. It is advised to change the reset time to 1 second (default = 35 seconds). Advertisements are encrypted, you need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**K9B**|**Linptech Switch**
Broadcasts the press type (`short press`, `double press`, `long press`) for each button. There are three different versions of this switch, with one, two or three buttons. The switch sensor state will return to `no press` after the time set with the [reset_timer](#reset_timer) option. It is advised to change the reset time to 1 second (default = 35 seconds). Advertisements are probably encrypted (not confirmed yet), you need to set the encryption key in your configuration, see for instructions the [encryption_key](#encryption_key) option.||
|**XMTZC01HM, XMTZC04HM**|**Mi Smart Scale 1 / Mi Smart Scale 2**
Broadcasts `weight`, `non-stabilized weight` and `weight removed`. The `weight` is only reported after the scale is stabilized, while the `non-stabilized weight` is reporting all weight measurements. For additional data like BMI, viscaral fat, etc. you can use e.g. the [bodymiscale](https://github.com/dckiller51/bodymiscale) custom integration. If you want to split your measurements into different persons, you can use [this template sensor](https://community.home-assistant.io/t/integrating-xiaomi-mi-scale/9972/533) https://community.home-assistant.io/t/integrating-xiaomi-mi-scale/9972/533?u=ernst ||
|**XMTZC02HM, XMTZC05HM, NUN4049CN**|**Mi Body Composition Scale 2 / Mi Body Fat Scale**
Broadcasts `weight`, `non-stabilized weight`, `impedance` and `weight removed`. The `weight` is only reported after the scale is stabilized, while the `non-stabilized weight` is reporting all weight measurements. For additional data like BMI, viscaral fat, muscle mass etc. you can use e.g. the [bodymiscale](https://github.com/dckiller51/bodymiscale) custom integration. If you want to split your measurements into different persons, you can use [this template sensor](https://community.home-assistant.io/t/integrating-xiaomi-mi-scale/9972/533)||
|**Kegtron KT-100, KT-200**|**Kegtron KT-100 / KT-200**
Broadcasts `volume dispensed` for each port and port attributes (`keg size`, `start volume`, `state`, `index` and `port name`. Kegtron devices only send data with the option [active_scan](#active_scan) set to `True`, so make sure you change this setting, as the default is `False`||
|**Thermoplus**|**Smart Hygrometer**
Rounded square body, LCD screen, e.g. Brifit, Oria. Broadcasts temperature, humidity and battery level.||
|**Thermoplus**|**Lanyard Hygrometer**
Square body, no screen, e.g. Brifit, Oria. Broadcasts temperature, humidity and battery level.||
|**Thermoplus**|**Mini Hygrometer**
Round body, no screen, is also sold under different brands, e.g. Brifit, Oria. Broadcasts temperature, humidity and battery level.||
*The amount of actually received data is highly dependent on the reception conditions (like distance and electromagnetic ambiance), readings numbers are indicated for good RSSI (Received Signal Strength Indicator) of about -75 till -70dBm.*
**Do you want to request support for a new sensor? In the [FAQ](https://github.com/custom-components/ble_monitor/blob/master/faq.md#my-sensor-from-the-xiaomi-ecosystem-is-not-in-the-list-of-supported-ones-how-to-request-implementation) you can read instructions how to request support for other sensors.**
## HOW TO INSTALL
### 1. Grant permissions for Python to have rootless access to the HCI interface
This is usually only needed for alternative installations of Home Assistant that only install Home Assistant core.
- to grant access:
```shell
sudo setcap 'cap_net_raw,cap_net_admin+eip' `readlink -f \`which python3\``
```
- to verify:
```shell
sudo getcap `readlink -f \`which python3\``
```
*In case you get a PermissionError, check the [Frequently Asked Questions (FAQ) page](faq.md).
### 2. Install the custom integration
The easiest way to install the BLE Monitor integration is with [HACS](https://hacs.xyz/). First install [HACS](https://hacs.xyz/) if you don't have it yet. After installation you can find this integration in the HACS store under integrations.
Alternatively, you can install it manually. Just copy paste the content of the `ble_monitor/custom_components` folder in your `config/custom_components` directory. As example, you will get the `sensor.py` file in the following path: `/config/custom_components/ble_monitor/sensor.py`. The disadvantage of a manual installation is that you won't be notified about updates.
### 3. Add your sensors to the MiHome app if you haven’t already
Many Xiaomi ecosystem sensors (maybe all) do not broadcast BLE advertisements containing useful data until they have gone through the "pairing" process in the MiHome app. The encryption key is also (re)set when adding the sensor to the MiHome app, so do this first. Some sensors also support alternative firmware, which doesn't need to be paired to MiHome.
### 4. Configure the integration
There are two ways to configure the integration and your devices (sensors), in the User Interface (UI) or in your YAML configuration file. Choose one method, you can't use both ways at the same time. You are able to switch from one to the other, at any time.
#### 4a. Configuration in the User Interface
Make sure you restart Home Assistant after the installation in HACS. After the restart, go to **Configuration** in the side menu in Home Assistant and select **Integrations**. Click on **Add Integrations** in the bottom right corner and search for **Passive BLE Monitor** to install. This will open the configuration menu with the default settings. The options are explained in the [configuration parameters](#configuration-parameters) section below and can also be changed later in the options menu. After a few seconds, the sensors should be added to your Home Assistant automatically. Note that the actual measurements require at least one [period](#period) to become visible.
#### 4b. Configuration in YAML
Alternatively, you can add the configuration in `configuration.yaml` as explained below. The options are the same as in the UI and are explained in the [configuration parameters](#configuration-parameters) section below. After adding your initial configuration to your YAML file, or applying a configuration change in YAML, a restart is required to load the new configuration. After a few minutes, the sensors should be changed/added to your Home Assistant automatically (at least one [period](#period) required).
An example of `configuration.yaml` with the minimum configuration is:
```yaml
ble_monitor:
```
An example of `configuration.yaml` with all optional parameters is:
```yaml
ble_monitor:
bt_interface: '04:B1:38:2C:84:2B'
discovery: True
active_scan: False
report_unknown: False
decimals: 1
period: 60
log_spikes: False
use_median: False
restore_state: False
devices:
- mac: 'A4:C1:38:2F:86:6C'
name: 'Livingroom'
encryption_key: '217C568CF5D22808DA20181502D84C1B'
temperature_unit: C
decimals: 2
use_median: False
restore_state: default
- mac: 'C4:3C:4D:6B:4F:F3'
name: 'Bedroom'
temperature_unit: F
- mac: 'B4:7C:8D:6D:4C:D3'
reset_timer: 35
```
Note: The encryption_key parameter is only needed for sensors, for which it is [pointed](#supported-sensors) that their messages are encrypted.
## CONFIGURATION PARAMETERS
### Configuration parameters at component level
#### bt_interface
(MAC address or list of multiple MAC addresses)(Optional) This parameter is used to select the Bluetooth-interface of your Home Assistant host. When using YAML, a list of available Bluetooth-interfaces available on your system is given in the Home Assistant log during startup of the Integration, when you enable the Home Assistant [logger at info-level](https://www.home-assistant.io/integrations/logger/). If you don't specify a MAC address, by default the first interface of the list will be used. If you want to use multiple interfaces, you can use the following configuration:
```yaml
ble_monitor:
bt_interface:
- '04:B1:38:2C:84:2B'
- '34:DE:36:4F:23:2C'
```
Default value: First available MAC address
#### hci_interface
(positive integer or list of positive integers)(Optional) Like the previous option `bt_interface`, this parameter is also used to select the bt-interface of your Home Assistant host. It is however strongly advised to use the `bt_interface` option and not this `hci_interface` option, as the hci number can change, e.g. when plugging in a dongle. However, due to backwards compatibility, this option is still available. Use 0 for hci0, 1 for hci1 and so on. On most systems, the interface is hci0. In addition, if you need to collect data from several interfaces, you can specify a list of interfaces:
```yaml
ble_monitor:
hci_interface:
- 0
- 1
```
Default value: No default value, `bt_interface` is used as default.
#### discovery
(boolean)(Optional) By default, the component creates entities for all discovered, supported sensors. However, situations may arise where you need to limit the list of sensors. For example, when you receive data from neighboring sensors, or when data from part of your sensors are received using other equipment, and you don't want to see entities you do not need. To resolve this issue, simply add an entry of each MAC-address of the sensors you need under `devices`, by using the `mac` option, and set the `discovery` option to False:
```yaml
ble_monitor:
discovery: False
devices:
- mac: '58:C1:38:2F:86:6C'
- mac: 'C4:FA:64:D1:61:7D'
```
Data from sensors with other addresses will be ignored. Default value: True
#### active_scan
(boolean)(Optional) In active mode scan requests will be sent, which is most often not required, but slightly increases the sensor battery consumption. 'Passive mode' means that you are not sending any request to the sensor but you are just receiving the advertisements sent by the BLE devices. This parameter is a subject for experiment. Default value: False
#### batt_entities [DEPRECATED]
(boolean)(Optional) This option is deprecated, please remove from your configuration.
#### decimals
(positive integer)(Optional) Number of decimal places to round. This setting can be overruled with for specific devices with settings [at device level](#configuration-parameters-at-device-level). Default value: 1
#### period
(positive integer)(Optional) The period in seconds during which the sensor readings are collected and transmitted to Home Assistant after averaging. Default value: 60.
*To clarify the difference between the sensor broadcast interval and the component measurement period: The LYWSDCGQ transmits 20-25 valuable BT LE messages (RSSI -75..-70 dBm). During the period = 60 (seconds), the component accumulates all these 20-25 messages, and after the 60 seconds expires, averages them and updates the sensor status in Home Assistant. The period does not affect the consumption of the sensor. It only affects the Home Assistant sensor update rate and the number of averaged values. We cannot change the frequency with which sensor sends data.*
#### log_spikes
(boolean)(Optional) Puts information about each erroneous spike in the Home Assistant log. Default value: False
*There are reports (pretty rare) that some sensors tend to sometimes produce erroneous values that differ markedly from the actual ones. Therefore, if you see inexplicable sharp peaks or dips on the temperature or humidity graph, I recommend that you enable this option so that you can see in the log which values were qualified as erroneous. The component discards values that exceeds the sensor’s measurement capabilities. These discarded values are given in the log records when this option is enabled. If erroneous values are within the measurement capabilities (-40..60°C and 0..100%H), there are no messages in the log. If your sensor is showing this, there is no other choice but to calculate the average as the median (next option).*
#### use_median
(boolean)(Optional) Use median as sensor output instead of mean (helps with "spiky" sensors). Please note that both the median and the mean values in any case are present as the sensor state attributes. This setting can be overruled with for specific devices with settings [at device level](#configuration-parameters-at-device-level). Default value: False
*The difference between the mean and the median is that the median is **selected** from the sensor readings, and not calculated as the average. That is, the median resolution is equal to the resolution of the sensor (one tenth of a degree or percent), while the mean allows you to slightly increase the resolution (the longer the measurement period, the larger the number of values will be averaged, and the higher the resolution can be achieved, if necessary with disabled rounding).*
#### restore_state
(boolean)(Optional) This option will, when set to `True`, restore the state of the sensors. If your [devices](#devices) are configured with a [mac](#mac) address, they will restore immediately after a restart of Home Assistant to the state right before the restart. If you didn't configure your [devices](#devices), the state will be restored upon the first BLE advertisement being received.
with `restore_state` set to `False`, the integration needs some time (see [period](#period) option) after a restart before it shows the actual data in Home Assistant. During this time, the integration receives data from your sensors and calculates the mean or median values of these measurements. During this period, the entity will have a state "unknown" or "unavailable" when `restore_state` is set to `False`. Setting it to `True` will prevent this, as it restores the old state, but could result in sensors having the wrong state, e.g. if the state has changed during the restart. By default, this option is disabled, as especially the binary sensors would rely on the correct state. For measuring sensors like temperature sensors, this option can be safely set to `True`. It is also possible to overrule this setting for specific devices with settings [at device level](#configuration-parameters-at-device-level). Default value: False
#### report_unknown
(`Xiaomi`, `Qingping`, `ATC`, `Mi Scale`, `Kegtron`, `Thermoplus`, `Other` or `False`)(Optional) This option is needed primarily for those who want to request an implementation of device support that is not in the list of [supported sensors](#supported-sensors). If you set this parameter to `Xiaomi`, `Qingping`, `ATC`, `Mi Scale`, `Kegtron` or `Thermoplus`, then the component will log all messages from unknown devices of the specified type to the Home Assitant log (`logger` component must be enabled at info level). When set to `Other`, all BLE advertisements will be logged. **Attention!** Enabling this option can lead to huge output to the Home Assistant log, especially when set to `Other`, do not enable it if you do not need it! Details in the [FAQ](https://github.com/custom-components/ble_monitor/blob/master/faq.md#my-sensor-from-the-xiaomi-ecosystem-is-not-in-the-list-of-supported-ones-how-to-request-implementation). Default value: False
### Configuration parameters at device level
#### devices
(Optional) The devices option is used for setting options at the level of the device and/or if you want to whitelist certain sensors with the `discovery` option. Note that if you use the `devices` option, the `mac` option is also required.
### Configuration in the User Interface
To add a device, open the options menu of the integration and select **Add Device** in the device drop down menu and click on Submit. You can modify existing configured devices in a similar way, by selecting your device in the same drop down menu and clicking on Submit. Both will show the following form.
### Configuraton in YAML
To add a device, add the following to your `configuration.yaml`
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
name: 'Livingroom'
encryption_key: '217C568CF5D22808DA20181502D84C1B'
temperature_unit: C
decimals: 2
use_median: False
restore_state: default
- mac: 'C4:3C:4D:6B:4F:F3'
reset_timer: 35
```
#### mac
(string)(Required) The `mac` option (`MAC address` in the UI) is used to identify your sensor device based on its mac-address. This allows you to define other additional options for this specific sensor device and/or to whitelist it with the `discovery` option. You can find the MAC address in the attributes of your sensor (`Developers Tools` --> `States`). For deleting devices see the instructions [below](#deleting-devices-and-sensors).
#### name
When using configuration in the User Interface, you can modify the device name by opening your device, via configuration, integrations and clicking on devices on the BLE monitor tile. Select the device you want to change the name of and click on the cogwheel in the topright corner, where you can change the name. You will get a question wether you want to rename the individual sensor entities of this device as well (normally, it is advised to do this).
(string)(Optional) When using YAML, you can use the `name` option to link a device name and sensor name to the mac-address of the sensor device. Using this option (or changing a name) will create new sensor entities. The old data won't be transfered to the new sensor. The old sensor entities can be safely deleted afterwards, but this has to be done manually at the moment, see the instructions [below](#deleting-devices-and-sensors). The sensors are named with the following convention: `sensor.ble_sensortype_device_name` (e.g. `sensor.ble_temperature_livingroom`) in stead of the default `ble_sensortype_mac` (e.g. `sensor.ble_temperature_A4C1382F86C`). You will have to update your lovelace cards, automation and scripts after each change. Note that you can still override the entity_id from the UI. Default value: Empty
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
name: 'Livingroom'
```
#### encryption_key
(string, 24 or 32 characters)(Optional) This option is used for sensors broadcasting encrypted advertisements. The encryption key should be 32 characters (= 16 bytes) for most devices (LYWSD03MMC, CGD1, MCCGQ02HL, and MHO-C401 (original firmware only). Only Yeelight YLYK01YL (all types), YLYB01YL-BHFRC, YLKG07YL and YLKG08YL require a 24 character (= 12 bytes) long key. The case of the characters does not matter. The keys below are an example, you need your own key(s)! Information on how to get your key(s) can be found [here](https://github.com/custom-components/ble_monitor/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key). Default value: Empty
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
encryption_key: '217C568CF5D22808DA20181502D84C1B'
```
#### temperature_unit
(C or F)(Optional) Most sensors are sending BLE advertisements with temperature data in Celsius (C), even when set to Fahrenheit (F) in the MiHome app. However, sensors with custom ATC firmware will start sending temperature data in Fahrenheit (F) after changing the display from Celsius to Fahrenheit. This means that you will have to tell `ble_monitor` that it should expect Fahrenheit data for these specific sensors, by setting this option to Fahrenheit (F). Note that Home Assistant is always converting measurements to C or F based on your Unit System setting in Configuration - General. Default value: C
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
temperature_unit: F
```
#### decimals (device level)
(positive integer or `default`)(Optional) Number of decimal places to round. Overrules the setting at integration level. Default value: default (which means: use setting at integration level)
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
decimals: 2
- mac: 'A4:C1:38:2F:86:6B'
decimals: default
```
#### use_median (device level)
(boolean or `default`)(Optional) Use median as sensor output instead of mean (helps with "spiky" sensors). Overrules the setting at integration level. Please note that both the median and the mean values in any case are present as the sensor state attributes. Default value: default (which means: use setting at integration level)
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
use_median: True
- mac: 'A4:C1:38:2F:86:6B'
use_median: default
```
#### restore_state (device level)
(boolean or `default`)(Optional) This option will, when set to `True`, restore the state of the sensors immediately after a restart of Home Assistant to the state right before the restart. Overrules the setting at integration level. See for a more detailed explanation the setting at integration level. Default value: default (which means: use setting at integration level)
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
restore_state: True
- mac: 'A4:C1:38:2F:86:6B'
restore_state: default
```
#### reset_timer
(possitive integer)(Optional) This option sets the time (in seconds) after which a sensor is reset to `motion clear` (motion sensors) or `no press` (button and dimmer sensors). After each `motion detected` advertisement or `button/dimmer press`, the timer starts counting down again. Setting this option to 0 seconds will turn this resetting behavior off.
Note that motion sensors also sends advertisements themselves that can overrule this setting. To our current knowledge, advertisements after 30 seconds of no motion send by the sensor are `motion clear` messages, advertisements within 30 seconds are `motion detected` messages. For button and dimmer sensors, it is advised to set the `reset_timer` to 1 second. Default value: 35
```yaml
ble_monitor:
devices:
- mac: 'A4:C1:38:2F:86:6C'
reset_timer: 35
```
### Deleting devices and sensors
Removing devices can be done by removing the corresponding lines in your `configuration.yaml`. In the UI, you can delete devices by typing `-` in the `MAC address` field. Note that if the [discovery](#discovery) option is set to `True` they will be discovered automatically again.
Unfortunately, old devices and sensor entities are not entirely deleted by this, they will still be visible, but will be `unavailable` after a restart. The same applies for changing a name of an existing device in YAML, the sensor entities with the old name will still remain visible, but with an `unavailable` state after a restart. To completely remove these left overs, follow the following steps.
#### 1. Remove old entities
First, delete the old entities, by going to **configuration**, **integrations** and selecting **devices** in the BLE monitor tile. Select the device with old entities and select each unavailable sensor, to delete it manually. If the delete button isn't visible, you will have to restart Home Assistant to unload the entities. Make sure all old sensor entities are deleted before going to the next step.
#### 2. Remove old devices
If the sensor doesn't have any sensor entities anymore, you can delete the device as well. Unfortunately, Home Assistant doesn't have an delete option to remove the old device. To overcome this problem, we have created a `service` to help you solve this. Go to **developer tools**, **services** and select the `ble_monitor.cleanup_entries` service. Click on **Call service** and the device should be gone. If not, you probably haven't deleted all sensor entities (go to step 1).
## FREQUENTLY ASKED QUESTIONS
Still having questions or issues? Please first have a look on our [Frequently Asked Questions (FAQ) page](faq.md) to see if your question is already answered. There are some useful tips also.
If your question or issue isn't answered in the FAQ, please open an [issue](https://github.com/custom-components/ble_monitor/issues).
## CREDITS
Credits and big thanks should be given to:
- [@Magalex](https://community.home-assistant.io/u/Magalex) and [@Ernst](https://community.home-assistant.io/u/Ernst) for the component creation, development, and support.
- [@koying](https://github.com/koying) for implementing the configuration in the user interface.
- [@tsymbaliuk](https://community.home-assistant.io/u/tsymbaliuk) for the idea and the first code.
## FORUM
You can more freely discuss the operation of the component, ask for support, leave feedback and share your experience in [our topic](https://community.home-assistant.io/t/passive-ble-monitor-integration/303583) on the Home Assistant forum.