miramode 1.0.0__py3-none-any.whl

miramode/__init__.py

@@ -0,0 +1,491 @@
+"""Control Mira Mode digital showers and bath fillers over Bluetooth LE.
+
+Current-generation Mira Mode / Kohler valves expose a GATT service
+(``SERVICE_UUID``) carrying a simple binary protocol. Commands are written
+to one characteristic and responses arrive as notifications on another,
+one response per command.
+
+Every message is a frame::
+
+    aa 55 <channel> <opcode> <length> <payload...> <checksum>
+
+where the checksum is the two's complement of the sum of all preceding
+bytes, so that the bytes of a whole valid frame sum to zero modulo 256.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from enum import IntEnum, IntFlag
+
+from bleak import BleakClient, BleakScanner
+
+__all__ = [
+    "CommandFailed",
+    "DeviceInfo",
+    "DiscoveredDevice",
+    "Frame",
+    "MiraError",
+    "NotConnected",
+    "Opcode",
+    "Outlet",
+    "Preset",
+    "ResponseTimeout",
+    "Shower",
+    "Status",
+    "discover",
+    "encode_frame",
+]
+
+LOG = logging.getLogger(__name__)
+
+SERVICE_UUID = "267f0001-eb15-43f5-94c3-67d2221188f7"
+COMMAND_CHAR_UUID = "267f0002-eb15-43f5-94c3-67d2221188f7"
+EVENT_CHAR_UUID = "267f0003-eb15-43f5-94c3-67d2221188f7"
+
+_DEVICE_NAME_CHAR_UUID = "00002a00-0000-1000-8000-00805f9b34fb"
+_MODEL_CHAR_UUID = "00002a24-0000-1000-8000-00805f9b34fb"
+_MANUFACTURER_CHAR_UUID = "00002a29-0000-1000-8000-00805f9b34fb"
+
+PREAMBLE = b"\xaa\x55"
+
+#: preamble, channel, opcode and payload length.
+_HEADER_SIZE = 5
+#: header plus the trailing checksum byte.
+_ENVELOPE_SIZE = _HEADER_SIZE + 1
+
+#: Presets store their name in a fixed-width, NUL-padded ASCII field.
+_NAME_SIZE = 16
+
+#: Flow is expressed as a percentage of the valve's maximum.
+MAX_FLOW = 100
+
+#: Highest preset slot the valve will answer for.
+MAX_PRESET = 15
+
+DEFAULT_CONNECT_TIMEOUT = 20.0
+DEFAULT_RESPONSE_TIMEOUT = 5.0
+DEFAULT_SCAN_TIMEOUT = 5.0
+
+
+class Opcode(IntEnum):
+    """Message types used by the valve."""
+
+    ACK = 0x01
+    GET_PRESET = 0x5D
+    SET_OUTLETS = 0xAB
+    RUN_PRESET = 0xB1
+
+
+class Status(IntEnum):
+    """Result byte carried by an :attr:`Opcode.ACK` response."""
+
+    OK = 0x01
+    ERROR = 0x80
+
+
+class Outlet(IntFlag):
+    """Which outlets should be running.
+
+    The valve takes the running outlets as a single bitfield rather than
+    one field per outlet, so a command always states the complete desired
+    state: anything not named here is turned off.
+    """
+
+    NONE = 0
+    FIRST = 1
+    SECOND = 2
+    THIRD = 4
+
+
+class MiraError(Exception):
+    """Base class for errors raised by this package."""
+
+
+class NotConnected(MiraError):
+    """Raised when a command needs a connection that isn't established."""
+
+
+class ResponseTimeout(MiraError):
+    """Raised when the valve doesn't answer a command in time."""
+
+
+class CommandFailed(MiraError):
+    """Raised when the valve explicitly rejects a command."""
+
+
+@dataclass(frozen=True)
+class Frame:
+    """A decoded protocol message."""
+
+    channel: int
+    opcode: int
+    payload: bytes
+
+    def __str__(self) -> str:
+        return (
+            f"channel={self.channel} opcode={self.opcode:#04x} "
+            f"payload={self.payload.hex(' ')}"
+        )
+
+
+@dataclass(frozen=True)
+class Preset:
+    """A stored programme, e.g. a bath fill."""
+
+    index: int
+    name: str
+    #: The rest of the slot's contents, which hold the target temperature
+    #: and run time in a layout that isn't fully decoded yet.
+    data: bytes
+
+
+@dataclass(frozen=True)
+class DeviceInfo:
+    """Identifying strings read from the standard GATT characteristics."""
+
+    name: str | None
+    manufacturer: str | None
+    model: str | None
+
+
+@dataclass(frozen=True)
+class DiscoveredDevice:
+    """A valve seen while scanning."""
+
+    address: str
+    name: str | None
+
+
+def _checksum(data: bytes) -> int:
+    """Return the byte that makes ``data`` sum to zero modulo 256."""
+    return -sum(data) & 0xFF
+
+
+def encode_frame(opcode: int, payload: bytes = b"", channel: int = 0) -> bytes:
+    """Build a complete frame, checksum included."""
+    if not 0 <= channel <= 0xFF:
+        raise ValueError(f"channel out of range: {channel}")
+    if len(payload) > 0xFF:
+        raise ValueError(f"payload too long: {len(payload)} bytes")
+    body = PREAMBLE + bytes((channel, int(opcode), len(payload))) + payload
+    return body + bytes((_checksum(body),))
+
+
+def _decode_frame(raw: bytes) -> Frame | None:
+    """Decode one complete frame, or return None if it doesn't check out."""
+    if len(raw) < _ENVELOPE_SIZE or not raw.startswith(PREAMBLE):
+        return None
+    if len(raw) != _ENVELOPE_SIZE + raw[4]:
+        return None
+    if sum(raw) & 0xFF:
+        return None
+    return Frame(channel=raw[2], opcode=raw[3], payload=raw[_HEADER_SIZE:-1])
+
+
+def encode_temperature(celsius: float) -> bytes:
+    """Encode a temperature as tenths of a degree, big endian.
+
+    Zero is meaningful: the valve reads it as "leave the temperature
+    alone", which is what a plain stop command sends.
+    """
+    tenths = round(celsius * 10)
+    if not 0 <= tenths <= 0xFFFF:
+        raise ValueError(f"temperature out of range: {celsius}")
+    return tenths.to_bytes(2, "big")
+
+
+def _decode_preset(payload: bytes) -> Preset | None:
+    """Decode a preset slot, or return None if the slot isn't in use.
+
+    An unconfigured slot answers with a mismatched index and arbitrary
+    bytes where the name belongs, so the name field is required to be
+    printable ASCII with NUL padding.
+    """
+    if len(payload) < 1 + _NAME_SIZE:
+        return None
+    raw_name = payload[1 : 1 + _NAME_SIZE]
+    if any(byte and not 0x20 <= byte < 0x7F for byte in raw_name):
+        return None
+    name = raw_name.split(b"\x00", 1)[0].decode("ascii").strip()
+    if not name:
+        return None
+    return Preset(
+        index=payload[0], name=name, data=bytes(payload[1 + _NAME_SIZE :])
+    )
+
+
+class _FrameReader:
+    """Reassembles frames from notification chunks.
+
+    A response usually arrives in a single notification, but nothing
+    guarantees that, so incoming bytes are buffered and frames are taken
+    out as they complete.
+    """
+
+    def __init__(self) -> None:
+        self._buffer = bytearray()
+
+    def reset(self) -> None:
+        self._buffer.clear()
+
+    def feed(self, chunk: bytes) -> list[Frame]:
+        self._buffer += chunk
+        frames: list[Frame] = []
+        while True:
+            start = self._buffer.find(PREAMBLE)
+            if start < 0:
+                # Keep a trailing byte, which may be a split preamble.
+                del self._buffer[: max(0, len(self._buffer) - 1)]
+                break
+            del self._buffer[:start]
+            if len(self._buffer) < _ENVELOPE_SIZE:
+                break
+            size = _ENVELOPE_SIZE + self._buffer[4]
+            if len(self._buffer) < size:
+                break
+            raw = bytes(self._buffer[:size])
+            del self._buffer[:size]
+            frame = _decode_frame(raw)
+            if frame is None:
+                LOG.debug("Discarding malformed frame: %s", raw.hex(" "))
+            else:
+                frames.append(frame)
+        return frames
+
+
+async def discover(
+    timeout: float = DEFAULT_SCAN_TIMEOUT,
+) -> list[DiscoveredDevice]:
+    """Scan for nearby valves.
+
+    Matches on the advertised service UUID, falling back to the name for
+    valves that advertise without it.
+    """
+    found: dict[str, DiscoveredDevice] = {}
+    for device, advertisement in (
+        await BleakScanner.discover(timeout=timeout, return_adv=True)
+    ).values():
+        name = advertisement.local_name or device.name
+        uuids = {uuid.lower() for uuid in advertisement.service_uuids or ()}
+        if SERVICE_UUID in uuids or (name and "mira" in name.lower()):
+            found[device.address] = DiscoveredDevice(device.address, name)
+    return sorted(found.values(), key=lambda d: (d.name or "", d.address))
+
+
+class Shower:
+    """A connection to one valve.
+
+    Usable as an async context manager::
+
+        async with Shower(address) as shower:
+            await shower.run_preset(2)
+    """
+
+    def __init__(
+        self,
+        address: str,
+        *,
+        channel: int = 0,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        response_timeout: float = DEFAULT_RESPONSE_TIMEOUT,
+    ) -> None:
+        self._address = address
+        self._channel = channel
+        self._connect_timeout = connect_timeout
+        self._response_timeout = response_timeout
+        self._client: BleakClient | None = None
+        self._reader = _FrameReader()
+        self._pending: asyncio.Future | None = None
+
+    @property
+    def address(self) -> str:
+        return self._address
+
+    @property
+    def is_connected(self) -> bool:
+        return self._client is not None and self._client.is_connected
+
+    async def __aenter__(self) -> Shower:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.disconnect()
+
+    async def connect(self) -> None:
+        if self._client is not None:
+            return
+        client = BleakClient(self._address, timeout=self._connect_timeout)
+        await client.connect()
+        try:
+            self._reader.reset()
+            await client.start_notify(EVENT_CHAR_UUID, self._on_notification)
+        except Exception:
+            await client.disconnect()
+            raise
+        self._client = client
+        LOG.debug("Connected to %s", self._address)
+
+    async def disconnect(self) -> None:
+        client, self._client = self._client, None
+        if client is None:
+            return
+        self._fail_pending(NotConnected("Disconnected while awaiting a reply"))
+        try:
+            if client.is_connected:
+                await client.stop_notify(EVENT_CHAR_UUID)
+        except Exception:
+            LOG.debug(
+                "Ignoring error while stopping notifications", exc_info=True
+            )
+        await client.disconnect()
+        LOG.debug("Disconnected from %s", self._address)
+
+    def _require_client(self) -> BleakClient:
+        if self._client is None:
+            raise NotConnected("Not connected; call connect() first")
+        return self._client
+
+    def _fail_pending(self, error: Exception) -> None:
+        pending, self._pending = self._pending, None
+        if pending is not None and not pending.done():
+            pending.set_exception(error)
+
+    def _on_notification(
+        self, _characteristic: object, data: bytearray
+    ) -> None:
+        for frame in self._reader.feed(bytes(data)):
+            LOG.debug("Received %s", frame)
+            pending, self._pending = self._pending, None
+            if pending is not None and not pending.done():
+                pending.set_result(frame)
+            else:
+                LOG.debug("Ignoring unsolicited frame")
+
+    async def _request(self, opcode: int, payload: bytes = b"") -> Frame:
+        """Send a command and wait for the valve's reply."""
+        client = self._require_client()
+        future: asyncio.Future = asyncio.get_running_loop().create_future()
+        self._pending = future
+        frame = encode_frame(opcode, payload, self._channel)
+        LOG.debug("Sending %s", frame.hex(" "))
+        try:
+            await client.write_gatt_char(
+                COMMAND_CHAR_UUID, frame, response=False
+            )
+            return await asyncio.wait_for(future, self._response_timeout)
+        except asyncio.TimeoutError:
+            raise ResponseTimeout(
+                f"No reply to command {opcode:#04x}"
+            ) from None
+        finally:
+            if self._pending is future:
+                self._pending = None
+
+    @staticmethod
+    def _check_ack(frame: Frame) -> None:
+        status = frame.payload[0] if frame.payload else None
+        if status == Status.OK:
+            return
+        if status == Status.ERROR:
+            raise CommandFailed("The valve rejected the command")
+        raise CommandFailed(f"Unexpected reply: {frame}")
+
+    async def set_outlets(
+        self,
+        outlets: Outlet,
+        temperature: float,
+        flow: int = MAX_FLOW,
+    ) -> None:
+        """Set exactly which outlets run, at a given temperature and flow.
+
+        Outlets absent from ``outlets`` are turned off.
+        """
+        if not 0 <= flow <= MAX_FLOW:
+            raise ValueError(f"flow out of range: {flow}")
+        payload = encode_temperature(temperature) + bytes(
+            (flow if outlets else 0, int(outlets))
+        )
+        self._check_ack(await self._request(Opcode.SET_OUTLETS, payload))
+
+    async def stop(self) -> None:
+        """Turn every outlet off, leaving the temperature setting alone."""
+        await self.set_outlets(Outlet.NONE, 0.0, 0)
+
+    async def run_preset(self, index: int) -> None:
+        """Start a stored preset.
+
+        Factory-fitted presets are numbered from 1.
+        """
+        self._check_ack(
+            await self._request(Opcode.RUN_PRESET, bytes((index,)))
+        )
+
+    async def read_preset(self, index: int) -> Preset | None:
+        """Read one preset slot, returning None if it isn't configured."""
+        frame = await self._request(Opcode.GET_PRESET, bytes((index,)))
+        preset = _decode_preset(frame.payload)
+        if preset is None or preset.index != index:
+            return None
+        return preset
+
+    async def presets(
+        self,
+        indexes: Iterable[int] | None = None,
+    ) -> list[Preset]:
+        """Read every configured preset in ``indexes``.
+
+        This only reads from the valve; it doesn't run any water.
+        """
+        if indexes is None:
+            indexes = range(MAX_PRESET + 1)
+        found = []
+        for index in indexes:
+            preset = await self.read_preset(index)
+            if preset is not None:
+                found.append(preset)
+        return found
+
+    def services(self) -> dict[str, list[str]]:
+        """Map each GATT service the valve offers to its characteristics."""
+        client = self._require_client()
+        return {
+            service.uuid.lower(): sorted(
+                char.uuid.lower() for char in service.characteristics
+            )
+            for service in client.services
+        }
+
+    async def device_info(self) -> DeviceInfo:
+        """Read whatever identification the valve exposes.
+
+        Not every valve implements the standard device-information
+        characteristics, so any of these fields may be None.
+        """
+        client = self._require_client()
+        available = {
+            uuid for uuids in self.services().values() for uuid in uuids
+        }
+
+        async def read(uuid: str) -> str | None:
+            if uuid not in available:
+                return None
+            try:
+                value = await client.read_gatt_char(uuid)
+            except Exception:
+                LOG.debug("Could not read %s", uuid, exc_info=True)
+                return None
+            return value.decode("utf-8", "replace").strip() or None
+
+        values: Sequence[str | None] = await asyncio.gather(
+            read(_DEVICE_NAME_CHAR_UUID),
+            read(_MANUFACTURER_CHAR_UUID),
+            read(_MODEL_CHAR_UUID),
+        )
+        return DeviceInfo(
+            name=values[0], manufacturer=values[1], model=values[2]
+        )

miramode/cli.py

@@ -0,0 +1,252 @@
+"""Command line interface for controlling Mira Mode valves."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from collections.abc import Sequence
+
+from . import (
+    DEFAULT_SCAN_TIMEOUT,
+    MAX_FLOW,
+    MAX_PRESET,
+    SERVICE_UUID,
+    MiraError,
+    Outlet,
+    Shower,
+    discover,
+)
+
+LOG = logging.getLogger(__name__)
+
+
+def _temperature(text: str) -> float:
+    try:
+        value = float(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{text!r} is not a number") from None
+    if not 0 < value < 100:
+        raise argparse.ArgumentTypeError(
+            f"{text} is not a plausible temperature in Celsius"
+        )
+    return value
+
+
+def _percentage(text: str) -> int:
+    try:
+        value = int(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{text!r} is not a number") from None
+    if not 0 <= value <= MAX_FLOW:
+        raise argparse.ArgumentTypeError(f"{text} is not between 0 and 100")
+    return value
+
+
+def _preset_index(text: str) -> int:
+    try:
+        value = int(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{text!r} is not a number") from None
+    if not 0 <= value <= MAX_PRESET:
+        raise argparse.ArgumentTypeError(
+            f"{text} is not between 0 and {MAX_PRESET}"
+        )
+    return value
+
+
+async def _scan(args: argparse.Namespace) -> int:
+    devices = await discover(timeout=args.timeout)
+    if not devices:
+        print("No valves found.")
+        return 1
+    for device in devices:
+        print(f"{device.address}  {device.name or '(unnamed)'}")
+    return 0
+
+
+async def _info(args: argparse.Namespace) -> int:
+    async with Shower(args.address) as shower:
+        info = await shower.device_info()
+        services = shower.services()
+    for label, value in (
+        ("Name", info.name),
+        ("Manufacturer", info.manufacturer),
+        ("Model", info.model),
+    ):
+        if value:
+            print(f"{label + ':':14}{value}")
+    supported = SERVICE_UUID in services
+    print(
+        f"{'Protocol:':14}"
+        f"{'GCS (supported)' if supported else 'not GCS (unsupported)'}"
+    )
+    print("Services:")
+    for service, characteristics in sorted(services.items()):
+        print(f"  {service}")
+        for characteristic in characteristics:
+            print(f"    {characteristic}")
+    return 0 if supported else 1
+
+
+async def _presets(args: argparse.Namespace) -> int:
+    async with Shower(args.address) as shower:
+        presets = await shower.presets(range(args.first, args.last + 1))
+    if not presets:
+        print("No presets configured.")
+        return 1
+    for preset in presets:
+        print(f"{preset.index:>3}  {preset.name}")
+    return 0
+
+
+async def _start(args: argparse.Namespace) -> int:
+    async with Shower(args.address) as shower:
+        await shower.run_preset(args.preset)
+    print(f"Started preset {args.preset}.")
+    return 0
+
+
+async def _outlets(args: argparse.Namespace) -> int:
+    outlets = Outlet.NONE
+    if args.first:
+        outlets |= Outlet.FIRST
+    if args.second:
+        outlets |= Outlet.SECOND
+    async with Shower(args.address) as shower:
+        await shower.set_outlets(outlets, args.temperature, args.flow)
+    running = ", ".join(
+        name for name, on in (("1", args.first), ("2", args.second)) if on
+    )
+    print(
+        f"Running outlet(s) {running} at {args.temperature}C."
+        if running
+        else "All outlets off."
+    )
+    return 0
+
+
+async def _stop(args: argparse.Namespace) -> int:
+    async with Shower(args.address) as shower:
+        await shower.stop()
+    print("All outlets off.")
+    return 0
+
+
+def _add_address(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "-a",
+        "--address",
+        required=True,
+        help="valve address (a MAC address, or a UUID on macOS)",
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="miramode",
+        description="Control Mira Mode digital showers and bath fillers.",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="log the frames exchanged with the valve",
+    )
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    scan = subcommands.add_parser("scan", help="find nearby valves")
+    scan.add_argument(
+        "-t",
+        "--timeout",
+        type=float,
+        default=DEFAULT_SCAN_TIMEOUT,
+        help=f"seconds to scan for (default: {DEFAULT_SCAN_TIMEOUT:g})",
+    )
+    scan.set_defaults(handler=_scan)
+
+    info = subcommands.add_parser("info", help="show valve identification")
+    _add_address(info)
+    info.set_defaults(handler=_info)
+
+    presets = subcommands.add_parser(
+        "presets", help="list stored presets (reads only, runs no water)"
+    )
+    _add_address(presets)
+    presets.add_argument(
+        "--first",
+        type=_preset_index,
+        default=0,
+        help="lowest slot to read (default: 0)",
+    )
+    presets.add_argument(
+        "--last",
+        type=_preset_index,
+        default=MAX_PRESET,
+        help=f"highest slot to read (default: {MAX_PRESET})",
+    )
+    presets.set_defaults(handler=_presets)
+
+    start = subcommands.add_parser("start", help="run a stored preset")
+    _add_address(start)
+    start.add_argument(
+        "preset",
+        type=_preset_index,
+        help="preset slot; factory-fitted presets start at 1",
+    )
+    start.set_defaults(handler=_start)
+
+    outlets = subcommands.add_parser(
+        "outlets", help="run specific outlets at a chosen temperature"
+    )
+    _add_address(outlets)
+    outlets.add_argument(
+        "-1", "--first", action="store_true", help="run the first outlet"
+    )
+    outlets.add_argument(
+        "-2", "--second", action="store_true", help="run the second outlet"
+    )
+    outlets.add_argument(
+        "-t",
+        "--temperature",
+        type=_temperature,
+        required=True,
+        help="target temperature in Celsius",
+    )
+    outlets.add_argument(
+        "-f",
+        "--flow",
+        type=_percentage,
+        default=MAX_FLOW,
+        help=f"flow as a percentage (default: {MAX_FLOW})",
+    )
+    outlets.set_defaults(handler=_outlets)
+
+    stop = subcommands.add_parser("stop", help="turn every outlet off")
+    _add_address(stop)
+    stop.set_defaults(handler=_stop)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    # Only turn up our own logging: bleak's debug output is a firehose of
+    # per-platform GATT callbacks that buries the frames being exchanged.
+    logging.basicConfig(
+        format="%(message)s", level=logging.WARNING, stream=sys.stderr
+    )
+    if args.verbose:
+        logging.getLogger(__package__).setLevel(logging.DEBUG)
+    try:
+        return asyncio.run(args.handler(args))
+    except MiraError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

miramode-1.0.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: miramode
+Version: 1.0.0
+Summary: Control Mira Mode digital showers and bath fillers over Bluetooth LE
+Project-URL: Homepage, https://github.com/ryan-shaw/mira-mode-control
+Project-URL: Repository, https://github.com/ryan-shaw/mira-mode-control
+Project-URL: Issues, https://github.com/ryan-shaw/mira-mode-control/issues
+Author: Ryan Shaw
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,home-automation,kohler,mira,mira-mode,shower,smart-home
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Hardware
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: bleak>=0.22
+Description-Content-Type: text/markdown
+
+# mira-mode-control
+
+[![Lint](https://github.com/ryan-shaw/mira-mode-control/actions/workflows/lint.yml/badge.svg)](https://github.com/ryan-shaw/mira-mode-control/actions/workflows/lint.yml)
+
+Control Mira Mode digital showers and bath fillers from Python, over
+Bluetooth Low Energy.
+
+Mira Mode valves (now sold under Kohler) ship with no interface other than
+BLE and the vendor's phone app, which means no Home Assistant, no
+automation, and no way to start filling the bath from anywhere but the
+bathroom. This package implements the valve's BLE protocol directly, so
+you can drive it from a Raspberry Pi, a laptop, or anything else with a
+Bluetooth radio.
+
+> **Use at your own risk.** This drives real plumbing that produces real
+> hot water. The protocol was reverse engineered, not documented by the
+> vendor. Don't run it unattended until you've watched it behave.
+
+## Supported hardware
+
+This implements the protocol used by current-generation valves, which
+advertise the GATT service `267f0001-eb15-43f5-94c3-67d2221188f7`. Check
+yours with `miramode info` — it reports whether the valve speaks a
+protocol this package understands.
+
+Earlier Mira Mode valves advertise `bccb0001-ca66-11e5-88a4-0002a5d5c51b`
+and use an unrelated, CRC-16 based protocol that this package does not
+support.
+
+Developed against a dual outlet shower and bath filler unit. Other valves
+in the range should work, but only the outlets and presets your unit
+actually has will do anything.
+
+## Requirements
+
+- Python 3.10 or newer
+- A Bluetooth Low Energy adapter
+- On Linux, BlueZ
+- The valve must be paired with the host first, through your operating
+  system's Bluetooth settings. The valve refuses to accept commands over
+  an unbonded connection.
+
+## Installation
+
+```console
+pip install miramode
+```
+
+Or, with [uv](https://docs.astral.sh/uv/) — `uv tool install miramode`
+to get just the `miramode` command, or `uv add miramode` to use it as a
+library in a project.
+
+### From source
+
+```console
+git clone git@github.com:ryan-shaw/mira-mode-control.git
+cd mira-mode-control
+uv sync
+```
+
+That installs the versions pinned in `uv.lock` into `.venv`. Prefix the
+commands below with `uv run` to use it.
+
+### Development
+
+The same checks CI runs:
+
+```console
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+```
+
+Use `uv run ruff format .` to apply formatting.
+
+## Command line usage
+
+Find your valve:
+
+```console
+$ miramode scan
+1FE6A4BD-73A5-055E-6463-F4785E21D49D  Mira 004C Bathroom
+```
+
+Addresses are MAC addresses on Linux and Windows, and opaque UUIDs on
+macOS. Every command below takes one with `-a`.
+
+### Presets
+
+Presets are the programmes stored in the valve — each carries its own
+target temperature and run time, and they're how the vendor app starts
+the shower or fills the bath. Listing them only reads from the valve and
+runs no water:
+
+```console
+$ miramode presets -a <address>
+  1  Default
+  2  Default Bathfill
+```
+
+Factory-fitted presets are numbered from 1; slot 0 is not used. Start one
+by number:
+
+```console
+miramode start -a <address> 2
+```
+
+### Outlets
+
+To run an outlet directly, at a temperature you choose:
+
+```console
+miramode outlets -a <address> --first --temperature 39
+```
+
+Use `--second` for the second outlet, and both flags together to run both
+at once. A command states the complete desired state, so any outlet you
+don't name is switched off. `--flow` sets the flow rate as a percentage,
+defaulting to 100.
+
+Which physical fixture is "first" depends on how your unit is plumbed.
+
+To shut everything off, including a running preset:
+
+```console
+miramode stop -a <address>
+```
+
+### Troubleshooting
+
+`-v` logs every frame exchanged with the valve:
+
+```console
+$ miramode -v stop -a <address>
+Connected to 1FE6A4BD-73A5-055E-6463-F4785E21D49D
+Sending aa 55 00 ab 04 00 00 00 00 52
+Received channel=1 opcode=0x01 payload=01
+```
+
+## Library usage
+
+The API is async, built on [bleak](https://github.com/hbldh/bleak):
+
+```python
+import asyncio
+from miramode import Outlet, Shower
+
+
+async def run_a_bath():
+    async with Shower("1FE6A4BD-73A5-055E-6463-F4785E21D49D") as shower:
+        for preset in await shower.presets():
+            print(preset.index, preset.name)
+
+        await shower.run_preset(2)  # start the bath filling
+        await asyncio.sleep(300)
+        await shower.stop()
+
+        # or drive an outlet directly
+        await shower.set_outlets(Outlet.FIRST, temperature=39.0)
+
+
+asyncio.run(run_a_bath())
+```
+
+Failures raise subclasses of `MiraError`: `NotConnected`,
+`ResponseTimeout`, and `CommandFailed` when the valve rejects a command.
+
+## Protocol notes
+
+Messages in both directions share one frame layout:
+
+```
+aa 55 <channel> <opcode> <length> <payload...> <checksum>
+```
+
+The checksum is the two's complement of the sum of the preceding bytes,
+so a whole valid frame sums to zero modulo 256. Commands are written to
+characteristic `267f0002-…` and replies arrive as notifications on
+`267f0003-…`, one reply per command.
+
+Three opcodes are implemented:
+
+| Opcode | Meaning | Payload |
+| --- | --- | --- |
+| `0xab` | Set outlets | temperature (2 bytes, tenths of a degree, big endian), flow percentage, outlet bitfield |
+| `0xb1` | Run preset | preset slot |
+| `0x5d` | Read preset | preset slot; the reply echoes the slot then a 16 byte NUL-padded name |
+
+The outlet field is a bitfield in a single byte — bit 0 is the first
+outlet, bit 1 the second, bit 2 a third — rather than one byte per
+outlet. A temperature of zero means "leave the setting alone", which is
+what `stop` sends.
+
+## Acknowledgements
+
+Nigel Hannam's [protocol
+documentation](https://github.com/nhannam/shower-controller-documentation)
+was a useful reference for the older generation of these valves.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

miramode-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+miramode/__init__.py,sha256=2Ve4LMMHkO6PsvaiN8Q0l-MX8wFLsIm4z2LkEv-2Vtk,15334
+miramode/cli.py,sha256=k8kfqZYVbQJ76486aiXTSiGMzohFJNfZ_dvdKjHjwSo,7111
+miramode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+miramode-1.0.0.dist-info/METADATA,sha256=vmUVPJMbmMBvVPRSx9_4TqveK1NJiPip__YF7cD34mQ,7000
+miramode-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+miramode-1.0.0.dist-info/entry_points.txt,sha256=Ck9LyIcR5Ehl4GeHYxGMTtOgATiFTyAOs--71CHjRL8,47
+miramode-1.0.0.dist-info/licenses/LICENSE,sha256=Y7yhFwGNqYRSMvFk9cxc_mxUD5oAbq-c6VeeTJTNoco,1066
+miramode-1.0.0.dist-info/RECORD,,

miramode-1.0.0.dist-info/WHEEL

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

miramode-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+miramode = miramode.cli:main

miramode-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Shaw
+
+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.