diff --git a/README.md b/README.md index 3faed6d6c..4cb660184 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,10 @@ This custom component is an alternative for the standard build in [mitemp_bt](ht (Xiaomi Honeywell Formaldehyde Sensor, OLED display, broadcasts temperature, humidity, formaldehyde (mg/m³) and battery level, about 50 messages per minute) +- WX08ZM + + (Xiaomi Mija Mosquito Repellent, Smart version, broadcasts switch state, tablet resource, battery level, about 50 messages per minute) + *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/sensor.mitemp_bt/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.** @@ -127,6 +131,7 @@ sensor: encryptors: 'A4:C1:38:2F:86:6C': '217C568CF5D22808DA20181502D84C1B' report_unknown: False + whitelist: False ``` Note: The encryptors parameter is only needed for sensors, for which it is [pointed](#supported-sensors) that their messages are encrypted. @@ -135,67 +140,94 @@ Note: The encryptors parameter is only needed for sensors, for which it is [poin #### rounding - (boolean)(Optional) Enable/disable rounding of the average of all measurements taken within the number seconds specified with 'period'. This option is designed to disable rounding and thus keep the full average accuracy. When disabled, the `decimals` option is ignored. Default value: True + (boolean)(Optional) Enable/disable rounding of the average of all measurements taken within the number seconds specified with 'period'. This option is designed to disable rounding and thus keep the full average accuracy. When disabled, the `decimals` option is ignored. Default value: True #### decimals - (positive integer)(Optional) Number of decimal places to round (will be ignored if rounding is disabled). Default value: 1 + (positive integer)(Optional) Number of decimal places to round (will be ignored if rounding is disabled). 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. + (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.* + *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 + (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).* + *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. Default value: False + (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. 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).* + *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).* #### 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 + (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 #### hci_interface - (positive integer or list of positive integers)(Optional) This parameter is used to select the bt-interface used. 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: + (positive integer or list of positive integers)(Optional) This parameter is used to select the bt-interface used. 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 - sensor: - - platform: mitemp_bt - hci_interface: - - 0 - - 1 - ``` + ```yaml + sensor: + - platform: mitemp_bt + hci_interface: + - 0 + - 1 + ``` - Default value: 0 + Default value: 0 #### batt_entities - (boolean)(Optional) By default, the battery information will be presented only as a sensor attribute called `battery level`. If you set this parameter to `True`, then the battery sensor entity will be additionally created - `sensor.mi_batt_ `. Default value: False + (boolean)(Optional) By default, the battery information will be presented only as a sensor attribute called `battery level`. If you set this parameter to `True`, then the battery sensor entity will be additionally created - `sensor.mi_batt_ `. Default value: False #### encryptors - (dictionary)(Optional) This option is used to link the mac-address of the sensor broadcasting encrypted advertisements to the encryption key (32 characters = 16 bytes). This is only needed for LYWSD03MMC and CGD1 sensors. 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/sensor.mitemp_bt/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key). Default value: Empty + (dictionary)(Optional) This option is used to link the mac-address of the sensor broadcasting encrypted advertisements to the encryption key (32 characters = 16 bytes). This is only needed for LYWSD03MMC and CGD1 sensors. 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/sensor.mitemp_bt/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key). Default value: Empty -```yaml -sensor: - - platform: mitemp_bt - encryptors: + ```yaml + sensor: + - platform: mitemp_bt + encryptors: 'A4:C1:38:2F:86:6C': '217C568CF5D22808DA20181502D84C1B' 'A4:C1:38:D1:61:7D': 'C99D2313182473B38001086FEBF781BD' -``` + ``` #### report_unknown - (boolean)(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 `True`, then the component will log all messages from unknown Xiaomi ecosystem devices to the Home Assitant log. **Attention!** Enabling this option can lead to huge output to the Home Assistant log, do not enable it if you do not need it! Details in the [FAQ](https://github.com/custom-components/sensor.mitemp_bt/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 + (boolean)(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 `True`, then the component will log all messages from unknown Xiaomi ecosystem devices to the Home Assitant log. **Attention!** Enabling this option can lead to huge output to the Home Assistant log, do not enable it if you do not need it! Details in the [FAQ](https://github.com/custom-components/sensor.mitemp_bt/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 + +#### whitelist + + (list or boolean)(Optional) By default, the component creates entities for all detected 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 list the MAC-addresses of the sensors you need in the `whitelist` option: + + ```yaml + sensor: + - platform: mitemp_bt + whitelist: + - '58:C1:38:2F:86:6C' + - 'C4:FA:64:D1:61:7D' + ``` + + Data from sensors with other addresses will be ignored. + In addition, all addresses listed in the `encryptors` option will be automatically whitelisted. + If you have no sensors other than those listed in `encryptors`, then just set `whitelist` to `True`: + + ```yaml + sensor: + - platform: mitemp_bt + encryptors: + 'A4:C1:38:2F:86:6C': '217C568CF5D22808DA20181502D84C1B' + 'A4:C1:38:D1:61:7D': 'C99D2313182473B38001086FEBF781BD' + whitelist: True + ``` + + Default value: False ## FREQUENTLY ASKED QUESTIONS diff --git a/custom_components/mitemp_bt/const.py b/custom_components/mitemp_bt/const.py index 1c13bf845..5f0f30269 100644 --- a/custom_components/mitemp_bt/const.py +++ b/custom_components/mitemp_bt/const.py @@ -1,4 +1,7 @@ """Constants for the Xiaomi passive BLE monitor sensor integration.""" +from homeassistant.const import ( + DEVICE_CLASS_POWER, +) # Configuration options CONF_ROUNDING = "rounding" @@ -11,6 +14,7 @@ CONF_BATT_ENTITIES = "batt_entities" CONF_ENCRYPTORS = "encryptors" CONF_REPORT_UNKNOWN = "report_unknown" +CONF_WHITELIST = "whitelist" # Default values for configuration options DEFAULT_ROUNDING = True @@ -22,6 +26,7 @@ DEFAULT_HCI_INTERFACE = 0 DEFAULT_BATT_ENTITIES = False DEFAULT_REPORT_UNKNOWN = False +DEFAULT_WHITELIST = False """Fixed constants.""" @@ -42,21 +47,33 @@ b'\xBC\x03': "GCLS002", b'\x5B\x05': "LYWSD03MMC", b'\x76\x05': "CGD1", - b'\xDF\x02': "JQJCY01YM" + b'\xDF\x02': "JQJCY01YM", + b'\x0A\x04': "WX08ZM" } # Sensor type indexes dictionary -# Temperature, Humidity, Moisture, Conductivity, Illuminance, Formaldehyde, Battery -# Measurement type T H M C I F B 9 - no measurement +# Temperature, Humidity, Moisture, Conductivity, Illuminance, Formaldehyde, Consumable, Switch, Battery +# Measurement type T H M C I F Cn Sw B 9 - no measurement MMTS_DICT = { - 'HHCCJCY01' : [0, 9, 1, 2, 3, 9, 9], - 'GCLS002' : [0, 9, 1, 2, 3, 9, 9], - 'HHCCPOT002': [9, 9, 0, 1, 9, 9, 9], - 'LYWSDCGQ' : [0, 1, 9, 9, 9, 9, 2], - 'LYWSD02' : [0, 1, 9, 9, 9, 9, 9], - 'CGG1' : [0, 1, 9, 9, 9, 9, 2], - 'LYWSD03MMC': [0, 1, 9, 9, 9, 9, 2], - 'CGD1' : [0, 1, 9, 9, 9, 9, 2], - 'JQJCY01YM' : [0, 1, 9, 9, 9, 2, 3] + 'HHCCJCY01' : [0, 9, 1, 2, 3, 9, 9, 9, 9], + 'GCLS002' : [0, 9, 1, 2, 3, 9, 9, 9, 9], + 'HHCCPOT002': [9, 9, 0, 1, 9, 9, 9, 9, 9], + 'LYWSDCGQ' : [0, 1, 9, 9, 9, 9, 9, 9, 2], + 'LYWSD02' : [0, 1, 9, 9, 9, 9, 9, 9, 9], + 'CGG1' : [0, 1, 9, 9, 9, 9, 9, 9, 2], + 'LYWSD03MMC': [0, 1, 9, 9, 9, 9, 9, 9, 2], + 'CGD1' : [0, 1, 9, 9, 9, 9, 9, 9, 2], + 'JQJCY01YM' : [0, 1, 9, 9, 9, 2, 9, 9, 3], + 'WX08ZM' : [9, 9, 9, 9, 9, 9, 0, 1, 2] +} + +# Switch binary sensor classes dict +SW_CLASS_DICT = { + 'WX08ZM' : DEVICE_CLASS_POWER +} + +# Consumable sensor name dict +CN_NAME_DICT = { + 'WX08ZM' : "tablet_" } diff --git a/custom_components/mitemp_bt/sensor.py b/custom_components/mitemp_bt/sensor.py index ecc10f161..3636a2f09 100644 --- a/custom_components/mitemp_bt/sensor.py +++ b/custom_components/mitemp_bt/sensor.py @@ -17,7 +17,15 @@ DEVICE_CLASS_BATTERY, TEMP_CELSIUS, ATTR_BATTERY_LEVEL, + STATE_OFF, STATE_ON, ) + +# Binary Sensor Class will be renamed in the future HA releases +try: + from homeassistant.components.binary_sensor import BinarySensorEntity +except ImportError: + from homeassistant.components.binary_sensor import BinarySensorDevice as BinarySensorEntity + from homeassistant.components.sensor import PLATFORM_SCHEMA import homeassistant.helpers.config_validation as cv from homeassistant.helpers.entity import Entity @@ -34,6 +42,7 @@ DEFAULT_HCI_INTERFACE, DEFAULT_BATT_ENTITIES, DEFAULT_REPORT_UNKNOWN, + DEFAULT_WHITELIST, CONF_ROUNDING, CONF_DECIMALS, CONF_PERIOD, @@ -44,12 +53,15 @@ CONF_BATT_ENTITIES, CONF_ENCRYPTORS, CONF_REPORT_UNKNOWN, + CONF_WHITELIST, CONF_TMIN, CONF_TMAX, CONF_HMIN, CONF_HMAX, XIAOMI_TYPE_DICT, MMTS_DICT, + SW_CLASS_DICT, + CN_NAME_DICT, ) _LOGGER = logging.getLogger(__name__) @@ -78,6 +90,9 @@ vol.Optional(CONF_BATT_ENTITIES, default=DEFAULT_BATT_ENTITIES): cv.boolean, vol.Optional(CONF_ENCRYPTORS, default={}): ENCRYPTORS_LIST_SCHEMA, vol.Optional(CONF_REPORT_UNKNOWN, default=DEFAULT_REPORT_UNKNOWN): cv.boolean, + vol.Optional( + CONF_WHITELIST, default=DEFAULT_WHITELIST + ): vol.Any(vol.All(cv.ensure_list, [cv.matches_regex(MAC_REGEX)]), cv.boolean), } ) @@ -176,6 +191,10 @@ def parse_xiaomi_value(hexvalue, typecode): return {"battery": hexvalue[0]} if typecode == b'\x08\x10': return {"moisture": hexvalue[0]} + if typecode == b'\x12\x10': + return {"switch": hexvalue[0]} + if typecode == b'\x13\x10': + return {"consumable": hexvalue[0]} if vlength == 3: if typecode == b'\x07\x10': (illum,) = ILL_STRUCT.unpack(hexvalue + b'\x00') @@ -205,7 +224,7 @@ def decrypt_payload(encrypted_payload, key, nonce): return plaindata -def parse_raw_message(data, aeskeyslist, report_unknown=False): +def parse_raw_message(data, aeskeyslist, whitelist, report_unknown=False): """Parse the raw data.""" if data is None: return None @@ -226,6 +245,10 @@ def parse_raw_message(data, aeskeyslist, report_unknown=False): source_mac_reversed = data[adv_index - 7:adv_index - 1] if xiaomi_mac_reversed != source_mac_reversed: return None + # check for MAC presence in whitelist, if needed + if whitelist: + if xiaomi_mac_reversed not in whitelist: + return None # extract RSSI byte (rssi,) = struct.unpack(" str: def force_update(self): """Force update.""" return True + +class ConsumableSensor(Entity): + """Representation of a Sensor.""" + + def __init__(self, mac): + """Initialize the sensor.""" + self._state = None + self._battery = None + self._cn_name = "cn_" + self._nmac = mac + self._device_state_attributes = {} + + @property + def name(self): + """Return the name of the sensor.""" + return "mi {}".format(self._cn_name + self._nmac) + + @property + def state(self): + """Return the state of the sensor.""" + return self._state + + @property + def unit_of_measurement(self): + """Return the unit of measurement.""" + return "%" + + @property + def icon(self): + """Return the icon of the sensor.""" + return "mdi:mdi-recycle-variant" + + @property + def should_poll(self): + """No polling needed.""" + return False + + @property + def device_state_attributes(self): + """Return the state attributes.""" + return self._device_state_attributes + + @property + def unique_id(self) -> str: + """Return a unique ID.""" + return self._cn_name + self._nmac + + @property + def force_update(self): + """Force update.""" + return True + +class SwitchBinarySensor(BinarySensorEntity): + """Representation of a Sensor.""" + + def __init__(self, mac): + """Initialize the sensor.""" + self._state = None + self._swclass = None + self._battery = None + self._unique_id = "sw_" + mac + self._device_state_attributes = {} + + @property + def is_on(self): + """Return true if the binary sensor is on.""" + return bool(self._state) + + @property + def name(self): + """Return the name of the sensor.""" + return "mi {}".format(self._unique_id) + + @property + def state(self): + """Return the state of the binary sensor.""" + return STATE_ON if self.is_on else STATE_OFF + + @property + def should_poll(self): + """No polling needed.""" + return False + + @property + def device_state_attributes(self): + """Return the state attributes.""" + return self._device_state_attributes + + @property + def unique_id(self) -> str: + """Return a unique ID.""" + return self._unique_id + + @property + def device_class(self): + """Return the class of this device, from component DEVICE_CLASSES.""" + return self._swclass + + @property + def force_update(self): + """Force update.""" + return True diff --git a/info.md b/info.md index bcf279175..60a26b36a 100644 --- a/info.md +++ b/info.md @@ -8,16 +8,39 @@ {% endif %} {% if installed or pending_update %} -# Changes since 0.6.3 +# Changes since 0.6.6 -- support for JQJCY01YM sensor Xiaomi Honeywell Formaldehyde Sensor - (about 50 messages per minute total: temperature + humidity + formaldehyde + battery level) +- changes to implement support for sensors broadcasting switch state and consumable resource; -- `decimals: 1` by default (instead of `decimals: 2`) + The entity class of the binary sensor and the entity name of the consumable sensor are assigned automatically depending on the type of specific device. + *Due to the fact that this component has a periodic nature of the operation, the state of the binary sensor will arrive with some delay. For example, if your period option is one minute (by default this is the case), and the state of the sensor has changed by 30 seconds of the period, then the state of the binary sensor entity in HA will change only after the remaining 30 seconds have passed.* -- some multithreading optimizations +- Xiaomi Mija Mosquito Repellent WX08ZM support; -*For JQJCY01YM owners: since the formaldehyde sensor returns values ​​in the range from 0 to 1.5 mg / m3 with a resolution of 0.01, the number of decimal places for the formaldehyde sensor is forced to 3 (in case of enabled rounding).* +- new `whitelist` option: + + By default, the component creates entities for all detected supported sensors. However, situations may arise when you need to limit the list of sensors. For example, when you receive data from neighboring sensors, or data from part of your sensors are received using other equipment, and you would not want to see entities you do not need. To resolve this issue, simply list the mac-addresses of the sensors you need in the `whitelist` option: + + ```yaml + sensor: + - platform: mitemp_bt + whitelist: + - '58:C1:38:2F:86:6C' + - 'C4:FA:64:D1:61:7D' + ``` + + data from sensors with other addresses will be ignored. + In addition, all addresses listed in the `encryptors` option will be automatically whitelisted. + If you have no sensors other than those listed in `encryptors`, then just set `whitelist` to `True`: + + ```yaml + sensor: + - platform: mitemp_bt + encryptors: + 'A4:C1:38:2F:86:6C': '217C568CF5D22808DA20181502D84C1B' + 'A4:C1:38:D1:61:7D': 'C99D2313182473B38001086FEBF781BD' + whitelist: True + ``` --- {% endif %} @@ -81,6 +104,10 @@ This custom component is an alternative for the standard build in [mitemp_bt](ht (Xiaomi Honeywell Formaldehyde Sensor, OLED display, broadcasts temperature, humidity, formaldehyde (mg/m³) and battery level, about 50 messages per minute) +- WX08ZM + + (Xiaomi Mija Mosquito Repellent, Smart version, broadcasts switch state, tablet resource, battery level, about 50 messages per minute) + *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 -70dBm till -75dBm.* **Do you want to request support for a new sensor? In the [FAQ](https://github.com/custom-components/sensor.mitemp_bt/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.** @@ -151,6 +178,7 @@ sensor: encryptors: 'A4:C1:38:2F:86:6C': '217C568CF5D22808DA20181502D84C1B' report_unknown: False + whitelist: False ``` Note: The encryptors parameter is only needed for sensors, for which it is [pointed](#supported-sensors) that their messages are encrypted. @@ -159,67 +187,95 @@ Note: The encryptors parameter is only needed for sensors, for which it is [poin #### rounding - (boolean)(Optional) Enable/disable rounding of the average of all measurements taken within the number seconds specified with 'period'. This option is designed to disable rounding and thus keep the full average accuracy. When disabled, the 'decimals' option is ignored. Default value: True + (boolean)(Optional) Enable/disable rounding of the average of all measurements taken within the number seconds specified with 'period'. This option is designed to disable rounding and thus keep the full average accuracy. When disabled, the `decimals` option is ignored. Default value: True #### decimals - (positive integer)(Optional) Number of decimal places to round (will be ignored if rounding is disabled). Default value: 1 + (positive integer)(Optional) Number of decimal places to round (will be ignored if rounding is disabled). 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. + (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.* + *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 + (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).* + *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. Default value: False + (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. 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).* + *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).* #### 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 + (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 #### hci_interface - (positive integer or list of positive integers)(Optional) This parameter is used to select the bt-interface used. 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 multiple interfaces simultaneously, you can specify a list of interfaces: + (positive integer or list of positive integers)(Optional) This parameter is used to select the bt-interface used. 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 - sensor: - - platform: mitemp_bt - hci_interface: - - 0 - - 1 - ``` + ```yaml + sensor: + - platform: mitemp_bt + hci_interface: + - 0 + - 1 + ``` - Default value: 0 + Default value: 0 #### batt_entities - (boolean)(Optional) By default, the battery information will be presented only as a sensor attribute called `battery level`. If you set this parameter to `True`, then the battery sensor entity will be additionally created - `sensor.mi_batt_ `. Default value: False + (boolean)(Optional) By default, the battery information will be presented only as a sensor attribute called `battery level`. If you set this parameter to `True`, then the battery sensor entity will be additionally created - `sensor.mi_batt_ `. Default value: False #### encryptors - (dictionary)(Optional) This option is used to link the mac-address of the sensor broadcasting encrypted advertisements to the encryption key (32 characters = 16 bytes). This is only needed for LYWSD03MMC and CGD1 sensors. 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/sensor.mitemp_bt/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key). Default value: Empty + (dictionary)(Optional) This option is used to link the mac-address of the sensor broadcasting encrypted advertisements to the encryption key (32 characters = 16 bytes). This is only needed for LYWSD03MMC and CGD1 sensors. 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/sensor.mitemp_bt/blob/master/faq.md#my-sensors-ble-advertisements-are-encrypted-how-can-i-get-the-key). Default value: Empty -```yaml -sensor: - - platform: mitemp_bt - encryptors: + ```yaml + sensor: + - platform: mitemp_bt + encryptors: 'A4:C1:38:2F:86:6C': '217C568CF5D22808DA20181502D84C1B' 'A4:C1:38:D1:61:7D': 'C99D2313182473B38001086FEBF781BD' -``` + ``` #### report_unknown - (boolean)(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 `True`, then the component will log all messages from unknown Xiaomi ecosystem devices to the Home Assitant log. **Attention!** Enabling this option can lead to huge output to the Home Assistant log, do not enable it if you do not need it! Details in the [FAQ](https://github.com/custom-components/sensor.mitemp_bt/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 + (boolean)(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 `True`, then the component will log all messages from unknown Xiaomi ecosystem devices to the Home Assitant log. **Attention!** Enabling this option can lead to huge output to the Home Assistant log, do not enable it if you do not need it! Details in the [FAQ](https://github.com/custom-components/sensor.mitemp_bt/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 + +#### whitelist + + (list or boolean)(Optional) By default, the component creates entities for all detected 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 list the MAC-addresses of the sensors you need in the `whitelist` option: + + ```yaml + sensor: + - platform: mitemp_bt + whitelist: + - '58:C1:38:2F:86:6C' + - 'C4:FA:64:D1:61:7D' + ``` + + data from sensors with other addresses will be ignored. + In addition, all addresses listed in the `encryptors` option will be automatically whitelisted. + If you have no sensors other than those listed in `encryptors`, then just set `whitelist` to `True`: + + ```yaml + sensor: + - platform: mitemp_bt + encryptors: + 'A4:C1:38:2F:86:6C': '217C568CF5D22808DA20181502D84C1B' + 'A4:C1:38:D1:61:7D': 'C99D2313182473B38001086FEBF781BD' + whitelist: True + ``` + + Default value: False + ## FREQUENTLY ASKED QUESTIONS diff --git a/sensors.jpg b/sensors.jpg index 4ff5d6275..e61e806e3 100644 Binary files a/sensors.jpg and b/sensors.jpg differ