kettle-x2p-cli 1.0.0__tar.gz

kettle_x2p_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-16
+### Added
+- Initial release, available from [PyPI](https://pypi.org/project/kettle-x2p-cli/) (`pip install kettle-x2p-cli`),
+  the [mane tap](https://github.com/ManeFunction/homebrew-tap) (`brew install kettle`) and GitHub releases.
+  Local control of the Xiaomi Smart Kettle 2 Pro (EU, `xiaomi.kettle.v20`) over the LAN:
+  `boil`, `warm-to <temp>`, `warm-keep <temp> <minutes>`, `cancel` and `status`, plus an interactive `shell`.
+- `kettle setup`: guided first-time setup with on-screen instructions. It explains how to pair the kettle in the
+  Xiaomi Home app, where to get the token extractor, asks for the token (hidden input), finds the kettle on the
+  network by trying the token on each Xiaomi device, then verifies and saves it.
+- `info`, `find` (re-locates the kettle after an IP change) and `hello` (raw handshake, for diagnostics).
+- `provision` for an advanced, experimental Wi-Fi setup of a kettle in setup mode.
+- Safety checks before heating: the kettle must be `xiaomi.kettle.v20`, idle, without a fault and on its base;
+  the exact writes are printed and confirmed (`--yes` is required without a terminal). `--dry-run` prints the
+  requests without sending anything.
+- Config in `~/.config/kettle/config.json` (mode 600). The client re-handshakes and re-syncs the device
+  timestamp on its own.
+- No dependencies: AES-128-CBC is implemented in pure Python (checked against the FIPS-197 and NIST SP 800-38A
+  test vectors).

kettle_x2p_cli-1.0.0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md SPEC.md LICENSE
+graft tests
+global-exclude __pycache__ *.py[cod]

kettle_x2p_cli-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,178 @@
+# 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/SPEC.md

@@ -0,0 +1,68 @@
+# MIoT spec: Xiaomi Smart Kettle 2 Pro (EU, BHR9107EU)
+
+**Model string: `xiaomi.kettle.v20`** ("Xiaomi Smart Kettle 2 Pro (欧规版)").
+URN: `urn:miot-spec-v2:device:kettle:0000A009:xiaomi-v20:1`
+
+> Status: **model confirmed on the device** (`miIO.info` returned `model: xiaomi.kettle.v20`,
+> firmware `2.2.7_0016`, hw `esp32`). `boil`, `warm-to`, `warm-keep`, `cancel` and `status` are all verified on the device.
+
+Sources (two agree on all numbers): home.miot-spec.com/spec/xiaomi.kettle.v20 and
+miot-spec.org/miot-spec-v2/instance?type=<URN above>.
+
+## siid 2: kettle
+
+| piid | name | format | access | range / values | unit |
+|---|---|---|---|---|---|
+| 1 | status | uint8 | r/n | 0 Idle, 1 Heating, 2 Boiling, 3 Cooling down, 4 Keep warm | |
+| 2 | fault | uint8 | r/n | 0–255 (0 = none) | |
+| 3 | temperature | int8 | r/n | -30–100 | °C |
+| 4 | target-temperature | uint8 | r/w/n | 40–99 | °C |
+| 5 | auto-keep-warm | bool | r/w/n | | |
+| 6 | keep-warm-temperature | uint8 | r/w/n | 0–100 | °C |
+| 7 | on | bool | r/w/n | | |
+
+## siid 3: function (xiaomi-spec)
+
+| piid | name | format | access | range / values | unit |
+|---|---|---|---|---|---|
+| 1 | keep-warm-time | uint16 | r/w/n | **60–1440** | min |
+| 2 | custom-knob-temp | bool | r/w/n | | |
+| 4 | lift-remember-temp | bool | r/w/n | | |
+| 5 | boiling-reminder | bool | r/w/n | | |
+| 6 | keep-warm-reminder | bool | r/w/n | | |
+| 7 | kettle-lifting | bool | r/n | true = kettle lifted off base | |
+| 8 | extended-mode | string | r/w/n | `name,temp,keep,keep_temp,minutes_...` presets | |
+| 10 | warming-time | uint16 | r/n | 0–720 | min |
+| 11 | target-mode | uint8 | r/w/n | 0 Heating, 1 Boiling, 10–15 Extended 1–6 | |
+| 12 | heat-mode | string | r/w/n | `"<target>,<keep 1/0>,<keep_temp>,<keep_min>"`, e.g. `70,1,45,1440` | |
+| 13 | boil-mode | string | r/w/n | same layout, e.g. `99,1,45,1440` | |
+
+Action: **siid 3, aiid 1 `stop-work`** (in: `[]`, out: `[]`).
+
+Other services (not used): siid 6 no-disturb (piid 1, bool); siid 4 knob-setting (piid 1–7, strings);
+siid 5 local-timing (piid 1–6 strings, action aiid 1 push-water-reminder). Events omitted.
+
+There is **no water-level property** in this spec. The closest safety signals are `fault` (2,2),
+`status` (2,1) and `kettle-lifting` (3,7). The unofficial HA integration for this model reports that
+fault `E2` = low water, but I have not confirmed the numeric fault code for it.
+
+## Proposed command mapping
+
+How the device is *started* is not defined by the spec itself; the batch below comes from the community integration
+[username-andrey/xiaomi-smart-kettle-ha](https://github.com/username-andrey/xiaomi-smart-kettle-ha)
+(tested on firmware v2.2.7_0016), which sends one `set_properties` with these items in this order.
+`boil` was confirmed on our hardware (starts heating without writing `on`).
+
+| command | set_properties (siid,piid = value) |
+|---|---|
+| `boil` | (2,4)=99, (2,5)=false, (2,6)=keep_temp, (3,1)=keep_min, (3,11)=1, (3,13)=`"99,0,<keep_temp>,<keep_min>"` |
+| `warm-to T` | (2,4)=T, (2,5)=false, (2,6)=keep_temp, (3,1)=keep_min, (3,11)=0, (3,12)=`"T,0,<keep_temp>,<keep_min>"` |
+| `warm-keep T M` | (2,4)=T, (2,5)=true, (2,6)=T, (3,1)=M, (3,11)=0, (3,12)=`"T,1,T,M"` |
+| `cancel` | action (3,1) stop-work |
+| `status` | get (2,1) (2,2) (2,3) (2,4) (2,5) (2,6) (3,7) (3,10) (3,11) |
+
+Validation limits taken from the spec: target 40–99 °C; keep-warm minutes 60–1440 (spec minimum is
+60, so `warm-keep` rejects less than 1 h).
+
+Open points:
+Which `fault` value means low water is still unknown.

kettle_x2p_cli-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kettle-x2p-cli"
+dynamic = ["version"]
+description = "Local control of the Xiaomi Smart Kettle 2 Pro over your Wi-Fi, no cloud at runtime."
+authors = [
+    { name = "Ilia Petrov-Komotskii", email = "ilia@inkedkettle.art" }
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = ["xiaomi", "mijia", "miot", "miio", "kettle", "smart-home", "home-assistant", "cli"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Home Automation",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ManeFunction/kettle-x2p-cli"
+Repository = "https://github.com/ManeFunction/kettle-x2p-cli"
+Issues = "https://github.com/ManeFunction/kettle-x2p-cli/issues"
+Changelog = "https://github.com/ManeFunction/kettle-x2p-cli/blob/main/CHANGELOG.md"
+
+[project.scripts]
+kettle = "kettle.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "kettle.version" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"

kettle_x2p_cli-1.0.0/setup.cfg

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

kettle_x2p_cli-1.0.0/src/kettle/__init__.py

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

kettle_x2p_cli-1.0.0/src/kettle/__main__.py

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