h5vx/xiaomi-air-purifier-exporter repository overview

⁠Xiaomi Air Purifier Exporter

A Prometheus⁠ exporter for the Xiaomi Smart Air Purifier Elite (zhimi.airp.meb1). It talks to the device directly over the local miIO protocol, so it needs no Xiaomi cloud, no Home Assistant and no python-miio, only cryptography and prometheus-client.

⁠Features

• Exports temperature, humidity, PM2.5, PM10, air quality, fan level, mode, plasma/UV state, filter life and more (see Metrics⁠)
• Locates the device by MAC address, so DHCP lease changes don't break anything
• Recovers on its own after device reboots and network glitches
• Tiny Docker image for amd64 and arm64 (Raspberry Pi included)
• Ships with a ready-made Grafana dashboard⁠

⁠Quick start

⁠1. Get the device token

miIO traffic is encrypted with a per-device 32-character token. The easiest way to get it is Xiaomi-cloud-tokens-extractor⁠:

# Linux
bash <(curl -L https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor/raw/master/run.sh)

# or, if that fails, the Docker version
bash <(curl -L https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor/raw/master/run_docker.sh)

On Windows, download token_extractor.exe⁠.

Log in with your Mi Home account. The extractor prints every device with its TOKEN, IP and MAC. Write down the ones for your purifier (model zhimi.airp.meb1).

⁠2. Run the exporter

cp .env.example .env   # put XIAOMI_TOKEN and XIAOMI_MAC in here
docker compose up -d

or without compose:

docker run -d --name xiaomi-air-purifier-exporter \
  --network host --restart unless-stopped \
  -e XIAOMI_TOKEN=0123456789abcdef0123456789abcdef \
  -e XIAOMI_MAC=aa:bb:cc:dd:ee:ff \
  h5vx/xiaomi-air-purifier-exporter

Check it: curl -s localhost:9811/metrics | grep xiaomi_

⁠3. Scrape it with Prometheus

scrape_configs:
  - job_name: xiaomi-air-purifier
    scrape_interval: 30s
    static_configs:
      - targets: ["<exporter-host>:9811"]

⁠4. Import the Grafana dashboard

In Grafana go to Dashboards → New → Import, upload contrib/grafana/dashboard.json⁠ and pick your Prometheus data source.

⁠Configuration

The device IP is looked up in /proc/net/arp. If it isn't there, the exporter pings every host in the directly attached subnets (/22 or smaller) to fill the ARP cache. On larger networks, reserve a DHCP lease or add a static ARP entry.

⁠Metrics

All metrics are gauges, refreshed from the device on every scrape.

⁠Running without Docker

Python 3.10+ is required.

pip install git+https://github.com/h5vx/xiaomi-air-purifier-exporter
XIAOMI_TOKEN=... XIAOMI_MAC=... xiaomi-air-purifier-exporter

⁠Helper scripts

The scripts/⁠ directory has a few tools for poking at miIO devices:

• discover.py [broadcast-or-ip]: finds miIO devices on the LAN with the "hello" broadcast
• read_sensors.py <ip> <token>: dumps every readable MIoT property of a device, using its spec from miot-spec.org⁠. Needs python-miio (pip install ".[tools]"). Handy for adding support for other models.

⁠Development

uv run --group dev pytest
docker build -t xiaomi-air-purifier-exporter .

To publish a release, push a tag such as v0.1.0. GitHub Actions then builds and pushes the multi-arch image to Docker Hub. The repository needs the DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets.

⁠License

MIT⁠. The product photo is © Xiaomi and is used for illustration only. This project is not affiliated with Xiaomi.