brymenble 0.5.2__tar.gz

brymenble-0.5.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brymenble-0.5.2/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: brymenble
+Version: 0.5.2
+Summary: Unofficial Python SDK for the Brymen BM78xBT Bluetooth Low Energy multimeter
+Author: Martin Chan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/milksplash/brymenble
+Project-URL: Repository, https://github.com/milksplash/brymenble
+Project-URL: Issues, https://github.com/milksplash/brymenble/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.21
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# brymenble SDK
+
+> **⚠️ Unofficial.** This is an independent, community-developed project. It is
+> **not affiliated with, endorsed by, or sponsored by** Brymen Technology Corporation. "Brymen" and the device model names are trademarks of their
+> respective owners.
+
+![Please note this picture is for showcase only. It is currently not possible to connect two instances to one meter.](img/showcase.png)
+
+Open-source Python SDK for **Brymen BM78xBT** Bluetooth Low Energy wireless multimeters. This is the monorepo for both the SDK itself (`src/brymenble/`) and
+its example apps (`examples/`): a live-readings console and a raw-protocol
+debug tool.
+
+## Related projects
+
+The SDK is used by two companion projects in the same family:
+
+- [**brymenble-overlay**](https://github.com/milksplash/brymenble-overlay) — emulates readings from the multimeter as an overlay
+  for OBS (or any browser), driven live by this SDK over BLE.
+- [**brymenble-tc-bridge**](https://github.com/milksplash/brymenble-tc-bridge) — re-emits the SDK's parsed readings over a TCP
+  socket so [**TestController**](https://lygte-info.dk/project/TestControllerIntro%20UK.html)
+(lygte-info.dk's freeware multi-device test & logging tool). can be used to log the meter.
+
+
+## SDK
+
+The SDK is a pip-installable package that handles the whole protocol:
+
+- `brymenble.constants` — protocol constants and lookup tables
+- `brymenble.crc` — CRC-16 (poly 0xA001) used by the protocol
+- `brymenble.commands` — building command packets (auth, etc.)
+- `brymenble.parsers` — turning raw packets/frames into `InfoPacket`, `ReadingPacket`, `RtcTime`
+- `brymenble.formatter` — converting a parsed reading into a display string (`"123.45 V"`)
+- `brymenble.console` — shared console output helpers (`ts()`, `status()`, `reading_line()`, `state()`, and lifecycle/status callbacks `retry` / `paused` / `lost` / `reconnected` / `scanning` / `using` / `found` / `connecting` / `connected` / `disconnected`) so every consumer prints identically
+- `brymenble.transport` — `BrymenbleClient`: connect, authenticate, subscribe, stream parsed frames, plus a retry/reconnect policy (`ensure_connected`), a high-level streaming loop (`read_stream`) that waits out function-switch pauses and reconnects on a real link drop, and idempotent `close()`
+
+### Documentation
+
+- `docs/SDK_DATA_REFERENCE.md` — reference of every parsed field the SDK exposes (`ReadingPacket`, `InfoPacket`, `RtcTime`, `CommandResponse`)
+
+### Install
+
+From PyPI (recommended):
+
+```bash
+pip install brymenble
+```
+
+From a source checkout (for development or unreleased changes):
+
+```bash
+pip install -e .          # from the repo root (installs `brymenble` + `bleak`)
+```
+
+Directly from GitHub (no PyPI needed):
+
+```bash
+pip install git+https://github.com/milksplash/brymenble.git
+```
+
+### Minimal use
+
+```python
+import asyncio
+from brymenble import BrymenbleClient, DEFAULT_PASSWORD, find_meters, format_reading
+
+async def main():
+    meters = await find_meters()
+    if not meters:
+        print("No BM78xBT meters found.")
+        return
+    mac = meters[0].address
+
+    async with BrymenbleClient(mac, DEFAULT_PASSWORD, sync_rtc_on_connect=True) as client:
+        async for frame in client:
+            print(frame.info.mac_str, format_reading(frame.readings[0]))
+
+asyncio.run(main())
+```
+
+`find_first_meter()` is the same discovery wrapped in a retry loop for
+long-running apps — it scans until a meter is found (retrying every
+`retry_interval` seconds, calling `on_retry(attempt)` before each re-scan).
+Pass `retry_interval=0` for a single-shot scan that returns `None` when
+nothing is found.
+
+### Long-running consumers
+
+For apps that must survive the meter powering off (overlays, loggers),
+`BrymenbleClient.read_stream()` is a self-healing loop: a data gap while the
+BLE link is up is treated as a function-switch pause and waited out, while a
+real link drop is confirmed and transparently reconnected. Optional
+`on_pause` / `on_lost` / `on_reconnected` callbacks report lifecycle
+changes; `retries=None` reconnects forever.
+
+```python
+async for frame in client.read_stream(retries=None):
+    print(frame.info.mac_str, format_reading(frame.readings[0]))
+```
+
+> **One connection per meter.** BLE is point-to-point — a BM78xBT accepts a
+> single connection, so a second instance (or any other app) cannot connect
+> while another holds it; it just looks like "out of range". If a connect
+> fails/times out, the error and a one-time warning include a hint to check
+> the meter isn't connected elsewhere. Stop the other app before retrying.
+
+## Example apps
+
+- **`examples/live.py`** — a thin program built on the SDK: it connects to a
+  meter and prints its readings as they arrive, using the shared
+  `brymenble.console` helpers so the output matches the overlay and the TC
+  bridge. With no MAC given it scans for the first BM78xBT meter it finds.
+
+  ```bash
+  python examples/live.py [MAC] [PASSWORD]
+  ```
+
+- **`examples/debug_stream.py`** — a debug/test script that dumps the raw
+  protocol stream via `examples/display.py`: the full raw frame hex, the
+  device-info packet, each reading packet, and packet-timing statistics. Use
+  it to inspect exactly what the meter sends (the clean console view above is
+  `examples/live.py`).
+
+  ```bash
+  python examples/debug_stream.py [MAC] [PASSWORD]
+  ```
+
+For on-demand reads and hardware probing, see `tools/probe.py` (exercises the
+command/response layer against a real meter) and `tools/capture.py` (records
+real frames for the test fixtures).
+
+## Platform support
+
+Linux and Windows are supported. macOS randomizes BLE device MAC addresses and behavior is not tested.
+
+## Tests
+
+Offline tests:
+
+```bash
+.venv\Scripts\python.exe -m pytest
+```
+
+`tools/capture.py` captures real frames from a meter into
+`tests/fixtures/captures.json`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+"Brymen" and the device model names are trademarks of their respective owners;
+this project is not affiliated with or endorsed by Brymen Technology Corporation.

brymenble-0.5.2/README.md

@@ -0,0 +1,151 @@
+# brymenble SDK
+
+> **⚠️ Unofficial.** This is an independent, community-developed project. It is
+> **not affiliated with, endorsed by, or sponsored by** Brymen Technology Corporation. "Brymen" and the device model names are trademarks of their
+> respective owners.
+
+![Please note this picture is for showcase only. It is currently not possible to connect two instances to one meter.](img/showcase.png)
+
+Open-source Python SDK for **Brymen BM78xBT** Bluetooth Low Energy wireless multimeters. This is the monorepo for both the SDK itself (`src/brymenble/`) and
+its example apps (`examples/`): a live-readings console and a raw-protocol
+debug tool.
+
+## Related projects
+
+The SDK is used by two companion projects in the same family:
+
+- [**brymenble-overlay**](https://github.com/milksplash/brymenble-overlay) — emulates readings from the multimeter as an overlay
+  for OBS (or any browser), driven live by this SDK over BLE.
+- [**brymenble-tc-bridge**](https://github.com/milksplash/brymenble-tc-bridge) — re-emits the SDK's parsed readings over a TCP
+  socket so [**TestController**](https://lygte-info.dk/project/TestControllerIntro%20UK.html)
+(lygte-info.dk's freeware multi-device test & logging tool). can be used to log the meter.
+
+
+## SDK
+
+The SDK is a pip-installable package that handles the whole protocol:
+
+- `brymenble.constants` — protocol constants and lookup tables
+- `brymenble.crc` — CRC-16 (poly 0xA001) used by the protocol
+- `brymenble.commands` — building command packets (auth, etc.)
+- `brymenble.parsers` — turning raw packets/frames into `InfoPacket`, `ReadingPacket`, `RtcTime`
+- `brymenble.formatter` — converting a parsed reading into a display string (`"123.45 V"`)
+- `brymenble.console` — shared console output helpers (`ts()`, `status()`, `reading_line()`, `state()`, and lifecycle/status callbacks `retry` / `paused` / `lost` / `reconnected` / `scanning` / `using` / `found` / `connecting` / `connected` / `disconnected`) so every consumer prints identically
+- `brymenble.transport` — `BrymenbleClient`: connect, authenticate, subscribe, stream parsed frames, plus a retry/reconnect policy (`ensure_connected`), a high-level streaming loop (`read_stream`) that waits out function-switch pauses and reconnects on a real link drop, and idempotent `close()`
+
+### Documentation
+
+- `docs/SDK_DATA_REFERENCE.md` — reference of every parsed field the SDK exposes (`ReadingPacket`, `InfoPacket`, `RtcTime`, `CommandResponse`)
+
+### Install
+
+From PyPI (recommended):
+
+```bash
+pip install brymenble
+```
+
+From a source checkout (for development or unreleased changes):
+
+```bash
+pip install -e .          # from the repo root (installs `brymenble` + `bleak`)
+```
+
+Directly from GitHub (no PyPI needed):
+
+```bash
+pip install git+https://github.com/milksplash/brymenble.git
+```
+
+### Minimal use
+
+```python
+import asyncio
+from brymenble import BrymenbleClient, DEFAULT_PASSWORD, find_meters, format_reading
+
+async def main():
+    meters = await find_meters()
+    if not meters:
+        print("No BM78xBT meters found.")
+        return
+    mac = meters[0].address
+
+    async with BrymenbleClient(mac, DEFAULT_PASSWORD, sync_rtc_on_connect=True) as client:
+        async for frame in client:
+            print(frame.info.mac_str, format_reading(frame.readings[0]))
+
+asyncio.run(main())
+```
+
+`find_first_meter()` is the same discovery wrapped in a retry loop for
+long-running apps — it scans until a meter is found (retrying every
+`retry_interval` seconds, calling `on_retry(attempt)` before each re-scan).
+Pass `retry_interval=0` for a single-shot scan that returns `None` when
+nothing is found.
+
+### Long-running consumers
+
+For apps that must survive the meter powering off (overlays, loggers),
+`BrymenbleClient.read_stream()` is a self-healing loop: a data gap while the
+BLE link is up is treated as a function-switch pause and waited out, while a
+real link drop is confirmed and transparently reconnected. Optional
+`on_pause` / `on_lost` / `on_reconnected` callbacks report lifecycle
+changes; `retries=None` reconnects forever.
+
+```python
+async for frame in client.read_stream(retries=None):
+    print(frame.info.mac_str, format_reading(frame.readings[0]))
+```
+
+> **One connection per meter.** BLE is point-to-point — a BM78xBT accepts a
+> single connection, so a second instance (or any other app) cannot connect
+> while another holds it; it just looks like "out of range". If a connect
+> fails/times out, the error and a one-time warning include a hint to check
+> the meter isn't connected elsewhere. Stop the other app before retrying.
+
+## Example apps
+
+- **`examples/live.py`** — a thin program built on the SDK: it connects to a
+  meter and prints its readings as they arrive, using the shared
+  `brymenble.console` helpers so the output matches the overlay and the TC
+  bridge. With no MAC given it scans for the first BM78xBT meter it finds.
+
+  ```bash
+  python examples/live.py [MAC] [PASSWORD]
+  ```
+
+- **`examples/debug_stream.py`** — a debug/test script that dumps the raw
+  protocol stream via `examples/display.py`: the full raw frame hex, the
+  device-info packet, each reading packet, and packet-timing statistics. Use
+  it to inspect exactly what the meter sends (the clean console view above is
+  `examples/live.py`).
+
+  ```bash
+  python examples/debug_stream.py [MAC] [PASSWORD]
+  ```
+
+For on-demand reads and hardware probing, see `tools/probe.py` (exercises the
+command/response layer against a real meter) and `tools/capture.py` (records
+real frames for the test fixtures).
+
+## Platform support
+
+Linux and Windows are supported. macOS randomizes BLE device MAC addresses and behavior is not tested.
+
+## Tests
+
+Offline tests:
+
+```bash
+.venv\Scripts\python.exe -m pytest
+```
+
+`tools/capture.py` captures real frames from a meter into
+`tests/fixtures/captures.json`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+"Brymen" and the device model names are trademarks of their respective owners;
+this project is not affiliated with or endorsed by Brymen Technology Corporation.

brymenble-0.5.2/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brymenble"
+version = "0.5.2"
+description = "Unofficial Python SDK for the Brymen BM78xBT Bluetooth Low Energy multimeter"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Martin Chan" },
+]
+dependencies = [
+    "bleak>=0.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/milksplash/brymenble"
+Repository = "https://github.com/milksplash/brymenble"
+Issues = "https://github.com/milksplash/brymenble/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+]
+dev = [
+    "pytest",
+    "build",
+    "twine",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+brymenble = ["py.typed"]

brymenble-0.5.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brymenble-0.5.2/src/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-0.5.2/src/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-0.5.2/src/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)