Connector for Xiaomi Mi Scale





GitHub Stars



Last Commit

2mos ago









version docker_badge

Xiaomi Mi Scale

Code to read weight measurements from Xiaomi Body Scales.


Please note that as off 0.2.0, the config is now located in options.json and no longer in the docker-compose / environment Please read on for for more information. This change was necessary to allow for unlimited number of users.

Supported Scales:

Mi Smart Scale 2                                                                                              XMTZCO1HM, XMTZC04HMMi Scale_2
Mi Body Composition ScaleXMTZC02HMMi Scale
Mi Body Composition Scale 2XMTZC05HMMi Body Composition Scale 2

Home Assistant Add-On:

If using Home Assistant (formerly known as hass.io), try instead the Xiaomi Mi Scale Add-On for Home Assistant based on this repository.

Getting the Mac Address of your Scale:

  1. Retrieve the scale's MAC Address from the Xiaomi Mi Fit App:

MAC Address

Setup & Configuration:

Running script with Docker:

  1. Supported platforms:
    1. linux/386
    2. linux/amd64
    3. linux/arm32v6
    4. linux/arm32v7
    5. linux/arm64v8
  2. Open docker-compose.yml (see below) and edit the environment to suit your configuration...
  3. Stand up the container - docker-compose up -d


version: '3'

    image: lolouk44/xiaomi-mi-scale:latest
    container_name: mi-scale
    restart: always

    network_mode: host
    privileged: true
      - ./data:/data


All the config needs to be in a file named options.json. You can get a copy of one with minimum config here

List of options

MISCALE_MACstringYesMac address of your scale
MQTT_HOSTstringYesMQTT Server (defaults to
HCI_DEVstringNoBluetooth hci device to use. Defaults to hci0
MQTT_PREFIXstringNoMQTT Topic Prefix. Defaults to miscale
MQTT_USERNAMEstringNoUsername for MQTT server (comment out if not required)
MQTT_PASSWORDstringNoPassword for MQTT (comment out if not required)
MQTT_PORTintNoDefaults to 1883
MQTT_DISCOVERYboolNoMQTT Discovery for Home Assistant Defaults to true
MQTT_DISCOVERY_PREFIXstringNoMQTT Discovery Prefix for Home Assistant. Defaults to homeassistant
MQTT_TLS_CACERTSstringNoMQTT TLS connection: directory with CA certificate(s) that signed MQTT Server's TLS certificate, defaults to None (= no TLS connection)
MQTT_TLS_INSECUREboolNoMQTT TLS connection: don't verify hostname in TLS certificate, defaults to None (= always check hostname)
BLUEPY_PASSIVE_SCANboolNoTry to set to true if getting an error like Bluetooth connection error: Failed to execute management command ‘le on’ on a Raspberry Pi. Defaults to false
TIME_INTERVALintNoTime in sec between each query to the scale, to allow other applications to use the Bluetooth module. Defaults to 30
USERSListYesList of users to add

Auto-gender selection/config -- This is used to create the calculations such as BMI, Water/Bone Mass etc... Here is the logic used to assign a measured weight to a user:

  • If the weight is within the range of a user's defined values for GT and LT, then it will be assigned (published) to that user.
  • If the weight matches two separate user ranges, it will only be assigned to the first user that matched (so don't overlap ranges!)
User OptionTypeRequiredDescription
GTintYesGreater Than - Weight must be greater than this value - this will be the lower limit for the weight range of this user
LTintYesLess Than - Weight must be less than this value - this will be the upper limit for the weight range of this user
SEXstringYesmale / female
NAMEstringYesName of the user
HEIGHTintYesHeight (in cm) of the user
DOBstringYesDOB (in yyyy-mm-dd format)

Note: The weight definitions must be in the same unit as the scale (kg, Lbs, jin)

Running script directly on your host system:

Note: Python 3.6 or higher is required to run the script manually

Note: this is now deprecated. It would still work provided the path to options.json is manually set in the code manually set path at line 39: with open('/data/options.json') as json_file

  1. Install python requirements (pip3 install -r requirements.txt)
  2. Open wrapper.sh and configure your environment variables to suit your setup.
  3. Add a cron-tab entry to wrapper like so:
@reboot bash /path/to/wrapper.sh

NOTE: Although once started the script runs continuously, it may take a few seconds for the data to be retrieved, computed and sent via mqtt.

Home-Assistant Setup:

Under the sensor block, enter as many blocks as users configured in your environment variables:

  - platform: mqtt
    name: "Example Name Weight"
    state_topic: "miscale/USER_NAME/weight"
    value_template: "{{ value_json['weight'] }}"
    unit_of_measurement: "kg"
    json_attributes_topic: "miscale/USER_NAME/weight"
    icon: mdi:scale-bathroom

  - platform: mqtt
    name: "Example Name BMI"
    state_topic: "miscale/USER_NAME/weight"
    value_template: "{{ value_json['bmi'] }}"
    icon: mdi:human-pregnant
    unit_of_measurement: "kg/m2"

Mi Scale

Mi Scale


Thanks to @syssi (https://gist.github.com/syssi/4108a54877406dc231d95514e538bde9) and @prototux (https://github.com/wiecosystem/Bluetooth) for their initial code

Special thanks to @ned-kelly for his help turning a "simple" python script into a fully fledged docker container

Thanks to @bpaulin, @AiiR42, @andreasbrett for their PRs and collaboration

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0