{
  "added_at": "2026-11-03",
  "additional_evidence_urls": [
    "https://github.com/anna-oake/xiaomi-kettle/blob/fbc0b513bed9fbe08edaa97d33e2e12e04d02544/cipher.go",
    "https://github.com/anna-oake/xiaomi-kettle/blob/fbc0b513bed9fbe08edaa97d33e2e12e04d02544/LICENSE.txt"
  ],
  "category": "reconstruction-cases",
  "description_en": "Documents the closed Bluetooth Low Energy GATT protocol of the Xiaomi Kettle, which the author reconstructed by decompiling the Mi Home Android app and disassembling its native encryption library. The write-up covers the connection and authentication handshake, the layout of status notifications and the writable settings characteristics, with a small Go reimplementation of the cipher helpers. The author built a kettle-to-MQTT bridge for Home Assistant from it but did not publish that code, and gives no guarantee that the notes work for others.",
  "description_zh": "记录 Xiaomi 电水壶封闭的低功耗蓝牙 GATT 协议；作者通过反编译 Mi Home Android 应用并反汇编其负责加密的原生库重建了该协议。文档涵盖连接与认证握手、状态通知的数据布局以及可写入的设置特征值，并附有用 Go 重新实现的少量加密辅助函数。作者据此开发了接入 Home Assistant 的水壶–MQTT 桥接程序，但未公开其代码，也不保证这些笔记对他人同样适用。",
  "entry_url": "https://awesomerea.org/resources/xiaomi-kettle-ble-protocol-case/",
  "entry_url_zh": "https://awesomerea.org/zh/resources/xiaomi-kettle-ble-protocol-case/",
  "evidence_url": "https://github.com/anna-oake/xiaomi-kettle/blob/fbc0b513bed9fbe08edaa97d33e2e12e04d02544/README.md",
  "group": "cases",
  "id": "xiaomi-kettle-ble-protocol-case",
  "json_url": "https://awesomerea.org/resources/xiaomi-kettle-ble-protocol-case/record.json",
  "kind": "case-study",
  "markdown_url": "https://awesomerea.org/resources/xiaomi-kettle-ble-protocol-case/index.md",
  "markdown_url_zh": "https://awesomerea.org/zh/resources/xiaomi-kettle-ble-protocol-case/index.md",
  "name": "Xiaomi Kettle BLE protocol: reconstructing a smart kettle's control interface",
  "name_zh": "Xiaomi Kettle BLE protocol：重建智能电水壶的控制接口",
  "record_type": "resource",
  "relationship": "independent-reconstruction",
  "requirements": [
    "Reviewed at the final commit of 2018-11-29; the repository is archived and consists of a README and one Go file. README says the kettle is built on a QN9020 MCU, and it names no specific model or firmware version.",
    "Applying the notes needs the user's own kettle and any BLE library that can read, write and subscribe to characteristics; the author used Go with currantlabs/ble. The Mi Home app, its native library and any decompiled output are not included, and the handshake uses a token the client generates itself, so no vendor key is committed or needed.",
    "README lists device limits it observed: heating cannot be started over BLE unless Keep Warm mode is already active, Keep Warm can only be re-enabled with the physical button, and its time limit tops out at 12 hours.",
    "cipher.go contains only the cipher and byte-mixing helpers, not a client. There are no tests, captures or verification records, so the protocol description is author-reported; the README credits jadx-gui and IDA Pro.",
    "WTFPL version 2 (LICENSE.txt). Xiaomi and Mi Home remain trademarks of their owner."
  ],
  "requirements_zh": [
    "在 2018-11-29 的最后一次提交处审阅；仓库已归档，只包含一份 README 和一个 Go 文件。README 称该水壶基于 QN9020 MCU，但未指明具体型号或固件版本。",
    "使用这些笔记需要使用者自己的水壶，以及任意能读写并订阅特征值的 BLE 库；作者使用 Go 与 currantlabs/ble。仓库未收录 Mi Home 应用、其原生库或任何反编译产物；握手使用客户端自行生成的令牌，因此既没有提交也不需要任何厂商密钥。",
    "README 列出了作者观察到的设备限制：除非保温模式已开启，否则无法通过 BLE 启动加热；保温模式只能用实体按键重新开启；保温时限最长为 12 小时。",
    "cipher.go 只包含加密与字节混排辅助函数，并非完整客户端。仓库没有测试、抓包或验证记录，因此协议说明为作者报告；README 致谢了 jadx-gui 和 IDA Pro。",
    "采用 WTFPL 第 2 版许可（LICENSE.txt）。Xiaomi 与 Mi Home 仍为其权利人的商标。"
  ],
  "targets": [
    "protocol"
  ],
  "url": "https://github.com/anna-oake/xiaomi-kettle",
  "verification": "source-reviewed",
  "verified_at": "2026-10-27"
}