hansa-ble-protocol 0.2.0__py3-none-any.whl

hansa_ble_protocol/__init__.py

@@ -0,0 +1,99 @@
+"""Wire protocol of Hansa/Oras Bluetooth faucets.
+
+This package knows how to read and write the bytes; it opens no connections
+and depends on no Bluetooth stack, so it can be tested without hardware.
+"""
+
+from .const import (
+    CH_COMMAND,
+    CH_COUNTER_A,
+    CH_COUNTER_B,
+    CH_COUNTER_C,
+    CH_NONCE,
+    CH_PARAM_A,
+    CH_PARAM_B,
+    CH_PARAM_C,
+    CH_PASSWORD,
+    CH_PRODUCT_INFO,
+    CH_PRODUCT_LOCATION,
+    CH_PRODUCT_NAME,
+    CH_STATE_A,
+    CH_STATE_B,
+    CMD_CLEANING,
+    CMD_COUNTER_RESET,
+    CMD_LOG_RESET,
+    CMD_NORMAL,
+    CMD_OPEN,
+    CMD_PAIRING_CLEAR,
+    CMD_PAIRING_START,
+    CMD_WINK,
+    MANUFACTURER,
+    MANUFACTURER_ID,
+    SERVICE_INFO,
+    SERVICE_SETTINGS,
+    SERVICE_TESTING,
+)
+from .protocol import (
+    PARAM_A_FIELDS,
+    FaucetData,
+    auth_response,
+    is_authenticated,
+    parse_advertisement,
+    parse_counter_a,
+    parse_counter_b,
+    parse_counter_c,
+    parse_param_a,
+    parse_product_info,
+    parse_product_location,
+    parse_product_name,
+    parse_state_a,
+    parse_state_b,
+    session_key,
+    write_param_a,
+)
+
+__all__ = [
+    "CH_COMMAND",
+    "CH_COUNTER_A",
+    "CH_COUNTER_B",
+    "CH_COUNTER_C",
+    "CH_NONCE",
+    "CH_PARAM_A",
+    "CH_PARAM_B",
+    "CH_PARAM_C",
+    "CH_PASSWORD",
+    "CH_PRODUCT_INFO",
+    "CH_PRODUCT_LOCATION",
+    "CH_PRODUCT_NAME",
+    "CH_STATE_A",
+    "CH_STATE_B",
+    "CMD_CLEANING",
+    "CMD_COUNTER_RESET",
+    "CMD_LOG_RESET",
+    "CMD_NORMAL",
+    "CMD_OPEN",
+    "CMD_PAIRING_CLEAR",
+    "CMD_PAIRING_START",
+    "CMD_WINK",
+    "MANUFACTURER",
+    "MANUFACTURER_ID",
+    "PARAM_A_FIELDS",
+    "SERVICE_INFO",
+    "SERVICE_SETTINGS",
+    "SERVICE_TESTING",
+    "FaucetData",
+    "auth_response",
+    "is_authenticated",
+    "parse_advertisement",
+    "parse_counter_a",
+    "parse_counter_b",
+    "parse_counter_c",
+    "parse_param_a",
+    "parse_product_info",
+    "parse_product_location",
+    "parse_product_name",
+    "parse_state_a",
+    "parse_state_b",
+    "session_key",
+    "write_param_a",
+]

hansa_ble_protocol/const.py

@@ -0,0 +1,41 @@
+"""Constants of the Hansa/Oras wire protocol.
+
+Every value here was derived from the vendor app and verified against a real
+device; docs/protocol.md records how each one was established.
+"""
+
+from typing import Final
+
+MANUFACTURER: Final = "Hansa"
+MANUFACTURER_ID: Final = 305  # 0x0131
+
+SERVICE_INFO: Final = "2be32db1-5f6b-4cbd-8803-38d6dfb16490"
+SERVICE_SETTINGS: Final = "2be32db1-5f6b-5bd8-8033-8d6dfb164900"
+SERVICE_TESTING: Final = "2be32db1-5f6b-6bd8-8033-8d6dfb164900"
+
+# Handles differ per device, so everything is addressed by UUID.
+CH_PRODUCT_INFO: Final = "2be32db1-5f6b-4cbd-8813-8d6dfb164900"
+CH_PRODUCT_NAME: Final = "2be32db1-5f6b-4cbd-8823-8d6dfb164900"
+CH_PRODUCT_LOCATION: Final = "2be32db1-5f6b-4cbd-8833-8d6dfb164900"
+CH_STATE_A: Final = "2be32db1-5f6b-4cbd-8843-8d6dfb164900"
+CH_STATE_B: Final = "2be32db1-5f6b-4cbd-8853-8d6dfb164900"
+CH_COUNTER_A: Final = "2be32db1-5f6b-4cbd-8863-8d6dfb164900"
+CH_COUNTER_B: Final = "2be32db1-5f6b-4cbd-8873-8d6dfb164900"
+CH_COUNTER_C: Final = "2be32db1-5f6b-4cbd-8883-8d6dfb164900"
+
+CH_PARAM_A: Final = "2be32db1-5f6b-5bd8-8138-d6dfb1649000"
+CH_PARAM_B: Final = "2be32db1-5f6b-5bd8-8238-d6dfb1649000"
+CH_PARAM_C: Final = "2be32db1-5f6b-5bd8-8338-d6dfb1649000"
+CH_COMMAND: Final = "2be32db1-5f6b-5bd8-8a38-d6dfb1649000"
+CH_PASSWORD: Final = "2be32db1-5f6b-5bd8-8b38-d6dfb1649000"
+CH_NONCE: Final = "2be32db1-5f6b-5bd8-8e8d-6dfb16490000"
+
+# A single byte written to CH_COMMAND once authenticated.
+CMD_WINK: Final = 0x51
+CMD_OPEN: Final = 0x62
+CMD_CLEANING: Final = 0x73
+CMD_NORMAL: Final = 0x84
+CMD_LOG_RESET: Final = 0x52
+CMD_COUNTER_RESET: Final = 0xA6
+CMD_PAIRING_START: Final = 0x40
+CMD_PAIRING_CLEAR: Final = 0x42

hansa_ble_protocol/protocol.py

@@ -0,0 +1,186 @@
+"""Wire format of the Hansa/Oras faucet: authentication and decoding.
+
+Reconstructed from the vendor app and checked against a real device. All
+integers are little endian, times are seconds, valve open time is in tenths
+of a second and the battery voltage is in hundredths of a volt.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.ciphers.aead import AESCCM
+
+# Fixed bootstrap key taken from the vendor app: sixteen 0x01 bytes.
+_BOOTSTRAP_KEY = bytes([0x01] * 16)
+
+# CCM with L=2 leaves 15-L = 13 bytes of nonce.
+_NONCE_LEN = 13
+
+
+def _ctr_keystream(key: bytes, nonce: bytes, blocks: int) -> bytes:
+    """CCM keystream A_1..A_n. A_0 only feeds the tag and is not needed here."""
+    cipher = Cipher(algorithms.AES(key), modes.ECB())
+    stream = b""
+    for counter in range(1, blocks + 1):
+        block = bytes([1]) + nonce + counter.to_bytes(2, "big")  # flags: L-1 = 1
+        encryptor = cipher.encryptor()
+        stream += encryptor.update(block) + encryptor.finalize()
+    return stream
+
+
+def session_key(nonce: bytes, password: bytes) -> bytes:
+    """Derive the session key from the nonce and the password characteristic.
+
+    The app nominally decrypts this with AES-CCM, but the tag area of the
+    buffer is all zeroes, so an authenticated decrypt could never verify.
+    Only the CTR half matters, and that is a plain XOR with the keystream.
+    """
+    keystream = _ctr_keystream(_BOOTSTRAP_KEY, nonce[:_NONCE_LEN], 1)
+    return bytes(a ^ b for a, b in zip(password[:16], keystream, strict=False))
+
+
+def auth_response(nonce: bytes, password: bytes, pin: str) -> bytes:
+    """Build the 16 bytes written back to the password characteristic."""
+    ccm = AESCCM(session_key(nonce, password), tag_length=8)
+    digest = hashlib.md5(pin.encode(), usedforsecurity=False).digest()
+    return ccm.encrypt(nonce[:_NONCE_LEN], digest, None)[:16]
+
+
+def is_authenticated(nonce: bytes) -> bool:
+    """Report whether the faucet flipped byte 15 of the nonce to 0xFF."""
+    return len(nonce) > 15 and nonce[15] == 0xFF
+
+
+def _u16(data: bytes, offset: int) -> int:
+    """Two bytes, little endian."""
+    return int.from_bytes(data[offset : offset + 2], "little")
+
+
+def _u32(data: bytes, offset: int) -> int:
+    """Four bytes, little endian."""
+    return int.from_bytes(data[offset : offset + 4], "little")
+
+
+def _text(data: bytes) -> str:
+    """Decode an ASCII field padded with NUL bytes."""
+    return data.decode("ascii", "replace").replace("\x00", " ").strip()
+
+
+def parse_advertisement(manufacturer_data: bytes) -> dict[str, Any]:
+    """Battery level and installation location, no connection required."""
+    if len(manufacturer_data) < 13:
+        return {}
+    return {
+        "battery_level": manufacturer_data[1] & 0x7F,
+        "location": _text(manufacturer_data[3:13]),
+    }
+
+
+def parse_state_a(data: bytes) -> dict[str, Any]:
+    """Decode the status byte, valve flag, battery and detection range."""
+    return {
+        "device_status": data[0],
+        "sensor_error": data[1],
+        "operating_mode": data[2],
+        "valve_open": bool(data[3]),
+        "battery_voltage": _u16(data, 4) / 100,
+        "battery_level": _u16(data, 6),
+        "detection_range": _u16(data, 12),
+    }
+
+
+def parse_state_b(data: bytes) -> dict[str, Any]:
+    """Decode the timers the faucet keeps: idle time and flush countdown."""
+    return {
+        "since_last_use": _u32(data, 4),
+        "until_next_flush": _u32(data, 8),
+        "since_reset": _u32(data, 12),
+    }
+
+
+def parse_counter_a(data: bytes) -> dict[str, Any]:
+    """Decode the lifetime counters for openings, run time and flushes."""
+    return {
+        "openings": _u32(data, 0),
+        "open_time": _u32(data, 8) / 10,  # tenths of a second
+        "auto_flushes": _u32(data, 12),
+        "manual_flushes": _u32(data, 16),
+    }
+
+
+def parse_counter_b(data: bytes) -> dict[str, Any]:
+    """Decode the total volume the faucet has computed."""
+    # Bytes 0-3 hold the total volume; counter A repeats after that.
+    return {"total_volume": _u32(data, 0)}
+
+
+def parse_counter_c(data: bytes) -> dict[str, Any]:
+    """Decode the resettable interim counter."""
+    return {
+        "interim_volume": _u32(data, 4),
+        "since_counter_reset": _u32(data, 8),
+    }
+
+
+def parse_product_info(data: bytes) -> dict[str, Any]:
+    """Decode the sensor number and hardware revision."""
+    return {"sensor_number": _text(data[0:7]), "hardware_version": _text(data[10:15])}
+
+
+def parse_product_name(data: bytes) -> dict[str, Any]:
+    """Decode the serial number and product name."""
+    return {"serial_number": _u32(data, 0), "product_name": _text(data[4:])}
+
+
+def parse_product_location(data: bytes) -> dict[str, Any]:
+    """Decode the installation location and date of manufacture."""
+    return {"location": _text(data[0:15]), "manufactured": _text(data[15:19])}
+
+
+# productParamA: one 16 bit little endian value per field, order per the app.
+PARAM_A_FIELDS: tuple[str, ...] = (
+    "min_signal_level",
+    "min_signal_level_flow",
+    "sensitivity",
+    "max_ir_power",
+    "force_level",
+    "max_run_time",
+    "manual_flush_time",
+    "cleaning_mode_time",
+    "generic_a1",
+    "run_on_time",
+)
+
+
+def parse_param_a(data: bytes) -> dict[str, Any]:
+    """Decode the adjustable settings block, field by field."""
+    return {
+        name: _u16(data, index * 2)
+        for index, name in enumerate(PARAM_A_FIELDS)
+        if index * 2 + 1 < len(data)
+    }
+
+
+def write_param_a(current: bytes, name: str, value: int) -> bytes:
+    """Change one field of productParamA, leaving the rest exactly as read."""
+    if name not in PARAM_A_FIELDS:
+        raise ValueError(f"unknown field: {name}")
+    offset = PARAM_A_FIELDS.index(name) * 2
+    updated = bytearray(current)
+    updated[offset : offset + 2] = int(value).to_bytes(2, "little")
+    return bytes(updated)
+
+
+@dataclass(slots=True)
+class FaucetData:
+    """Everything one poll produces, plus what the advertisement carried."""
+
+    values: dict[str, Any] = field(default_factory=dict)
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """Return one value, or the default when the faucet did not report it."""
+        return self.values.get(name, default)

hansa_ble_protocol-0.2.0.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: hansa-ble-protocol
+Version: 0.2.0
+Summary: Wire protocol of Hansa/Oras Bluetooth Low Energy faucets
+Project-URL: Homepage, https://github.com/skjall/home-assistant-hansa-ble
+Project-URL: Source, https://github.com/skjall/home-assistant-hansa-ble/tree/main/lib/hansa_ble_protocol
+Project-URL: Issues, https://github.com/skjall/home-assistant-hansa-ble/issues
+Author: Jan Großheim
+License-Expression: MIT
+Keywords: ble,bluetooth,faucet,hansa,home-assistant,oras
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0.0
+Description-Content-Type: text/markdown
+
+# hansa-ble-protocol
+
+The wire protocol of Hansa and Oras electronic faucets that speak Bluetooth
+Low Energy: how to decode what they send, how to encode what they accept, and
+how the PIN exchange works.
+
+This package handles bytes only. It opens no connections and pulls in no
+Bluetooth stack, so it runs and tests without hardware. The Home Assistant
+integration that uses it lives in the
+[parent repository](https://github.com/skjall/home-assistant-hansa-ble); how
+each byte offset was established is documented in
+[docs/protocol.md](https://github.com/skjall/home-assistant-hansa-ble/blob/main/docs/protocol.md).
+
+```python
+from hansa_ble_protocol import parse_state_a, auth_response
+
+state = parse_state_a(raw_bytes)
+print(state["valve_open"], state["battery_level"])
+
+# Answer the faucet's challenge with the PIN from the vendor app.
+response = auth_response(nonce, password, "1234")
+```
+
+Not affiliated with, endorsed by, or supported by Hansa or Oras.
+
+## License
+
+MIT

hansa_ble_protocol-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+hansa_ble_protocol/__init__.py,sha256=XjqxuEvACrTPiletp7wJ5JDCvvzSgfBEjy-6aab_Nqo,2019
+hansa_ble_protocol/const.py,sha256=fZmrGbsdHYxc8rIxNezS7ZsL7xYlT2cYw1kk06y7JfU,1676
+hansa_ble_protocol/protocol.py,sha256=PvJqFpPzZ813LQHZL4YoMCizV4jnJa2rjSFMDDR_wNM,6398
+hansa_ble_protocol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hansa_ble_protocol-0.2.0.dist-info/METADATA,sha256=479yh_fMV5ia8p7dqJrfyg9opCJCwW_fwWpLkevFQtE,1818
+hansa_ble_protocol-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+hansa_ble_protocol-0.2.0.dist-info/RECORD,,

hansa_ble_protocol-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any