brymenble 0.5.2__py3-none-any.whl

brymenble/__init__.py

@@ -0,0 +1,81 @@
+"""brymenble — unofficial, open-source SDK for the Brymen BM78xBT BLE multimeter.
+
+Public API:
+
+- ``BrymenbleClient``: connect/authenticate/subscribe and stream parsed frames
+- ``parsers``: ``InfoPacket`` / ``ReadingPacket`` / ``RtcTime`` and parse helpers
+- ``commands``: command-packet builders
+- ``formatter``: turn a parsed reading into a display string
+- ``console``: shared console output (status lines) for every consumer
+- ``scanner``: find BM78xBT meters from their BLE advertising packets
+- ``crc`` / ``constants``: protocol primitives
+"""
+
+from . import commands, console, constants, crc, formatter, parsers, scanner
+from .commands import (
+    build_command_packet,
+    build_rtc_time_packet,
+    build_verify_password_packet,
+)
+from .crc import calculate_crc, verify_crc
+from .formatter import format_reading
+from .parsers import (
+    CommandResponse,
+    InfoPacket,
+    ReadingPacket,
+    RtcTime,
+    StreamFrame,
+    parse_command_response,
+    parse_info_packet,
+    parse_reading_packet,
+    parse_stream_frame,
+)
+from .transport import (
+    BrymenbleClient,
+    COMMAND_CHAR_UUID,
+    DEFAULT_PASSWORD,
+    NOTIFY_CHAR_UUID,
+    CommandError,
+)
+from .scanner import (
+    DiscoveredMeter,
+    find_first_meter,
+    find_meters,
+    is_brymenble_advertisement,
+)
+
+__version__ = "0.5.2"
+
+__all__ = [
+    "commands",
+    "console",
+    "constants",
+    "crc",
+    "formatter",
+    "parsers",
+    "scanner",
+    "find_first_meter",
+    "find_meters",
+    "is_brymenble_advertisement",
+    "DiscoveredMeter",
+    "build_command_packet",
+    "build_rtc_time_packet",
+    "build_verify_password_packet",
+    "calculate_crc",
+    "verify_crc",
+    "format_reading",
+    "InfoPacket",
+    "ReadingPacket",
+    "RtcTime",
+    "StreamFrame",
+    "CommandResponse",
+    "parse_info_packet",
+    "parse_reading_packet",
+    "parse_stream_frame",
+    "parse_command_response",
+    "BrymenbleClient",
+    "CommandError",
+    "COMMAND_CHAR_UUID",
+    "DEFAULT_PASSWORD",
+    "NOTIFY_CHAR_UUID",
+]

brymenble/commands.py

@@ -0,0 +1,83 @@
+"""Building of BM78xBT command packets (32 bytes, see protocol spec section 2)."""
+
+from datetime import datetime
+from typing import Optional, Union
+
+from . import constants
+from . import crc
+
+
+def build_command_packet(
+    mac_address: str, command_id: Union[int, bytes], args: bytes = b""
+) -> bytes:
+    """
+    Build a 32-byte command packet.
+
+    Args:
+        mac_address: BLE device address as 'XX:XX:XX:XX:XX:XX'.
+        command_id:  command ID as a 2-byte little-endian bytes value
+                     (e.g. constants.CMD_VERIFY_PASSWORD) or as an int
+                     (e.g. constants.CMD_RTC_TIME_CALIBRATION).
+        args:        command-specific arguments (up to 14 bytes), zero-padded.
+
+    Raises:
+        ValueError: if mac_address is not a 6-byte address or command_id is
+                    not a valid 2-byte ID.
+    """
+    mac_bytes = bytes.fromhex(mac_address.replace(':', ''))
+    if len(mac_bytes) != 6:
+        raise ValueError("MAC address must be 6 bytes")
+    if isinstance(command_id, int):
+        command_id = command_id.to_bytes(2, 'little')
+    if len(command_id) != 2:
+        raise ValueError("command_id must be exactly 2 bytes")
+
+    header = bytes([constants.COMMAND_HEAD_BYTE0, constants.COMMAND_HEAD_BYTE1])
+    payload = (
+        bytes([
+            constants.COMMAND_PACKET_LEN_BYTE,
+            constants.COMMAND_PACKET_TYPE,
+            constants.PROTOCOL_VERSION,
+        ])
+        + mac_bytes[::-1]  # BLE device address, reversed byte order
+        + command_id
+        + bytes([constants.PASSWORD_ID])
+        + args.ljust(14, b'\x00')
+    )
+    crc_bytes = crc.calculate_crc(payload).to_bytes(2, 'little')
+    footer = bytes([constants.COMMAND_END_BYTE0, constants.COMMAND_END_BYTE1])
+    return header + payload + crc_bytes + footer
+
+
+def build_verify_password_packet(mac_address: str, password: str = "0000") -> bytes:
+    """Build a 'Verify Password' (0x0151) command packet."""
+    if len(password) != 4 or not password.isdigit():
+        raise ValueError("Password must be a 4-digit string")
+    args = bytes(int(ch) for ch in password)
+    return build_command_packet(mac_address, constants.CMD_VERIFY_PASSWORD, args)
+
+
+def encode_rtc_time_args(when: datetime) -> bytes:
+    """Encode a datetime as RTC Calibration (0x0010) args.
+
+    Arg[0..6] = second, minute, hour, date, day-of-week (Mon=1..Sun=7),
+    month, year-2000; Arg[7..13] zero (see protocol spec).
+    """
+    day_of_week = when.weekday() + 1        # Mon=1 .. Sun=7 (protocol range)
+    return bytes([
+        when.second, when.minute, when.hour, when.day,
+        day_of_week, when.month, when.year - 2000,
+    ]) + b'\x00' * 7
+
+
+def build_rtc_time_packet(mac_address: str, when: Optional[datetime] = None) -> bytes:
+    """Build an 'RTC Time Calibration' (0x0010) command packet.
+
+    The meter has no RTC battery, so its clock resets on power-off and must be
+    re-synced after connecting. Defaults to the host's local time.
+    """
+    if when is None:
+        when = datetime.now()
+    return build_command_packet(
+        mac_address, constants.CMD_RTC_TIME_CALIBRATION, encode_rtc_time_args(when)
+    )

brymenble/console.py

@@ -0,0 +1,115 @@
+"""Shared console output for every brymenble consumer.
+
+All streaming consumers — ``examples/live.py``, ``tools/connection_state.py``,
+the display overlay, the TestController bridge — print the same timestamped
+status lines, lifecycle events and reading format via this module, so the
+console looks uniform no matter which tool is running.
+
+Reading lines use the SDK's protocol-faithful formatter (overload -> ``OL``).
+Consumers that add their own display accommodations at the UI layer (e.g. the
+overlay/bridge showing ``----`` for a temperature overload) still override
+there; the shared format itself stays protocol-faithful.
+"""
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from typing import Optional, TextIO
+
+from .formatter import format_reading
+from .parsers import ReadingPacket
+
+
+def ts() -> str:
+    """``[HH:MM:SS.mmm]`` prefix used by every status line."""
+    now = datetime.now()
+    return f"{now:%H:%M:%S}.{now.microsecond // 1000:03d}"
+
+
+def status(message: str, *, stream: Optional[TextIO] = None) -> None:
+    """Print a timestamped event line: ``[HH:MM:SS] message``."""
+    print(f"[{ts()}] {message}", file=stream, flush=True)
+
+
+def reading_line(reading: Optional[ReadingPacket]) -> str:
+    """One-line display of a reading: ``DCV 607.80 V`` / ``Resistance OL``.
+
+    Mirrors the meter LCD: ``<function> <value>``. Overload/ASCII states show
+    as ``<function> OL`` / ``<function> <text>``.
+    """
+    if reading is None:
+        return "?"
+    if reading.is_overload:
+        return f"{reading.function_name} OL"
+    if reading.is_ascii:
+        return f"{reading.function_name} {reading.ascii_text or '?'}"
+    return f"{reading.function_name} {format_reading(reading)}"
+
+
+# --- lifecycle events (drop-in SDK callbacks / wrappers) -----------------
+
+def retry(attempt: int, max_retries: Optional[int], error: Exception) -> None:
+    """SDK ``on_retry`` callback: ``[HH:MM:SS] retry N[/M]: <error>``."""
+    label = f"retry {attempt}" if max_retries is None else f"retry {attempt}/{max_retries}"
+    status(f"{label}: {error}")
+
+
+def paused(seconds: float = 1.0) -> None:
+    """Link-up silence = pause (e.g. function switch). Deliberately silent:
+    the pause is a lifecycle event (``on_pause``) that consumers act on — e.g.
+    the overlay blanks its display — not a status line. Kept so
+    ``on_pause=console.paused`` remains a valid hook."""
+
+
+def lost(reason: str = "link_down") -> None:
+    """SDK ``on_lost`` callback: link-down (power off) or pause_cap."""
+    if reason == "pause_cap":
+        status("link up but silent too long — forcing reconnect")
+    else:
+        status("BLE link lost — meter powered off; reconnecting")
+
+
+def reconnected() -> None:
+    """SDK ``on_reconnected`` callback."""
+    status("reconnected and subscribed")
+
+
+def scanning() -> None:
+    status("scanning for a BM78xBT meter...")
+
+
+def scanning_retry(attempt: int) -> None:
+    status(f"no BM78xBT meter in range yet (attempt {attempt}) — retrying...")
+
+
+def using(mac: str, name: Optional[str] = None) -> None:
+    status(f"using {name or 'BM78xBT'} at {mac}")
+
+
+def connecting(mac: str) -> None:
+    """``[HH:MM:SS] connecting to <mac>...``"""
+    status(f"connecting to {mac}...")
+
+
+def connected(mac: str, *, detail: Optional[str] = None) -> None:
+    """``[HH:MM:SS] connected to <mac>[ — <detail>]``"""
+    suffix = f" — {detail}" if detail else ""
+    status(f"connected to {mac}{suffix}")
+
+
+def disconnected() -> None:
+    """``[HH:MM:SS] disconnected``"""
+    status("disconnected")
+
+
+def found(mac: str, name: Optional[str] = None, rssi: Optional[float] = None) -> None:
+    """``[HH:MM:SS] found <name> at <mac>[, rssi=..]`` — a meter from a scan."""
+    label = name or "BM78xBT"
+    rssi_txt = f", rssi={rssi}" if rssi is not None else ""
+    status(f"found {label} at {mac}{rssi_txt}")
+
+
+def state(name: str, detail: str, *, stream: Optional[TextIO] = None) -> None:
+    """A link/data state-report line: ``[HH:MM:SS] <name>  <detail>`` with the
+    state name padded to a 20-char column (used by the connection-state tools)."""
+    print(f"[{ts()}] {name:<20} {detail}", file=stream, flush=True)

brymenble/constants.py

@@ -0,0 +1,185 @@
+# Lookup tables and enumerations for the BM78xBT protocol
+
+# --- Packet framing / layout constants ----------------------------------------
+
+# Fixed packet sizes (bytes)
+INFO_PACKET_LENGTH = 24
+READING_PACKET_LENGTH = 32
+STREAM_FRAME_LENGTH = 152          # 1 info packet + 4 reading packets
+READINGS_PER_FRAME = 4
+
+# Byte [0] / [1]: header (HeadByte0 / HeadByte1)
+HEAD_BYTE0 = 0xFF
+HEAD_BYTE1_INFO = 0x01
+HEAD_BYTE1_READING = 0x02
+
+# Byte [2]: packet length field (always equals INFO/READING_PACKET_LENGTH)
+# Byte [3]: packet type
+INFO_PACKET_TYPE = 0x04            # Device Information
+READING_PACKET_TYPE = 0x05         # Device Reading
+# Byte [4]: protocol version
+PROTOCOL_VERSION = 0x01
+
+# Byte [30] / [31]: trailer (EndByte0 / EndByte1)
+END_BYTE0 = 0xFF
+END_BYTE1 = 0x03
+
+# CRC-16 field: computed over bytes [start:end], stored little-endian at [end:end+2]
+INFO_CRC_START = 2
+INFO_CRC_END = 20
+READING_CRC_START = 2
+READING_CRC_END = 28
+
+# --- Command packet framing (32 bytes) -----------------------------------------
+COMMAND_PACKET_LENGTH = 32
+COMMAND_HEAD_BYTE0 = 0xFF             # Byte [0]
+COMMAND_HEAD_BYTE1 = 0x01             # Byte [1] (SOH)
+COMMAND_PACKET_LEN_BYTE = 0x20        # Byte [2] (32)
+COMMAND_PACKET_TYPE = 0x01            # Byte [3]: Command (0x02 = Response)
+# Byte [4] protocol version: reuses PROTOCOL_VERSION
+PASSWORD_ID = 0x01                    # Byte [13]: password identification
+COMMAND_END_BYTE0 = 0xFF              # Byte [30]
+COMMAND_END_BYTE1 = 0x03              # Byte [31] (ETX)
+COMMAND_CRC_START = 2
+COMMAND_CRC_END = 28
+
+# Command IDs (2 bytes, little-endian on the wire)
+CMD_VERIFY_PASSWORD = bytes([0x51, 0x01])   # 0x0151 (legacy bytes form)
+
+# Full command table (numeric form; send_command / builders accept either)
+CMD_GET_FIRMWARE_VERSION = 0x0004
+CMD_RTC_TIME_CALIBRATION = 0x0010
+CMD_GET_MODEL_SERIES_ID = 0x0116
+CMD_SET_CONNECTION_PASSWORD = 0x0140
+CMD_GET_CONNECTION_PASSWORD = 0x0141
+CMD_SET_DEVICE_NAME = 0x0142
+CMD_GET_DEVICE_NAME = 0x0143
+CMD_VERIFY_CONNECTION_PASSWORD = 0x0151
+
+# Command/response packet framing
+COMMAND_RESPONSE_TYPE = 0x02            # Byte [3]: Response (0x01 = Command)
+CMD_FAILURE = 0x8001                    # response Command ID signalling failure
+
+# Error codes carried in 0x8001 failure responses (Arg[3:2], little-endian)
+ERROR_CODES = {
+    0: "Checksum error",
+    1: "Invalid channel ID",
+    2: "Out of setting range",
+    3: "Invalid password",
+    4: "Invalid password",
+    5: "Invalid arguments",
+    6: "Insufficient permissions",
+}
+
+# Device Category IDs
+CATEGORY_MULTIMETER = 0x02
+CATEGORY_CLAMP_METER = 0x03
+
+# Battery Status
+BATTERY_NORMAL = 0x00
+BATTERY_LOW = 0x02
+
+# Value -> human-readable name lookups
+CATEGORY_NAMES = {
+    CATEGORY_MULTIMETER: "Multimeter",
+    CATEGORY_CLAMP_METER: "Clamp-on",
+}
+
+BATTERY_NAMES = {
+    BATTERY_NORMAL: "Normal",
+    BATTERY_LOW: "Low",
+}
+
+# Function IDs mapping (Main Function ID, Sub-Function ID -> description)
+FUNCTION_NAMES = {
+    (0x02, 0x00): "LoZ-ACV",
+    (0x02, 0x01): "LoZ-DCV",
+    (0x02, 0x03): "AUTO",
+    (0x03, 0x00): "ACV",
+    (0x03, 0x01): "DCV",
+    (0x03, 0x02): "DC+ACV",
+    (0x17, 0x00): "Hz of VFD-ACV",
+    (0x17, 0x01): "VFD-ACV",
+    (0x04, 0x00): "ACmV",
+    (0x04, 0x01): "DCmV",
+    (0x04, 0x02): "DC+ACmV",
+    (0x05, 0x00): "ACµA",
+    (0x05, 0x01): "DCµA",
+    (0x05, 0x02): "DC+ACµA",
+    (0x06, 0x00): "ACmA",
+    (0x06, 0x01): "DCmA",
+    (0x06, 0x02): "DC+ACmA",
+    (0x06, 0x08): "%4~20mA",
+    (0x07, 0x00): "ACA",
+    (0x07, 0x01): "DCA",
+    (0x07, 0x02): "DC+ACA",
+    (0x0C, 0x00): "T1",
+    (0x0C, 0x01): "T2",
+    (0x0C, 0x02): "T1-T2",
+    (0x0D, 0x00): "Resistance",
+    (0x0E, 0x00): "Capacitance",
+    (0x0F, 0x00): "Continuity",
+    (0x10, 0x00): "Diode",
+    (0x11, 0x00): "nS Conductance",
+    (0x12, 0x00): "Duty Cycle (%)",
+    (0x13, 0x00): "Logic-Hz",
+    (0x22, 0x00): "EF-Lo",
+    (0x22, 0x01): "EF-Hi",
+    (0x23, 0x00): "Hz of Line Signal",
+}
+
+# Unit codes (Byte 26) -> SI unit string
+UNIT_CODES = {
+    0x02: "V",
+    0x03: "A",
+    0x04: "Ω",
+    0x05: "S",
+    0x06: "F",
+    0x08: "Hz",
+    0x0A: "%",
+    0x14: "°C",
+    0x15: "°F",
+    0x4F: "%4~20mA",
+}
+
+# Metrics Prefixes (Byte 25) -> symbol
+PREFIX_MAP = {
+    -9: "n",
+    -6: "µ",
+    -3: "m",
+    0: "",
+    3: "k",
+    6: "M",
+    9: "G",
+}
+
+# ASCII reading mappings (when Status Flag 0 Bit 2 = 1)
+ASCII_READING_MAP = {
+    0x000001: "Auto",
+    0x000002: "InEr",
+    0x000003: "-",
+    0x000004: "--",
+    0x000005: "---",
+    0x000006: "----",
+    0x000007: "-----",
+    0x00000A: "EF-H",
+    0x00000B: "EF-L",
+}
+
+# Status Flag 0 bit definitions (Byte 14)
+STATUS0_CREST = 0x80
+STATUS0_REL   = 0x40
+STATUS0_HOLD  = 0x20
+STATUS0_AUTO_RANGE = 0x10
+STATUS0_AUTO_HOLD  = 0x08
+STATUS0_ASCII_READING = 0x04
+
+# Status Flag 1 bit definitions (Byte 15)
+STATUS1_SIGN = 0x40
+STATUS1_OL   = 0x20
+STATUS1_RECORD = 0x10
+STATUS1_MAX  = 0x08
+STATUS1_MIN  = 0x04
+STATUS1_AVG  = 0x02
+
+# Status Flag 2 (Byte 16) is "don't care"

brymenble/crc.py

@@ -0,0 +1,17 @@
+# CRC-16 (Reverse, polynomial 0xA001) calculation and verification
+
+def calculate_crc(data: bytes) -> int:
+    """Return CRC-16 (little-endian) over the given bytes."""
+    reg_crc = 0xFFFF
+    for byte in data:
+        reg_crc ^= byte
+        for _ in range(8):
+            if reg_crc & 0x01:
+                reg_crc = (reg_crc >> 1) ^ 0xA001
+            else:
+                reg_crc >>= 1
+    return reg_crc
+
+def verify_crc(data: bytes, expected_crc: int) -> bool:
+    """Check if the CRC of 'data' matches 'expected_crc'."""
+    return calculate_crc(data) == expected_crc

brymenble/formatter.py

@@ -0,0 +1,31 @@
+# Convert a parsed reading packet into a human-readable string
+
+from .parsers import ReadingPacket
+
+def format_reading(reading: ReadingPacket) -> str:
+    """
+    Given a parsed ReadingPacket, return a string like "123.45 V".
+    Handles overload, ASCII displays, and signs.
+    """
+    if reading is None:
+        return "Invalid packet"
+    if reading.is_overload:
+        return "OL"
+    if reading.is_ascii:
+        return reading.ascii_text or "???"
+
+    # Derived from the packet's canonical value/decimals surface rather than
+    # re-scaling the raw fields here — so this can never drift from other
+    # consumers (overlay, to_dict(), etc.) on edge cases like decimal_pos == 0.
+    value = reading.value
+    if value is None:   # defensive; unreachable after the overload/ASCII checks
+        return "???"
+    number_str = f"{value:.{reading.decimals}f}"
+
+    # Combine with prefix and unit
+    prefix = reading.prefix  # symbol like 'k', 'm', etc.
+    unit = reading.unit
+    if prefix:
+        return f"{number_str} {prefix}{unit}"
+    else:
+        return f"{number_str} {unit}".strip()