kettle-x2p-cli 1.0.0__py3-none-any.whl

kettle/__init__.py

@@ -0,0 +1,3 @@
+"""Local control of the Xiaomi Smart Kettle 2 Pro over the LAN."""
+
+version = "1.0.0"

kettle/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

kettle/aes.py

@@ -0,0 +1,151 @@
+"""AES-128 in CBC mode with PKCS7 padding, pure Python (standard library only).
+
+The miio protocol encrypts a few hundred bytes per request with AES-128-CBC, so speed is
+irrelevant and a tiny implementation keeps the package free of compiled dependencies
+(which makes it trivial to package for Homebrew). Verified against the FIPS-197 and
+NIST SP 800-38A test vectors in tests/test_aes.py.
+"""
+from __future__ import annotations
+
+
+def _build_sbox() -> list:
+    sbox = [0] * 256
+    p = q = 1
+    while True:
+        p = p ^ ((p << 1) & 0xFF) ^ (0x1B if p & 0x80 else 0)  # p *= 3 in GF(2^8)
+        q ^= q << 1
+        q ^= q << 2
+        q ^= q << 4
+        q &= 0xFF
+        if q & 0x80:
+            q ^= 0x09  # q /= 3
+        x = q
+        for shift in (1, 2, 3, 4):
+            x ^= ((q << shift) | (q >> (8 - shift))) & 0xFF
+        sbox[p] = (x ^ 0x63) & 0xFF
+        if p == 1:
+            break
+    sbox[0] = 0x63
+    return sbox
+
+
+_SBOX = _build_sbox()
+_INV_SBOX = [0] * 256
+for _i, _v in enumerate(_SBOX):
+    _INV_SBOX[_v] = _i
+
+
+def _xtime(a: int) -> int:
+    a <<= 1
+    return (a ^ 0x11B) & 0xFF if a & 0x100 else a
+
+
+def _mul(a: int, b: int) -> int:
+    r = 0
+    while b:
+        if b & 1:
+            r ^= a
+        a = _xtime(a)
+        b >>= 1
+    return r
+
+
+_MUL = {n: [_mul(i, n) for i in range(256)] for n in (2, 3, 9, 11, 13, 14)}
+
+
+def _expand_key(key: bytes) -> list:
+    if len(key) != 16:
+        raise ValueError("AES-128 needs a 16-byte key")
+    w = [list(key[i:i + 4]) for i in range(0, 16, 4)]
+    rcon = 1
+    for i in range(4, 44):
+        t = list(w[i - 1])
+        if i % 4 == 0:
+            t = t[1:] + t[:1]
+            t = [_SBOX[b] for b in t]
+            t[0] ^= rcon
+            rcon = _xtime(rcon)
+        w.append([w[i - 4][j] ^ t[j] for j in range(4)])
+    return [sum(w[4 * r:4 * r + 4], []) for r in range(11)]
+
+
+def _add_key(state: list, rk: list) -> list:
+    return [s ^ k for s, k in zip(state, rk)]
+
+
+def _shift_rows(s: list) -> list:
+    return [s[r + 4 * ((c + r) % 4)] for c in range(4) for r in range(4)]
+
+
+def _inv_shift_rows(s: list) -> list:
+    out = [0] * 16
+    for c in range(4):
+        for r in range(4):
+            out[r + 4 * ((c + r) % 4)] = s[r + 4 * c]
+    return out
+
+
+def _mix_columns(s: list) -> list:
+    m2, m3 = _MUL[2], _MUL[3]
+    out = []
+    for c in range(0, 16, 4):
+        a0, a1, a2, a3 = s[c:c + 4]
+        out += [m2[a0] ^ m3[a1] ^ a2 ^ a3,
+                a0 ^ m2[a1] ^ m3[a2] ^ a3,
+                a0 ^ a1 ^ m2[a2] ^ m3[a3],
+                m3[a0] ^ a1 ^ a2 ^ m2[a3]]
+    return out
+
+
+def _inv_mix_columns(s: list) -> list:
+    m9, m11, m13, m14 = _MUL[9], _MUL[11], _MUL[13], _MUL[14]
+    out = []
+    for c in range(0, 16, 4):
+        a0, a1, a2, a3 = s[c:c + 4]
+        out += [m14[a0] ^ m11[a1] ^ m13[a2] ^ m9[a3],
+                m9[a0] ^ m14[a1] ^ m11[a2] ^ m13[a3],
+                m13[a0] ^ m9[a1] ^ m14[a2] ^ m11[a3],
+                m11[a0] ^ m13[a1] ^ m9[a2] ^ m14[a3]]
+    return out
+
+
+def encrypt_block(round_keys: list, block: bytes) -> bytes:
+    s = _add_key(list(block), round_keys[0])
+    for r in range(1, 10):
+        s = _add_key(_mix_columns(_shift_rows([_SBOX[b] for b in s])), round_keys[r])
+    return bytes(_add_key(_shift_rows([_SBOX[b] for b in s]), round_keys[10]))
+
+
+def decrypt_block(round_keys: list, block: bytes) -> bytes:
+    s = _add_key(list(block), round_keys[10])
+    for r in range(9, 0, -1):
+        s = _inv_mix_columns(_add_key([_INV_SBOX[b] for b in _inv_shift_rows(s)], round_keys[r]))
+    return bytes(_add_key([_INV_SBOX[b] for b in _inv_shift_rows(s)], round_keys[0]))
+
+
+def cbc_encrypt(key: bytes, iv: bytes, data: bytes) -> bytes:
+    """AES-128-CBC with PKCS7 padding."""
+    rk = _expand_key(key)
+    pad = 16 - len(data) % 16
+    data += bytes([pad]) * pad
+    out, prev = bytearray(), iv
+    for i in range(0, len(data), 16):
+        prev = encrypt_block(rk, bytes(a ^ b for a, b in zip(data[i:i + 16], prev)))
+        out += prev
+    return bytes(out)
+
+
+def cbc_decrypt(key: bytes, iv: bytes, data: bytes) -> bytes:
+    """Inverse of cbc_encrypt; raises ValueError on bad length or padding."""
+    if not data or len(data) % 16:
+        raise ValueError("ciphertext is not a multiple of 16 bytes")
+    rk = _expand_key(key)
+    out, prev = bytearray(), iv
+    for i in range(0, len(data), 16):
+        block = data[i:i + 16]
+        out += bytes(a ^ b for a, b in zip(decrypt_block(rk, block), prev))
+        prev = block
+    pad = out[-1]
+    if not 1 <= pad <= 16 or out[-pad:] != bytes([pad]) * pad:
+        raise ValueError("bad PKCS7 padding")
+    return bytes(out[:-pad])

kettle/cli.py

@@ -0,0 +1,437 @@
+"""Command line interface: argument parsing, the commands and the interactive shell."""
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import os
+import sys
+import time
+
+from . import config, version
+from .miio import MiioClient, MiioError, MiioRpcError, discover, local_subnet
+
+EXPECTED_MODEL = "xiaomi.kettle.v20"
+
+# (siid, piid) from SPEC.md
+STATUS, FAULT, TEMP, TARGET, AUTO_KEEP, KEEP_TEMP, ON = (2, 1), (2, 2), (2, 3), (2, 4), (2, 5), (2, 6), (2, 7)
+KEEP_MIN, LIFTED, WARMING, TARGET_MODE, HEAT_MODE, BOIL_MODE = (3, 1), (3, 7), (3, 10), (3, 11), (3, 12), (3, 13)
+STOP_ACTION = (3, 1)
+STATUS_NAMES = {0: "idle", 1: "heating", 2: "boiling", 3: "cooling down", 4: "keep warm"}
+
+
+class KettleError(Exception):
+    def __init__(self, msg: str, code: int = 1):
+        super().__init__(msg)
+        self.code = code
+
+
+def die(msg: str, code: int = 1):
+    raise KettleError(msg, code)
+
+
+def connect(args, use_saved_token: bool = True, need_token: bool = True) -> tuple[MiioClient, dict]:
+    cfg = config.load_config()
+    shared = getattr(args, "_client", None)
+    if shared is not None and use_saved_token:
+        return shared, cfg
+    ip = args.ip or cfg.get("ip") or die("no kettle configured yet: run `kettle setup`")
+    token_hex = args.token or (cfg.get("token") if use_saved_token else None)
+    token = bytes.fromhex(token_hex) if token_hex else None
+    if token is not None and len(token) != 16:
+        die("token must be 32 hex characters")
+    if token is None and need_token:
+        die("no token saved: run `kettle setup`")
+    return MiioClient(ip, token, timeout=args.timeout, debug=args.debug), cfg
+
+
+def read_props(c: MiioClient, props) -> dict:
+    """Read properties; any non-zero code or missing value aborts (never act on ambiguous data)."""
+    out = {}
+    for item in c.get_properties(props):
+        key = (item.get("siid"), item.get("piid"))
+        if item.get("code") != 0 or "value" not in item:
+            die(f"could not read property {key}: {item}")
+        out[key] = item["value"]
+    if len(out) != len(props):
+        die(f"expected {len(props)} properties, got {len(out)}")
+    return out
+
+
+def get_info(c: MiioClient, cfg: dict, save: bool = True) -> dict:
+    h = c.handshake()
+    info = c.call("miIO.info")
+    if save and isinstance(info, dict):
+        cfg.update(ip=c.ip, token=c.token.hex(), did=h.did, model=info.get("model"))
+        config.save_config(cfg)
+    return info
+
+
+def check_model(c: MiioClient, cfg: dict, args) -> None:
+    if getattr(args, "_model_ok", False):
+        return
+    info = get_info(c, cfg)
+    model = info.get("model")
+    if model != EXPECTED_MODEL and not args.force_model:
+        die(f"model is {model!r}, SPEC.md is for {EXPECTED_MODEL!r}; refusing to send commands "
+            f"(--force-model to override)")
+    if getattr(args, "_client", None) is not None:
+        args._model_ok = True
+
+
+# --- commands ---------------------------------------------------------
+
+def cmd_hello(args):
+    c, _ = connect(args, need_token=False)
+    with c:
+        h = c.handshake()
+    print(f"device id : {h.did} ({h.did:#010x})")
+    print(f"stamp     : {h.stamp}")
+    print(f"checksum  : {h.checksum.hex()}")
+    if h.token:
+        print(f"TOKEN LEAKED in hello reply: {h.token.hex()}")
+        print("  (keep it private; `kettle info` will save it to the config)")
+    else:
+        print("token not exposed in hello reply (zeros/ff): supply it with --token or run `kettle setup`")
+
+
+def cmd_info(args):
+    c, cfg = connect(args, need_token=False)
+    with c:
+        if c.token is None:
+            c.handshake()
+            if c.token is None:
+                die("no token available; run `kettle setup`")
+        info = get_info(c, cfg)
+    shown = {k: ("<saved to config, hidden>" if k == "token" else v) for k, v in info.items()}
+    print(json.dumps(shown, indent=2))
+    print(f"\nmodel: {info.get('model')}"
+          + ("" if info.get("model") == EXPECTED_MODEL else f"   <-- differs from {EXPECTED_MODEL}"))
+    print(f"saved to {config.CONFIG_PATH}")
+
+
+def cmd_status(args):
+    c, cfg = connect(args)
+    with c:
+        v = read_props(c, [STATUS, FAULT, TEMP, TARGET, AUTO_KEEP, KEEP_TEMP, KEEP_MIN, LIFTED, WARMING, TARGET_MODE])
+    print(f"status       : {STATUS_NAMES.get(v[STATUS], v[STATUS])} ({v[STATUS]})")
+    print(f"fault        : {v[FAULT]}")
+    print(f"temperature  : {v[TEMP]} C")
+    print(f"target       : {v[TARGET]} C")
+    print(f"keep warm    : {'on' if v[AUTO_KEEP] else 'off'} at {v[KEEP_TEMP]} C for {v[KEEP_MIN]} min")
+    print(f"warming time : {v[WARMING]} min")
+    print(f"target mode  : {v[TARGET_MODE]}")
+    print(f"lifted       : {v[LIFTED]}")
+    print("water level  : not exposed by this model (a low-water fault shows up in `fault`)")
+
+
+def show_items(items) -> None:
+    for s_, p_, val in items:
+        print(f"  ({s_},{p_}) = {val!r}")
+
+
+def confirm(args, items) -> None:
+    print("About to send set_properties:")
+    show_items(items)
+    if args.yes:
+        return
+    if not sys.stdin.isatty():
+        die("non-interactive: pass --yes to start heating")
+    if input("Start heating? [y/N] ").strip().lower() != "y":
+        die("aborted", 2)
+
+
+TEMP_MIN, TEMP_MAX = 40, 99          # spec: (2,4) target-temperature
+KEEP_MIN_LO, KEEP_MIN_HI = 60, 1440  # spec: (3,1) keep-warm-time, minutes
+
+
+def boil_items(keep_temp, keep_min) -> list:
+    return [(*TARGET, 99), (*AUTO_KEEP, False), (*KEEP_TEMP, keep_temp), (*KEEP_MIN, keep_min),
+            (*TARGET_MODE, 1), (*BOIL_MODE, f"99,0,{keep_temp},{keep_min}")]
+
+
+def warm_to_items(temp, keep_temp, keep_min) -> list:
+    return [(*TARGET, temp), (*AUTO_KEEP, False), (*KEEP_TEMP, keep_temp), (*KEEP_MIN, keep_min),
+            (*TARGET_MODE, 0), (*HEAT_MODE, f"{temp},0,{keep_temp},{keep_min}")]
+
+
+def warm_keep_items(temp, minutes) -> list:
+    return [(*TARGET, temp), (*AUTO_KEEP, True), (*KEEP_TEMP, temp), (*KEEP_MIN, minutes),
+            (*TARGET_MODE, 0), (*HEAT_MODE, f"{temp},1,{temp},{minutes}")]
+
+
+def check_temp(temp: int) -> int:
+    if not TEMP_MIN <= temp <= TEMP_MAX:
+        die(f"temperature must be {TEMP_MIN}-{TEMP_MAX} C (kettle limits), got {temp}")
+    return temp
+
+
+def check_minutes(minutes: int) -> int:
+    if not KEEP_MIN_LO <= minutes <= KEEP_MIN_HI:
+        die(f"keep-warm time must be {KEEP_MIN_LO}-{KEEP_MIN_HI} minutes (1-24 h, kettle limits), got {minutes}")
+    return minutes
+
+
+def start_heating(args, build, label: str) -> None:
+    """Shared flow for boil / warm-to / warm-keep: preflight reads, confirm, write, verify.
+
+    build(keep_temp, keep_min) -> items. On --dry-run nothing is sent (no network at all)."""
+    if args.dry_run:
+        items = build("<current keep temp>", "<current keep min>")
+        if args.set_on:
+            items.append((*ON, True))
+        print(f"dry-run, {label}: set_properties would be:")
+        show_items(items)
+        return
+    c, cfg = connect(args)
+    with c:
+        check_model(c, cfg, args)
+        v = read_props(c, [STATUS, FAULT, TEMP, LIFTED, KEEP_TEMP, KEEP_MIN])
+        if v[FAULT] != 0:
+            die(f"kettle reports fault {v[FAULT]} (possibly low water); not heating")
+        if v[LIFTED]:
+            die("kettle is lifted off its base; not heating")
+        if v[STATUS] != 0:
+            die(f"kettle is not idle ({STATUS_NAMES.get(v[STATUS], v[STATUS])}); run `cancel` first")
+        keep_min = min(max(v[KEEP_MIN], KEEP_MIN_LO), KEEP_MIN_HI)
+        if keep_min != v[KEEP_MIN]:
+            print(f"note: keep-warm minutes {v[KEEP_MIN]} out of spec range, using {keep_min}")
+        print(f"{label}: water at {v[TEMP]} C, idle, no fault.")
+        items = build(v[KEEP_TEMP], keep_min)
+        if args.set_on:
+            items.append((*ON, True))
+        confirm(args, items)
+        results = c.set_properties(items)
+        bad = [r for r in results if r.get("code") != 0]
+        if bad:
+            die(f"device rejected some writes: {bad}")
+        print("accepted. waiting 3 s then reading status...")
+        time.sleep(3)
+        v = read_props(c, [STATUS, FAULT, TEMP])
+    print(f"status: {STATUS_NAMES.get(v[STATUS], v[STATUS])}, {v[TEMP]} C, fault {v[FAULT]}")
+    if v[STATUS] == 0:
+        print("kettle is still idle: the batch alone did not start it. Re-run with --set-on "
+              "(also writes on=true) once you are watching the kettle.")
+
+
+def cmd_boil(args):
+    start_heating(args, boil_items, "boil")
+
+
+def cmd_warm_to(args):
+    t = check_temp(args.temp)
+    start_heating(args, lambda kt, km: warm_to_items(t, kt, km), f"warm to {t} C, then stop")
+
+
+def cmd_warm_keep(args):
+    t, m = check_temp(args.temp), check_minutes(args.minutes)
+    start_heating(args, lambda kt, km: warm_keep_items(t, m), f"warm to {t} C and keep warm {m} min")
+
+
+def cmd_cancel(args):
+    if args.dry_run:
+        print(f"dry-run, action would be: siid={STOP_ACTION[0]} aiid={STOP_ACTION[1]} in=[]")
+        return
+    c, cfg = connect(args)
+    with c:
+        check_model(c, cfg, args)
+        res = c.action(*STOP_ACTION)
+        print(f"action result: {res}")
+        if isinstance(res, dict) and res.get("code") not in (0, None):
+            die("device rejected stop-work")
+        time.sleep(1)
+        v = read_props(c, [STATUS, TEMP])
+    print(f"status: {STATUS_NAMES.get(v[STATUS], v[STATUS])}, {v[TEMP]} C")
+
+
+def local_tz_name() -> str:
+    """Olson name of the Mac's timezone (e.g. Europe/Berlin), or '' if it cannot be determined."""
+    try:
+        target = os.path.realpath("/etc/localtime")
+        return target.split("zoneinfo/", 1)[1]
+    except (OSError, IndexError):
+        return ""
+
+
+def router_params(ssid: str, password: str, uid: int, app_params: bool, cc: str) -> dict:
+    """Params for miIO.config_router. app_params mirrors what the Xiaomi Home app 11.7.704 sends
+    in AP mode, minus bind_key (cloud-issued, deliberately omitted)."""
+    params = {"ssid": ssid, "passwd": password, "uid": uid}
+    if app_params:
+        params.update(config_type="app",
+                      gmt_offset=time.localtime().tm_gmtoff,
+                      tz=local_tz_name(),
+                      wifi_config={"cc": cc})
+    return params
+
+
+def cmd_provision(args):
+    """Send home Wi-Fi credentials via miIO.config_router. Run while joined to the kettle's AP."""
+    import getpass
+    cfg = config.load_config()
+    args.ip = args.ip or "10.10.1.1"
+    if not args.ssid:
+        die("--ssid is required (must be a 2.4 GHz network)")
+    password = getpass.getpass(f"Password for {args.ssid!r} (hidden, not stored): ")
+    if getpass.getpass("Type it again to confirm: ") != password:
+        die("passwords differ; nothing was sent")
+    if args.dry_run:
+        shown = router_params(args.ssid, "<hidden>", args.uid, args.app_params, args.cc)
+        print(f"dry-run: miIO.config_router {json.dumps(shown)}")
+        return
+    # In setup mode the token is re-generated each time, so never trust the saved one here:
+    # take the fresh one the kettle leaks in its hello reply.
+    c, cfg = connect(args, use_saved_token=False, need_token=False)
+    with c:
+        c.handshake()
+        if c.token is None:
+            die("kettle did not leak its token in the hello reply; supply --token")
+        info = get_info(c, cfg)  # also saves token/did/model
+        if info.get("model") != EXPECTED_MODEL and not args.force_model:
+            die(f"unexpected model {info.get('model')!r}")
+        params = router_params(args.ssid, password, args.uid, args.app_params, args.cc)
+        try:
+            res = c.call("miIO.config_router", params, retry=False)
+        except MiioError as e:
+            # The kettle drops its AP as soon as it accepts the config, so a lost reply is expected.
+            print(f"no clean reply ({e}); this is normal if the kettle dropped its AP.")
+            res = None
+    print(f"device replied: {res}")
+    print("Rejoin your normal Wi-Fi, give the kettle ~30 s, then run `kettle find`.")
+
+
+def cmd_find(args):
+    """Locate the saved device on the LAN by sweeping a /24 with hello packets."""
+    cfg = config.load_config()
+    did = cfg.get("did") or die("no saved device id; run `kettle setup` first")
+    base = (args.subnet.rsplit(".", 1)[0] if args.subnet and args.subnet.count(".") == 3
+            else args.subnet) or local_subnet()
+    print(f"sweeping {base}.0/24 for device id {did} ...")
+    found = next((ip for ip, d in discover(base) if d == did), None)
+    if not found:
+        die("device not found; is it online and on the same Wi-Fi/LAN as this computer?")
+    cfg["ip"] = found
+    config.save_config(cfg)
+    print(f"found at {found}, saved to config. Consider a DHCP reservation for it.")
+
+
+def cmd_setup(args):
+    from .wizard import run_setup
+    run_setup(args)
+
+
+def cmd_shell(args):
+    """Interactive session: one open socket, model checked once, same commands as the CLI."""
+    import shlex
+    try:
+        import readline  # noqa: F401  (line editing/history where available)
+    except ImportError:
+        pass
+    parser = build_parser()
+    c, _cfg = connect(args)
+    c.persistent = True
+    args._client = c
+    try:
+        c.handshake()
+        print(f"connected to {c.ip}. Type `help` for commands, `quit` to leave.")
+    except MiioError as e:
+        print(f"warning: handshake failed ({e}); commands will retry")
+    try:
+        while True:
+            try:
+                line = input("kettle> ").strip()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                break
+            if not line:
+                continue
+            if line in ("quit", "exit", "q"):
+                break
+            if line in ("help", "?"):
+                print("boil | warm-to <40-99> | warm-keep <40-99> <60-1440 min> | cancel | status | info")
+                print("add --yes to skip the heating confirmation, --dry-run to only print the RPC")
+                continue
+            try:
+                tokens = shlex.split(line)
+                if tokens[0] in ("shell", "setup", "provision", "find", "hello"):
+                    print(f"`{tokens[0]}` is not available inside the shell")
+                    continue
+                sub_args = parser.parse_args(tokens, namespace=copy.copy(args))
+                run_command(sub_args)
+            except SystemExit:
+                pass  # argparse already printed its message
+            except KettleError as e:
+                print(f"error: {e}")
+            except (MiioError, OSError, ValueError) as e:
+                print(f"error: {e}")
+    finally:
+        c.persistent = False
+        c.close()
+
+
+COMMANDS = {"hello": cmd_hello, "info": cmd_info, "status": cmd_status, "boil": cmd_boil,
+            "warm-to": cmd_warm_to, "warm-keep": cmd_warm_keep, "cancel": cmd_cancel,
+            "provision": cmd_provision, "find": cmd_find, "shell": cmd_shell, "setup": cmd_setup}
+
+
+def run_command(args) -> None:
+    COMMANDS[args.cmd](args)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="kettle", description="Local control of the Xiaomi Smart Kettle 2 Pro.")
+    p.add_argument("--version", action="version", version=f"kettle v{version}")
+    p.add_argument("--ip")
+    p.add_argument("--token", help="32 hex chars")
+    p.add_argument("--timeout", type=float, default=3.0)
+    p.add_argument("--debug", action="store_true", help="print raw packets and RPC")
+    p.add_argument("--dry-run", action="store_true", help="print the RPC instead of sending")
+    p.add_argument("--yes", action="store_true", help="skip heating confirmation")
+    p.add_argument("--force-model", action="store_true")
+    sub = p.add_subparsers(dest="cmd", metavar="command")
+    st = sub.add_parser("setup", help="guided first-time setup (token, IP, check)")
+    st.add_argument("--subnet", help="e.g. 192.168.1 (default: this computer's /24)")
+    sub.add_parser("hello", help="raw handshake, shows whether the token is exposed")
+    sub.add_parser("info", help="miIO.info; saves ip/token/did/model to config")
+    sub.add_parser("status", help="temperature, mode, target, fault, keep-warm")
+    sub.add_parser("cancel", help="stop heating / keep-warm")
+    sub.add_parser("shell", help="interactive session")
+    heat = argparse.ArgumentParser(add_help=False)
+    heat.add_argument("--set-on", action="store_true", help="also write on=true (2,7)")
+    sub.add_parser("boil", parents=[heat], help="heat to boiling")
+    w = sub.add_parser("warm-to", parents=[heat], help="heat to TEMP C, then stop")
+    w.add_argument("temp", type=int, help=f"{TEMP_MIN}-{TEMP_MAX} C")
+    k = sub.add_parser("warm-keep", parents=[heat], help="heat to TEMP C and keep warm for MINUTES")
+    k.add_argument("temp", type=int, help=f"{TEMP_MIN}-{TEMP_MAX} C")
+    k.add_argument("minutes", type=int, help=f"{KEEP_MIN_LO}-{KEEP_MIN_HI}")
+    pr = sub.add_parser("provision", help="advanced: send Wi-Fi to a kettle in setup mode (see README)")
+    pr.add_argument("--ssid")
+    pr.add_argument("--uid", type=int, default=0)
+    pr.add_argument("--app-params", action="store_true",
+                    help="also send config_type/gmt_offset/tz/wifi_config like the Xiaomi Home app")
+    pr.add_argument("--cc", default="GB", help="country code for --app-params (app sends the account's)")
+    f = sub.add_parser("find", help="find the kettle's LAN IP by device id and save it")
+    f.add_argument("--subnet", help="e.g. 192.168.1 (default: the Mac's current /24)")
+    return p
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.cmd is None:
+        parser.print_help()
+        if not config.load_config().get("token"):
+            print("\nFirst time here? Run `kettle setup`.")
+        return
+    try:
+        run_command(args)
+    except KettleError as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(e.code)
+    except (MiioError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

kettle/config.py

@@ -0,0 +1,21 @@
+"""The saved kettle (ip, token, did, model) in ~/.config/kettle/config.json, mode 600."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+CONFIG_PATH = Path(os.path.expanduser("~/.config/kettle/config.json"))
+
+
+def load_config() -> dict:
+    try:
+        return json.loads(CONFIG_PATH.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def save_config(cfg: dict) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(cfg, indent=2))
+    os.chmod(CONFIG_PATH, 0o600)

kettle/miio.py

@@ -0,0 +1,220 @@
+"""Minimal raw miio client (UDP 54321): handshake, AES-128-CBC, JSON-RPC."""
+from __future__ import annotations
+
+import hashlib
+import json
+import socket
+import struct
+import time
+from dataclasses import dataclass
+
+from . import aes
+
+PORT = 54321
+MAGIC = 0x2131
+HELLO = bytes.fromhex("21310020") + b"\xff" * 28
+
+
+class MiioError(Exception):
+    pass
+
+
+class MiioTimeout(MiioError):
+    pass
+
+
+class MiioRpcError(MiioError):
+    def __init__(self, error: dict):
+        super().__init__(f"device returned error: {error}")
+        self.error = error
+
+
+@dataclass
+class Hello:
+    did: int
+    stamp: int
+    checksum: bytes  # holds the token on some unprovisioned/older devices
+
+    @property
+    def token(self) -> bytes | None:
+        """Token if the device leaks it in the hello reply, else None."""
+        if self.checksum in (b"\x00" * 16, b"\xff" * 16):
+            return None
+        return self.checksum
+
+
+def _keys(token: bytes) -> tuple[bytes, bytes]:
+    key = hashlib.md5(token).digest()
+    iv = hashlib.md5(key + token).digest()
+    return key, iv
+
+
+def encrypt(token: bytes, data: bytes) -> bytes:
+    key, iv = _keys(token)
+    return aes.cbc_encrypt(key, iv, data)
+
+
+def decrypt(token: bytes, data: bytes) -> bytes:
+    key, iv = _keys(token)
+    return aes.cbc_decrypt(key, iv, data)
+
+
+def build_packet(token: bytes, did: int, stamp: int, payload: dict) -> bytes:
+    body = encrypt(token, json.dumps(payload, separators=(",", ":")).encode())
+    head = struct.pack(">HHIII", MAGIC, 32 + len(body), 0, did, stamp)
+    checksum = hashlib.md5(head + token + body).digest()
+    return head + checksum + body
+
+
+def parse_packet(data: bytes) -> tuple[int, int, int, bytes, bytes]:
+    """Returns (length, did, stamp, checksum, body). Raises MiioError if malformed."""
+    if len(data) < 32:
+        raise MiioError(f"short packet ({len(data)} bytes)")
+    magic, length, _unk, did, stamp = struct.unpack(">HHIII", data[:16])
+    if magic != MAGIC or length != len(data):
+        raise MiioError(f"bad header: magic={magic:#x} length={length} actual={len(data)}")
+    return length, did, stamp, data[16:32], data[32:]
+
+
+def decode_response(token: bytes, data: bytes) -> dict:
+    _length, _did, _stamp, checksum, body = parse_packet(data)
+    if hashlib.md5(data[:16] + token + body).digest() != checksum:
+        raise MiioError("response checksum mismatch (wrong token?)")
+    return json.loads(decrypt(token, body).rstrip(b"\x00").decode())
+
+
+class MiioClient:
+    def __init__(self, ip: str, token: bytes | None = None, timeout: float = 3.0,
+                 retries: int = 3, port: int = PORT, debug: bool = False):
+        self.ip, self.port = ip, port
+        self.token = token
+        self.timeout, self.retries, self.debug = timeout, retries, debug
+        self.did: int | None = None
+        self.persistent = False  # shell mode: `with` must not close the shared socket
+        self._stamp_base = 0
+        self._stamp_at = 0.0
+        self._id = 0
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self._sock.settimeout(timeout)
+
+    def close(self) -> None:
+        self._sock.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        if not self.persistent:
+            self.close()
+
+    def _log(self, *a):
+        if self.debug:
+            print("[miio]", *a)
+
+    def _roundtrip(self, packet: bytes) -> bytes:
+        self._log("->", packet.hex())
+        self._sock.sendto(packet, (self.ip, self.port))
+        try:
+            data, _ = self._sock.recvfrom(4096)
+        except socket.timeout:
+            raise MiioTimeout(f"no reply from {self.ip}:{self.port} in {self.timeout}s") from None
+        self._log("<-", data.hex())
+        return data
+
+    def handshake(self) -> Hello:
+        """Send hello, sync device id and stamp. Retries on timeout."""
+        last: Exception | None = None
+        for _ in range(self.retries):
+            try:
+                data = self._roundtrip(HELLO)
+            except MiioTimeout as e:
+                last = e
+                continue
+            _l, did, stamp, checksum, _b = parse_packet(data)
+            self.did, self._stamp_base, self._stamp_at = did, stamp, time.monotonic()
+            # A device that leaks its token in the hello reply is telling us its *current* one
+            # (it is regenerated every time setup mode is entered), so it beats any saved token.
+            if Hello(did, stamp, checksum).token:
+                self.token = checksum
+            return Hello(did, stamp, checksum)
+        raise last or MiioTimeout("handshake failed")
+
+    def _stamp(self) -> int:
+        return self._stamp_base + int(time.monotonic() - self._stamp_at) + 1
+
+    def call(self, method: str, params=None, retry: bool = True) -> object:
+        """Send one RPC; re-handshake transparently on timeout or stale stamp.
+
+        retry=False sends exactly once (for non-idempotent calls like config_router)."""
+        if self.token is None:
+            raise MiioError("no token available (the kettle hides it); run `kettle setup`")
+        last: Exception | None = None
+        for attempt in range(self.retries if retry else 1):
+            try:
+                if self.did is None or attempt > 0:
+                    self.handshake()
+                self._id = self._id % 9999 + 1
+                req = {"id": self._id, "method": method, "params": params if params is not None else []}
+                self._log("request", req)
+                data = self._roundtrip(build_packet(self.token, self.did, self._stamp(), req))
+                resp = decode_response(self.token, data)
+                self._log("response", resp)
+                if resp.get("id") != self._id:
+                    raise MiioError(f"id mismatch: sent {self._id}, got {resp.get('id')}")
+                if "error" in resp:
+                    raise MiioRpcError(resp["error"])
+                return resp.get("result")
+            except MiioRpcError:
+                raise
+            except (MiioError, ValueError, OSError) as e:  # timeout, bad checksum, stale stamp, no route...
+                last = e
+                self.did = None
+        raise MiioError(f"{method} failed after {self.retries} attempts: {last}")
+
+    # --- MIoT helpers -------------------------------------------------
+    def get_properties(self, props: list[tuple[int, int]]) -> list[dict]:
+        req = [{"did": f"{s}-{p}", "siid": s, "piid": p} for s, p in props]
+        return self.call("get_properties", req)
+
+    def set_properties(self, items: list[tuple[int, int, object]]) -> list[dict]:
+        req = [{"did": f"{s}-{p}", "siid": s, "piid": p, "value": v} for s, p, v in items]
+        return self.call("set_properties", req)
+
+    def action(self, siid: int, aiid: int, args: list | None = None) -> dict:
+        return self.call("action", {"did": f"action-{siid}-{aiid}", "siid": siid,
+                                    "aiid": aiid, "in": args or []})
+
+
+def local_subnet() -> str:
+    """First three octets of this computer's outgoing IPv4 address, e.g. "192.168.1"."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect(("192.0.2.1", 9))  # no packet is sent; just picks the outgoing interface
+        return s.getsockname()[0].rsplit(".", 1)[0]
+    finally:
+        s.close()
+
+
+def discover(base: str, wait: float = 4.0, port: int = PORT) -> list:
+    """Hello-sweep BASE.1-254; returns [(ip, did)] for every miio device that answers."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.settimeout(0.3)
+    found = {}
+    try:
+        for host in range(1, 255):
+            try:
+                sock.sendto(HELLO, (f"{base}.{host}", port))
+            except OSError:
+                continue
+        deadline = time.monotonic() + wait
+        while time.monotonic() < deadline:
+            try:
+                data, addr = sock.recvfrom(4096)
+                found[addr[0]] = parse_packet(data)[1]
+            except socket.timeout:
+                continue
+            except MiioError:
+                continue
+    finally:
+        sock.close()
+    return sorted(found.items(), key=lambda kv: tuple(int(p) for p in kv[0].split(".")))

kettle/wizard.py

@@ -0,0 +1,167 @@
+"""`kettle setup`: guided first-time setup with on-screen instructions.
+
+Steps: pair in the Xiaomi Home app, get the token with the open-source extractor, paste it,
+find the kettle on the LAN (the token tells us which device is the kettle), verify and save.
+"""
+from __future__ import annotations
+
+import getpass
+import ipaddress
+import re
+import sys
+
+from . import cli, config
+from .miio import MiioClient, MiioError, discover, local_subnet
+
+EXTRACTOR_URL = "https://github.com/PiotrMachowski/Xiaomi-Cloud-Tokens-Extractor"
+EXTRACTOR_ZIP = ("https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor"
+                 "/releases/latest/download/token_extractor.zip")
+TOKEN_RE = re.compile(r"^[0-9a-f]{32}$")
+RULE = "-" * 64
+
+
+def clean_token(raw: str) -> str:
+    """Lower-case a pasted token and drop spaces/quotes/colons; "" if it is not 32 hex digits."""
+    token = re.sub(r"[\s'\"`:]", "", raw).lower()
+    return token if TOKEN_RE.match(token) else ""
+
+
+def probe(ip: str, token: bytes, timeout: float = 1.5):
+    """miIO.info from ip with the token, or None if it does not answer / cannot decrypt."""
+    c = MiioClient(ip, token, timeout=timeout, retries=2)
+    try:
+        info = c.call("miIO.info")
+        return info if isinstance(info, dict) else None
+    except MiioError:
+        return None
+    finally:
+        c.close()
+
+
+def run_setup(args, ask=input, secret=getpass.getpass, out=print) -> None:
+    def step(n: int, title: str) -> None:
+        out(f"\n{RULE}\nStep {n}/4: {title}\n{RULE}")
+
+    scripted = bool(args.token)  # token on the command line: no prompts, for scripts
+    if not scripted and not sys.stdin.isatty() and ask is input:
+        cli.die("setup is interactive; for scripts pass --token (and --ip) instead")
+
+    out("kettle setup: connect this computer to your Xiaomi Smart Kettle 2 Pro")
+    saved = config.load_config()
+    if saved.get("token") and saved.get("ip") and not scripted:
+        out(f"\nAlready set up for {saved['ip']} ({saved.get('model', 'unknown model')}).")
+        if ask("Run setup again? [y/N] ").strip().lower() != "y":
+            out("Nothing changed. Try `kettle status`.")
+            return
+
+    # ---- 1. pairing -------------------------------------------------
+    if not scripted:
+        step(1, "Add the kettle to the Xiaomi Home app")
+        out("""The kettle gets onto your Wi-Fi through Xiaomi's app, and Xiaomi's cloud is the
+only place that knows the kettle's token (its local password). You need this once.
+
+  1. Install "Xiaomi Home" (iOS / Android) and sign in. Remember the server region.
+  2. Add device > Xiaomi Smart Kettle 2 Pro, and follow the in-app Wi-Fi setup.
+     The kettle only works on a 2.4 GHz network.
+  3. Wait until the app shows the kettle as online.
+
+Do not reset or re-add the kettle later: that creates a new token.""")
+        ask("\nPress Enter when the kettle is online in the app... ")
+
+    # ---- 2. token ---------------------------------------------------
+    if not scripted:
+        step(2, "Get the token")
+    token_hex = ""
+    if scripted:
+        token_hex = clean_token(args.token)
+        if not token_hex:
+            cli.die("--token must be 32 hex characters")
+    else:
+        out(f"""Use the free open-source extractor (MIT licensed):
+  {EXTRACTOR_URL}
+
+  Windows:        download token_extractor.exe from the latest release and run it.
+  macOS / Linux:  needs Python 3; in a Terminal run
+      curl -L -o token_extractor.zip {EXTRACTOR_ZIP}
+      unzip token_extractor.zip && cd token_extractor
+      pip3 install -r requirements.txt
+      python3 token_extractor.py
+
+It asks for your Xiaomi account login (or a QR code) and a server region; leave the
+region empty to check all of them. Your login goes only to the extractor, never to kettle.
+In its list find "Xiaomi Smart Kettle 2 Pro" (model xiaomi.kettle.v20) and copy its
+TOKEN: 32 letters and digits. Treat it like a password.""")
+        for attempt in range(3):
+            token_hex = clean_token(secret("\nPaste the token here (hidden, then Enter): "))
+            if token_hex:
+                break
+            out("That is not a 32-character hex token (0-9, a-f). Copy just the token and try again.")
+        if not token_hex:
+            cli.die("no valid token entered; run `kettle setup` again when you have it", 2)
+        out(f"Token accepted (ends in ...{token_hex[-4:]}).")
+    token = bytes.fromhex(token_hex)
+
+    # ---- 3. find the kettle -----------------------------------------
+    step(3, "Find the kettle on your network")
+    ip = args.ip
+    info = None
+    if ip:
+        out(f"Using {ip}.")
+    else:
+        base = args.subnet.rsplit(".", 1)[0] if args.subnet and args.subnet.count(".") == 3 else (
+            args.subnet or local_subnet())
+        out(f"Looking for Xiaomi devices on {base}.0/24 (a few seconds)...")
+        try:
+            devices = discover(base)
+        except OSError as e:
+            cli.die(f"network scan failed: {e}")
+        out(f"{len(devices)} Xiaomi device(s) answered; testing your token on each...")
+        for dev_ip, _did in devices:
+            found = probe(dev_ip, token)
+            if found:
+                ip, info = dev_ip, found
+                out(f"  {dev_ip}: {found.get('model')}  <- your token works here")
+                break
+            out(f"  {dev_ip}: not the kettle (token rejected)")
+    if not ip:
+        if scripted:
+            cli.die("kettle not found; check it is online, or pass --ip")
+        out("""
+Could not find the kettle automatically. Its address is in your router's client list
+(look for a device named "xiaomi", "kettle" or with a MAC starting with E4:FE:43), or in
+the extractor's output. Same Wi-Fi as this computer is required.""")
+        for _ in range(3):
+            raw = ask("Kettle IP address (Enter to quit): ").strip()
+            if not raw:
+                cli.die("setup cancelled", 2)
+            try:
+                ip = str(ipaddress.ip_address(raw))
+                break
+            except ValueError:
+                out("That is not an IPv4 address, like 192.168.1.36.")
+        if not ip:
+            cli.die("no valid IP entered", 2)
+
+    # ---- 4. verify and save -----------------------------------------
+    step(4, "Check and save")
+    info = info or probe(ip, token, timeout=3.0)
+    if info is None:
+        cli.die(f"""{ip} did not accept the token, so nothing was saved. Usual reasons:
+  - the token is from a different device or an old pairing (the extractor shows several);
+  - the kettle was re-added to the app since, so its token changed: run the extractor again;
+  - the kettle is offline or on another network.""")
+    model = info.get("model")
+    if model != cli.EXPECTED_MODEL and not args.force_model:
+        cli.die(f"the device at {ip} is {model!r}, but kettle supports {cli.EXPECTED_MODEL!r} only "
+                f"(Xiaomi Smart Kettle 2 Pro, EU). Nothing was saved.")
+    c = MiioClient(ip, token, timeout=3.0)
+    try:
+        did = c.handshake().did
+    finally:
+        c.close()
+    config.save_config({"ip": ip, "token": token_hex, "did": did, "model": model})
+    out(f"Saved to {config.CONFIG_PATH} (readable by you only).")
+    out(f"\nKettle: {model}, firmware {info.get('fw_ver', '?')}, MAC {info.get('mac', '?')}, IP {ip}")
+    out("Tip: give it a fixed address (DHCP reservation) in your router so the IP never changes.")
+    out("If it ever moves, `kettle find` locates it again.")
+    out(f"\n{RULE}\nAll set. Try:\n  kettle status\n  kettle boil\n  kettle shell\n{RULE}")

kettle_x2p_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: kettle-x2p-cli
+Version: 1.0.0
+Summary: Local control of the Xiaomi Smart Kettle 2 Pro over your Wi-Fi, no cloud at runtime.
+Author-email: Ilia Petrov-Komotskii <ilia@inkedkettle.art>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ManeFunction/kettle-x2p-cli
+Project-URL: Repository, https://github.com/ManeFunction/kettle-x2p-cli
+Project-URL: Issues, https://github.com/ManeFunction/kettle-x2p-cli/issues
+Project-URL: Changelog, https://github.com/ManeFunction/kettle-x2p-cli/blob/main/CHANGELOG.md
+Keywords: xiaomi,mijia,miot,miio,kettle,smart-home,home-assistant,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# kettle
+
+Control your [Xiaomi Smart Kettle 2 Pro](https://www.mi.com/global/product/xiaomi-smart-kettle-2-pro/) from the
+Terminal: boil, heat to a temperature, keep warm for up to 24 hours, check the state or stop it. Everything runs over
+your own Wi-Fi, directly to the kettle - no Xiaomi Home app and no cloud connection when you use it.
+
+```
+$ kettle warm-keep 80 120
+warm to 80 C and keep warm 120 min: water at 41 C, idle, no fault.
+About to send set_properties:
+  (2,4) = 80
+  ...
+Start heating? [y/N] y
+status: heating, 41 C, fault 0
+```
+
+Written for the EU model (BHR9107EU, `xiaomi.kettle.v20`, 1.7 L, 1800 W), tested on firmware `2.2.7_0016`.
+It has no dependencies except Python itself. This is the standalone tool and a documented protocol reference ([SPEC.md](https://github.com/ManeFunction/kettle-x2p-cli/blob/main/SPEC.md))
+made just for fun... or not. Setting a kettle right from the Terminal while working is pretty neat, actually :)
+
+---
+
+## Features
+
+| Command | What it does |
+|---|---|
+| `kettle setup` | Guided first-time setup: asks for the token, finds the kettle, checks and saves it. |
+| `kettle boil` | Heats to boiling (99 °C, the kettle's boil mode). |
+| `kettle warm-to <40-99>` | Heats to that temperature in °C, then stops. |
+| `kettle warm-keep <40-99> <60-1440>` | Heats to that temperature and keeps it warm for that many minutes (1-24 h). |
+| `kettle cancel` | Stops heating / keep-warm. |
+| `kettle status` | State, current temperature, target, fault, keep-warm settings. |
+| `kettle shell` | Interactive session with the same commands. |
+| `kettle info` | Model, firmware and MAC from the kettle. |
+| `kettle find` | Finds the kettle on the network again if its IP changed. |
+
+Useful flags go before the command: `--dry-run` (print the requests, send nothing), `--yes` (skip the heating
+confirmation), `--debug` (raw packets), `--ip`, `--token`.
+
+**Safety.** Heating commands refuse to start unless the kettle is a `xiaomi.kettle.v20`, idle, on its base and
+reporting no fault, and a status read that fails or is unclear never starts anything. They print exactly what they
+will send and ask `y/N` (without a terminal, `--yes` is required). This model has no water-level reading, so a
+low-water condition only shows up as a fault code. Heat water remotely only when you know the kettle has water in it.
+
+---
+
+## Installation
+
+**kettle** is available from a variety of sources.
+`pip` or `brew` is recommended, because they have a convenient way to manage updates automatically.
+
+1) **pip (Recommended for everyone with a Python environment)**
+    - You can check if you have Python installed by running `python --version` in the Terminal or cmd.
+    - For Mac and Linux users, there is a high chance that you already have Python installed on your system.
+    - For Windows users, you can download Python from the [official website](https://www.python.org/downloads/).
+      The tool is built and tested for macOS and Linux; it should work on Windows too, but that is untested.
+    - After confirmation, install **kettle** through the [PyPI](https://pypi.org/project/kettle-x2p-cli) package
+      manager, typing `pip install kettle-x2p-cli` in the Terminal. For Mac users, you may need to use `pip3`
+      instead of `pip`. The package is called `kettle-x2p-cli`; the command it installs is `kettle`.
+    - Verify the installation with `kettle --version`.
+    - You are perfect, you can use the app with `kettle` from any folder in your system.
+2) **brew (Recommended for Mac and Linux users)**
+    - Type `brew tap manefunction/tap` in your Terminal to add my custom tap (app source) to your brew sources,
+      if you haven't already.
+    - Type `brew install kettle` to install the application itself.
+    - Verify the installation with `kettle --version`.
+    - You are perfect, you can use the app with `kettle` from any folder in your system.
+3) **Python package (manual installation, for advanced users)**
+    - Clone the repository or download the source code from GitHub.
+    - Go to the folder with the code in your Terminal.
+    - Run `pip install .` to install `kettle` to your system.
+    - Run `kettle --version` to verify the install.
+
+Updates arrive with `pip install --upgrade kettle-x2p-cli` or `brew upgrade`. Your saved kettle settings live outside the install
+(`~/.config/kettle/`), so upgrading or reinstalling never loses them. (`pip` may ask you to use a virtual environment or `pipx` on newer
+systems; `pipx install kettle-x2p-cli` is a good fit for a command line tool.)
+
+---
+
+## First-time setup
+
+Run `kettle setup` and follow the instructions on the screen. It takes about five minutes the first time and is
+never needed again unless you re-pair the kettle.
+
+1. **Add the kettle to the Xiaomi Home app** (iOS / Android) so it joins your 2.4 GHz Wi-Fi.
+2. **Get the kettle's token** with the free, open-source
+   [Xiaomi Cloud Tokens Extractor](https://github.com/PiotrMachowski/Xiaomi-Cloud-Tokens-Extractor). The setup
+   screen shows the exact commands for Windows, macOS and Linux. It asks for your Xiaomi login and lists your devices
+   with their tokens; copy the 32-character token of *Xiaomi Smart Kettle 2 Pro* (`xiaomi.kettle.v20`).
+3. **Paste the token** into `kettle setup` (the input is hidden). It scans your network, tries the token on every
+   Xiaomi device it finds, and the one that answers is your kettle.
+4. It checks the model and saves everything to `~/.config/kettle/config.json` (readable by you only).
+
+Then try `kettle status`. Reserve the kettle's address in your router (DHCP reservation) so it never moves; if it
+does, `kettle find` locates it again.
+
+For scripts, skip the prompts: `kettle --token <token> --ip <ip> setup`. Note that a token typed on the command
+line is visible in your shell history, so the interactive prompt is the safer way.
+
+### Why the Xiaomi app and cloud are needed once
+
+The kettle talks to the local network with a secret 16-byte token, and only Xiaomi's cloud keeps it for you.
+On firmware `2.2.7` the kettle changes that token when it joins your Wi-Fi, so the token it shows while in
+setup mode stops working afterwards. I tried the alternatives (including the app's own extra provisioning parameters,
+`kettle provision --app-params`); none gave a usable token without the cloud. After the one-time extraction,
+all control is local. If you re-pair or reset the kettle, the token changes and you run `kettle setup` again.
+
+---
+
+## Usage
+
+```bash
+kettle status                  # what is it doing?
+kettle boil                    # asks for confirmation, then heats to boiling
+kettle warm-to 70              # 70 °C, then stop (green tea)
+kettle warm-keep 85 90         # 85 °C and keep it there for 90 minutes
+kettle cancel                  # stop everything
+kettle --dry-run warm-to 70    # show what would be sent
+kettle shell                   # keep a session open
+```
+
+In `kettle shell` you type the same commands without the `kettle` prefix (`boil`, `warm-to 70`, `status`, `quit`).
+Keep-warm time is limited by the kettle to 60-1440 minutes, and the target temperature to 40-99 °C; anything
+else is rejected before it is sent.
+
+### Troubleshooting
+
+- **"no reply from ..."**: the kettle is offline, the IP changed (`kettle find`), or the token is out of date
+  (the kettle silently ignores requests it cannot decrypt). Run `kettle setup` again if you re-paired it.
+- **Setup does not find the kettle**: your computer and the kettle must be on the same network (no guest network
+  or VLAN between them). You can enter the IP by hand; it is in your router's client list.
+- **"kettle reports fault ..."**: check the water level and that the kettle sits on its base. Fault codes are not
+  documented by Xiaomi; `0` means none.
+
+---
+
+## How it works
+
+The kettle speaks Xiaomi's *miio* protocol over UDP port 54321: a hello handshake that returns the device id and
+a timestamp, then JSON-RPC calls encrypted with AES-128-CBC keyed from the token. Its functions are described by
+a MIoT spec (service/property numbers); the ones used here are listed in [SPEC.md](https://github.com/ManeFunction/kettle-x2p-cli/blob/main/SPEC.md). The client is a few hundred
+lines of standard-library Python, including its own AES, and handles re-handshakes and timestamp drift by itself.
+
+---
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e .
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+The tests run against a fake kettle on the loopback interface that speaks the real wire format; nothing touches a
+real device. The release workflow checks that the tag matches `src/kettle/__init__.py`, builds the package and
+publishes it to PyPI and creates the GitHub release; the Homebrew formula is bumped automatically.
+
+---
+
+## Credits
+
+- [python-miio](https://github.com/rytilahti/python-miio) for documenting the miio protocol.
+- [Xiaomi Cloud Tokens Extractor](https://github.com/PiotrMachowski/Xiaomi-Cloud-Tokens-Extractor) by Piotr Machowski.
+- [miot-spec.org](https://home.miot-spec.com/) for the device specs, and username-ardrey for
+  [Xiaomi Smart Kettle integration for Home Assistant](https://github.com/username-andrey/xiaomi-smart-kettle-ha),
+  which shows how this model is started.
+
+This is an unofficial project and is not affiliated with Xiaomi.
+
+
+## Repository info
+
+This repo follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/ManeFunction/kettle-x2p-cli)](https://github.com/ManeFunction/kettle-x2p-cli/releases/latest)
+[![GitHub All Releases](https://img.shields.io/github/downloads/ManeFunction/kettle-x2p-cli/total)](https://github.com/ManeFunction/kettle-x2p-cli/releases)
+[![PyPI version](https://img.shields.io/pypi/v/kettle-x2p-cli)](https://pypi.org/project/kettle-x2p-cli/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/kettle-x2p-cli)](https://pypi.org/project/kettle-x2p-cli/)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/ManeFunction?label=Sponsor&logo=GitHubSponsors&style=flat)](https://github.com/sponsors/ManeFunction)

kettle_x2p_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kettle/__init__.py,sha256=dc-o4WFlOYPBeu9k2cG7M0K6uAsf67Ndji-YeZt-XEk,86
+kettle/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+kettle/aes.py,sha256=AkpK_smvLQJQeG_A7l3yyf3NMT84GO0JEUuGyILrjYY,4624
+kettle/cli.py,sha256=56SGetUBaBVP9Ml6kqJIcvUJw0zVx_tO1N-5tI-9aA4,18034
+kettle/config.py,sha256=1Tds5JTYQ1sSt0hzo8bse486V8t_NU0TJoGI2FceEA8,589
+kettle/miio.py,sha256=GhlViyUzmXZugcRIwS5zaICj3bXyz0yJQ17vwoBm2oA,8217
+kettle/wizard.py,sha256=X2ShDfaq8aGabKiqg3ulRvGeB-M-paBt3ABR8kdxDn8,7540
+kettle_x2p_cli-1.0.0.dist-info/licenses/LICENSE,sha256=4ns8nl0KWTDY69GjkDm3TnKKnec1MeAGioDzBPi-HNw,1105
+kettle_x2p_cli-1.0.0.dist-info/METADATA,sha256=xli8e2M7pX71rkM3Jgyp9eGllX-3a-JaKzWMATjduz0,11019
+kettle_x2p_cli-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+kettle_x2p_cli-1.0.0.dist-info/entry_points.txt,sha256=hOy4SxavQKxPJjoTo-sISJgkt_EOlumgKgqLvvWBRns,43
+kettle_x2p_cli-1.0.0.dist-info/top_level.txt,sha256=LJMwvPf4zNJ7KHw-sIgdw8bRfkEeBtrc9gF3MQE5WYY,7
+kettle_x2p_cli-1.0.0.dist-info/RECORD,,

kettle_x2p_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kettle_x2p_cli-1.0.0.dist-info/entry_points.txt

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

kettle_x2p_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Ilia Petrov-Komotskii (Mane Function)
+
+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.

kettle_x2p_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kettle