mikettle

Python library for authenticating with and reading status data from a Xiaomi Mi Kettle via Bluetooth Low Energy (BLE).

The authentication protocol was reverse-engineered by aprosvetova.

---

Features

• Authenticates with the Mi Kettle using the proprietary RC4-based handshake
• Reads device name and firmware version
• Reads live status data:
  • Current action (idle / heating / cooling / keeping warm)
  • Current mode (none / boil / keep warm)
  • Set temperature
  • Current temperature
  • Keep-warm type (warm up / cool down)
  • Keep-warm time
• Thread-safe in-memory cache with configurable timeout

---

Requirements

• Python 3.6+
• A Bluetooth Low Energy adapter (e.g. built-in on Raspberry Pi, or a USB dongle)
• bluepy – install via pip install bluepy
• A Xiaomi Mi Kettle

---

Installation

pip install bluepy
python setup.py install

Or directly from PyPI (once published):

pip install mikettle

---

Quick Start

Find your kettle's MAC address:

sudo hcitool lescan

Run the demo script (European Product ID is 275):

python demo.py connect AB:CD:EF:12:34:56 275

---

Library Usage

from mikettle.mikettle import (
    MiKettle,
    MI_ACTION,
    MI_MODE,
    MI_SET_TEMPERATURE,
    MI_CURRENT_TEMPERATURE,
    MI_KW_TYPE,
    MI_KW_TIME,
)

kettle = MiKettle("AB:CD:EF:12:34:56", product_id=275)

print(kettle.name())
print(kettle.firmware_version())
print(kettle.parameter_value(MI_CURRENT_TEMPERATURE))
print(kettle.parameter_value(MI_MODE))

Parameters

Constant	Description	Example value
MI_ACTION	What the kettle is doing right now	"heating"
MI_MODE	Active programme	"boil"
MI_SET_TEMPERATURE	Target temperature (°C)	100
MI_CURRENT_TEMPERATURE	Measured water temperature (°C)	25
MI_KW_TYPE	Keep-warm direction	"warm up"
MI_KW_TIME	Keep-warm duration (seconds)	3600

---

Running Tests

pip install -r requirements-test.txt
pytest tests/

---

Home Assistant

A Home Assistant custom component is included in this repository under custom_components/mikettle/.

Installation

1. Copy the custom_components/mikettle folder into your Home Assistant config/custom_components/ directory so the final path looks like:

   config/
   └── custom_components/
       └── mikettle/
           ├── __init__.py
           ├── const.py
           ├── manifest.json
           └── sensor.py
   

2. Restart Home Assistant.

Configuration

Add the following to your configuration.yaml:

sensor:
  - platform: mikettle
    mac: "AB:CD:EF:12:34:56"   # Bluetooth MAC address of your kettle
    product_id: 275             # 275 for the EU model
    name: Mi Kettle             # optional, default: "Mi Kettle"
    scan_interval: 60           # optional, seconds between polls (default: 60)
    cache_timeout: 600          # optional, seconds before cache expires (default: 600)

Find your kettle's MAC address with:

sudo hcitool lescan

Sensors Created

Entity suffix	Unit	Description
current_temperature	°C	Measured water temperature
set_temperature	°C	Target temperature
action	–	Current action (idle / heating / …)
mode	–	Active mode (none / boil / keep warm)
keep_warm_type	–	Keep-warm direction (warm up / cool down)
keep_warm_time	s	Keep-warm duration in seconds

All sensors are grouped under a single Mi Kettle device in the Home Assistant device registry.

---

License

MIT