Add aqara locks

Author: Ernst79

custom_components/ble_monitor/binary_sensor.py

@@ -256,10 +256,6 @@ async def async_added_to_hass(self):
             self._state = True
         elif old_state.state == STATE_OFF:
             self._state = False
-        if "status" in old_state.attributes:
-            self._extra_state_attributes["status"] = old_state.attributes[
-                "status"
-            ]
         if "rssi" in old_state.attributes:
             self._extra_state_attributes["rssi"] = old_state.attributes["rssi"]
         if "firmware" in old_state.attributes:
@@ -272,6 +268,25 @@ async def async_added_to_hass(self):
             self._extra_state_attributes[ATTR_BATTERY_LEVEL] = old_state.attributes[
                 ATTR_BATTERY_LEVEL
             ]
+        if "status" in old_state.attributes:
+            self._extra_state_attributes["status"] = old_state.attributes["status"]
+        if "motion timer" in old_state.attributes:
+            self._extra_state_attributes["motion timer"] = old_state.attributes[
+                "motion timer"
+            ]
+        if "action" in old_state.attributes:
+            self._extra_state_attributes["action"] = old_state.attributes["action"]
+        if "method" in old_state.attributes:
+            self._extra_state_attributes["method"] = old_state.attributes["method"]
+        if "error" in old_state.attributes:
+            self._extra_state_attributes["error"] = old_state.attributes["error"]
+        if "key id" in old_state.attributes:
+            self._extra_state_attributes["key id"] = old_state.attributes["key id"]
+        if "timestamp" in old_state.attributes:
+            self._extra_state_attributes["timestamp"] = old_state.attributes["timestamp"]
+        if "result" in old_state.attributes:
+            self._extra_state_attributes["result"] = old_state.attributes["result"]
+
         self.ready_for_update = True
 
     @property
@@ -358,6 +373,15 @@ def collect(self, data, batt_attr=None):
                 self._extra_state_attributes["status"] = self._newstate
         if self.entity_description.key == "opening":
             self._extra_state_attributes["status"] = data["status"]
+        if self.entity_description.key == "lock":
+            self._extra_state_attributes["action"] = data["action"]
+            self._extra_state_attributes["method"] = data["method"]
+            self._extra_state_attributes["error"] = data["error"]
+            self._extra_state_attributes["key id"] = data["key id"]
+            self._extra_state_attributes["timestamp"] = data["timestamp"]
+        if self.entity_description.key == "fingerprint":
+            self._extra_state_attributes["result"] = data["result"]
+            self._extra_state_attributes["key id"] = data["key id"]
 
     async def async_update(self):
         """Update sensor state and attribute."""

custom_components/ble_monitor/ble_parser/xiaomi.py

@@ -4,6 +4,8 @@
 import struct
 from Cryptodome.Cipher import AES
 
+from homeassistant.util import datetime
+
 _LOGGER = logging.getLogger(__name__)
 
 # Device type dictionary
@@ -46,6 +48,8 @@
     0x04E6: "YLYK01YL-VENFAN",
     0x03BF: "YLYB01YL-BHFRC",
     0x03B6: "YLKG07YL/YLKG08YL",
+    0x069E: "ZNMS16LM",
+    0x069F: "ZNMS17LM",
 }
 
 # Structured objects for data conversions
@@ -61,17 +65,146 @@
 P_STRUCT = struct.Struct("<H")
 BUTTON_STRUCT = struct.Struct("<BBB")
 
+# Definition of lock messages
+BLE_LOCK_ERROR = {
+    0xC0DE0000: "frequent unlocking with incorrect password",
+    0xC0DE0001: "frequent unlocking with wrong fingerprints",
+    0xC0DE0002: "operation timeout (password input timeout)",
+    0xC0DE0003: "lock picking",
+    0xC0DE0004: "reset button is pressed",
+    0xC0DE0005: "the wrong key is frequently unlocked",
+    0xC0DE0006: "foreign body in the keyhole",
+    0xC0DE0007: "the key has not been taken out",
+    0xC0DE0008: "error NFC frequently unlocks",
+    0xC0DE0009: "timeout is not locked as required",
+    0xC0DE000A: "failure to unlock frequently in multiple ways",
+    0xC0DE000B: "unlocking the face frequently fails",
+    0xC0DE000C: "failure to unlock the vein frequently",
+    0xC0DE000D: "hijacking alarm",
+    0xC0DE000E: "unlock inside the door after arming",
+    0xC0DE000F: "palmprints frequently fail to unlock",
+    0xC0DE0010: "the safe was moved",
+    0xC0DE1000: "the battery level is less than 10%",
+    0xC0DE1001: "the battery is less than 5%",
+    0xC0DE1002: "the fingerprint sensor is abnormal",
+    0xC0DE1003: "the accessory battery is low",
+    0xC0DE1004: "mechanical failure",
+    0xC0DE1005: "the lock sensor is faulty",
+}
+
+BLE_LOCK_ACTION = {
+    0b0000: [0, "unlock outside the door"],
+    0b0001: [1, "lock"],
+    0b0010: [1, "turn on anti-lock"],
+    0b0011: [0, "turn off anti-lock"],
+    0b0100: [0, "unlock inside the door"],
+    0b0101: [1, "lock inside the door"],
+    0b0110: [1, "turn on child lock"],
+    0b0111: [0, "turn off child lock"],
+    0b1000: [1, "lock outside the door"],
+    0b1111: [0, "abnormal"],
+}
+
+BLE_LOCK_METHOD = {
+    0b0000: "bluetooth",
+    0b0001: "password",
+    0b0010: "biometrics",
+    0b0011: "key",
+    0b0100: "turntable",
+    0b0101: "nfc",
+    0b0110: "one-time password",
+    0b0111: "two-step verification",
+    0b1001: "Homekit",
+    0b1000: "coercion",
+    0b1010: "manual",
+    0b1011: "automatic",
+    0b1111: "abnormal"
+}
+
 
 # Advertisement conversion of measurement data
 # https://iot.mi.com/new/doc/embedded-development/ble/object-definition
 def obj0003(xobj):
     return {"motion": xobj[0], "motion timer": xobj[0]}
 
 
+def obj0006(xobj):
+    if len(xobj) == 5:
+        key_id = xobj[0:4]
+        match_byte = xobj[4]
+        if key_id == b'\x00\x00\x00\x00':
+            key_id = "administrator"
+        elif key_id == b'\xff\xff\xff\xff':
+            key_id = "unknown operator"
+        else:
+            key_id = int.from_bytes(key_id, 'little')
+        if match_byte == 0x00:
+            result = "match successful"
+        elif match_byte == 0x01:
+            result = "match failed"
+        elif match_byte == 0x02:
+            result = "timeout"
+        elif match_byte == 0x033:
+            result = "low quality (too light, fuzzy)"
+        elif match_byte == 0x04:
+            result = "insufficient area"
+        elif match_byte == 0x05:
+            result = "skin is too dry"
+        elif match_byte == 0x06:
+            result = "skin is too wet"
+        else:
+            result = None
+
+        fingerprint = 1 if match_byte == 0x00 else 0
+
+        return {
+            "fingerprint": fingerprint,
+            "result": result,
+            "key id": key_id,
+        }
+    else:
+        return {}
+
+
 def obj0010(xobj):
     return {"toothbrush mode": xobj[1]}
 
 
+def obj000b(xobj):
+    if len(xobj) == 9:
+        action = xobj[0] & 0x0F
+        method = xobj[0] >> 4
+        key_id = int.from_bytes(xobj[1:5], 'little')
+        timestamp = int.from_bytes(xobj[5:], 'little')
+
+        timestamp = datetime.fromtimestamp(timestamp).isoformat()
+
+        # all keys except Bluetooth have only 65536 values
+        error = BLE_LOCK_ERROR.get(key_id)
+        if error is None and method > 0:
+            key_id &= 0xFFFF
+        elif error:
+            key_id = hex(key_id)
+
+        if action not in BLE_LOCK_ACTION or method not in BLE_LOCK_METHOD:
+            return {}
+
+        lock = BLE_LOCK_ACTION[action][0]
+        action = BLE_LOCK_ACTION[action][1]
+        method = BLE_LOCK_METHOD[method]
+
+        return {
+            "lock": lock,
+            "action": action,
+            "method": method,
+            "error": error,
+            "key id": key_id,
+            "timestamp": timestamp,
+        }
+    else:
+        return {}
+
+
 def obj000f(xobj):
     if len(xobj) == 3:
         (value,) = LIGHT_STRUCT.unpack(xobj + b'\x00')
@@ -370,7 +503,9 @@ def obj2000(xobj):
 # {dataObject_id: (converter}
 xiaomi_dataobject_dict = {
     0x0003: obj0003,
+    0x0006: obj0006,
     0x0010: obj0010,
+    0x000B: obj000b,
     0x000F: obj000f,
     0x1001: obj1001,
     0x1004: obj1004,

custom_components/ble_monitor/const.py

@@ -9,6 +9,7 @@
     DEVICE_CLASS_MOTION,
     DEVICE_CLASS_OPENING,
     DEVICE_CLASS_SMOKE,
+    DEVICE_CLASS_LOCK,
     BinarySensorEntityDescription,
 )
 from homeassistant.components.sensor import (
@@ -185,6 +186,21 @@ class BLEMonitorBinarySensorEntityDescription(
         unique_id="sd_",
         device_class=DEVICE_CLASS_SMOKE,
     ),
+    BLEMonitorBinarySensorEntityDescription(
+        key="fingerprint",
+        sensor_class="BaseBinarySensor",
+        name="ble fingerprint",
+        icon="mdi:fingerprint",
+        unique_id="fp_",
+        device_class=None,
+    ),
+    BLEMonitorBinarySensorEntityDescription(
+        key="lock",
+        sensor_class="BaseBinarySensor",
+        name="ble lock",
+        unique_id="lock_",
+        device_class=DEVICE_CLASS_LOCK,
+    ),
 )
 
 
@@ -534,6 +550,8 @@ class BLEMonitorBinarySensorEntityDescription(
     'RTCGQ02LM'               : [["battery"], ["button"], ["light", "motion"]],
     'MMC-T201-1'              : [["temperature", "battery"], [], []],
     'M1S-T500'                : [["battery"], ["toothbrush mode"], []],
+    'ZNMS16LM'                : [["battery"], [], ["lock", "fingerprint"]],
+    'ZNMS17LM'                : [["battery"], [], ["lock", "fingerprint"]],
     'CGC1'                    : [["temperature", "humidity", "battery"], [], []],
     'CGD1'                    : [["temperature", "humidity", "battery"], [], []],
     'CGDK2'                   : [["temperature", "humidity", "battery"], [], []],
@@ -599,6 +617,8 @@ class BLEMonitorBinarySensorEntityDescription(
     'RTCGQ02LM'               : 'Xiaomi',
     'MMC-T201-1'              : 'Xiaomi',
     'M1S-T500'                : 'Xiaomi Soocas',
+    'ZNMS16LM'                : 'Xiaomi Aqara',
+    'ZNMS17LM'                : 'Xiaomi Aqara',
     'CGC1'                    : 'Qingping',
     'CGD1'                    : 'Qingping',
     'CGDK2'                   : 'Qingping',

custom_components/ble_monitor/test/test_xiaomi_parser.py

@@ -324,6 +324,47 @@ def test_Xiaomi_M1S_T500(self):
         assert sensor_msg["toothbrush mode"] == 3
         assert sensor_msg["rssi"] == -36
 
+    def test_Xiaomi_ZNMS16LM_fingerprint(self):
+        """Test Xiaomi parser for ZNMS16LM."""
+        data_string = "043e2a02010000918aeb441fd71e020106030295fe161695fe50449e0642918aeb441fd7060005ffffffff00a9"
+        data = bytes(bytearray.fromhex(data_string))
+
+        # pylint: disable=unused-variable
+        ble_parser = BleParser()
+        sensor_msg, tracker_msg = ble_parser.parse_data(data)
+
+        assert sensor_msg["firmware"] == "Xiaomi (MiBeacon V4)"
+        assert sensor_msg["type"] == "ZNMS16LM"
+        assert sensor_msg["mac"] == "D71F44EB8A91"
+        assert sensor_msg["packet"] == 66
+        assert sensor_msg["data"]
+        assert sensor_msg["fingerprint"] == 1
+        assert sensor_msg["result"] == "match successful"
+        assert sensor_msg["key id"] == "unknown operator"
+        assert sensor_msg["rssi"] == -87
+
+    def test_Xiaomi_ZNMS16LM_lock(self):
+        """Test Xiaomi parser for ZNMS16LM."""
+        data_string = "043e2e02010000918aeb441fd722020106030295fe1a1695fe50449e0643918aeb441fd70b000920020001807c442f61a9"
+        data = bytes(bytearray.fromhex(data_string))
+
+        # pylint: disable=unused-variable
+        ble_parser = BleParser()
+        sensor_msg, tracker_msg = ble_parser.parse_data(data)
+
+        assert sensor_msg["firmware"] == "Xiaomi (MiBeacon V4)"
+        assert sensor_msg["type"] == "ZNMS16LM"
+        assert sensor_msg["mac"] == "D71F44EB8A91"
+        assert sensor_msg["packet"] == 67
+        assert sensor_msg["data"]
+        assert sensor_msg["lock"] == 0
+        assert sensor_msg["action"] == "unlock outside the door"
+        assert sensor_msg["method"] == "biometrics"
+        assert sensor_msg["error"] is None
+        assert sensor_msg["key id"] == 2
+        assert sensor_msg["timestamp"] == "2021-09-01T11:14:36"
+        assert sensor_msg["rssi"] == -87
+
     def test_Xiaomi_YLAI003(self):
         """Test Xiaomi parser for YLAI003."""
 

docs/_devices/ZNMS16LM.md

@@ -0,0 +1,75 @@
+---
+manufacturer: Xiaomi Aqara
+name: Lock N100
+model: ZNMS16LM
+image: ZNMS16LM.png
+physical_description:
+broadcasted_properties:
+  - fingerprint
+  - lock
+  - battery
+  - result
+  - key id
+  - action
+  - method
+  - error
+  - timestamp
+broadcasted_property_notes:
+  - property: fingerprint
+    note: The fingerprint sensor is `On` if the fingerprint scan was succesful, otherwise it is `Off` The fingerprint entity has two extra attributes, `result` and `key id`.
+  - property: result
+    note: >
+      `result` shows the result of the last fingerprint reading and can have the following values:
+        * match successful
+        * match failed
+        * timeout
+        * low quality (too light, fuzzy)
+        * insufficient area
+        * skin is too dry
+        * skin is too wet
+  - property: key id
+    note: >
+      `key id` is an id number. For the fingerprint sensor, it can also be `administrator` or `unknown operator`
+  - property: lock
+    note: The state of the lock depends on the last `action`. The lock entity has five extra attributes, `action`, `method`, `error` and `key id` and `timestamp`
+  - property: action
+    note: >
+      `action` shows the last change in of the lock and can have the followng values:
+        * unlock outside the door
+        * lock
+        * turn on anti-lock
+        * turn off anti-lock
+        * unlock inside the door
+        * lock inside the door
+        * turn on child lock
+        * turn off child lock
+        * lock outside the door
+        * abnormal
+  - property: method
+    note: >
+      `method` shows the last used locking mechanism and can have the following values:
+        * unlock outside the door
+        * lock
+        * bluetooth
+        * password
+        * biometrics
+        * key
+        * turntable
+        * nfc
+        * one-time password
+        * two-step verification
+        * Homekit
+        * coercion
+        * manual
+        * automatic
+        * abnormal
+  - property: error
+    note: The error state of the lock
+  - property: timestamp
+    note: The timestamp of the latest lock change
+broadcast_rate:
+active_scan:
+encryption_key:
+custom_firmware:
+notes: Bluetooth version
+---