lumimqtt 1.0.18

Xiaomi Lumi Gateway MQTT integration

MQTT agent for Xiaomi Lumi gateway

Description

The service allow controlling gateway LEDs, button, and illuminance sensor over MQTT

Default config should be located in /etc/lumimqtt.json or can be overridden with LUMIMQTT_CONFIG environment variable.

Interaction

Default devices

Action	Topic	Payload	Expected values
Read light state	lumi/<ID>/light		{"state": "ON", "brightness": 255, "color": {"r": 255, "g": 0, "b": 0}}
Switch light	lumi/<ID>/light/set	{"state": "ON"}
Set light color	lumi/<ID>/light/set	{"color": {"r": 255, "g": 0, "b": 0}}
Set brightness	lumi/<ID>/light/set	{"brightness": 255}
Set color or brigthness with 10 seconds transition	lumi/<ID>/light/set	{"color": {"r": 255, "g": 0, "b": 0}, "brightness": 100, "transition": 10}
Read illuminance	lumi/<ID>/illuminance		0-1000
Button	lumi/<ID>/btn0/action		single, double, triple, quadruple, many, hold, double_hold, triple_hold, quadruple_hold, many_hold, release

Binary sensors (soldered to GPIO points)

Action	Topic	Expected values
Read GPIO sensor	lumi/<ID>/<SENSOR_NAME>	ON/OFF

Run application

Example run command:

LUMIMQTT_CONFIG=./lumimqtt.json python3 -m lumimqtt

The configuration file is a JSON with the following content:

{
    "mqtt_host": "localhost",
    "mqtt_port": 1883,
    "mqtt_user": "",
    "mqtt_password": "",
    "topic_root": "lumi/{device_id}",
    "auto_discovery": true,
    "sensor_retain": false,
    "sensor_threshold": 50,
    "sensor_debounce_period": 60,
    "legacy_color_mode": true,
    "light_transition_period": 1.0
}

Every line is optional. By default, LumiMQTT will use the connection to localhost with the anonymous login.

device_id if not provided will be automatically replaced by a hex number representing a MAC address of the first network interface.

auto_discovery set to false to disable creating autodiscovery topics that are user by Home Assistant to discover entities.

sensor_retain is option to enable storing last sensor value on the broker

sensor_threshold is a threshold to avoid sending data to MQTT on small changes

sensor_debounce_period value in seconds to send data despite the threshold

light_transition_period value in seconds to set default transition for light switching or light change. Use 0 to remove the transition.

legacy_color_mode set to false to use with Home Assistant 2024.4 or newer

SSL connection

To use SSL connection, you need to set mqtt_cert and mqtt_key, and optional mqtt_ca with corresponding paths to files.

Custom sensors

You can also use GPIO(s) as binary sensor(s). Add this to configuration:

{
    <your configuration>,
    "binary_sensors": {
        "<sensor name>": {
            "gpio": "<gpio number>",
            "device_class": "<device class>",
            "topic": "<sensor name>"
        }
    }
}

Values in <> must be replaced.

gpio is required, device_class and topic are optional. By default topic is sensor's name.

List of GPIOs. List of device classes.

Custom commands

You can add an extra section with custom commands that are executed with mqtt topics. Every command is exported as a switch entity in Home Assistant. If json is passed to the set topic, the command will be interpolated with the values. Plain text is passed as {text} variable

{
    <your configuration>,
    "custom_commands": {
      "blink": "for i in 0 255 0 255 0 255 0; do echo $i > /sys/class/leds/{color}/brightness; sleep 1; done",
      "tts": "echo \"Test TTS without MPD component for home assistant\" | python3 -c 'from urllib.parse import quote_plus;from sys import stdin;print(\"wget -O /tmp/tts.mp3 -U Mozilla \\\"http://translate.google.com/translate_tts?q=\"+quote_plus(stdin.read()[:100])+\"&ie=UTF-8&tl=en&total=1&idx=0&client=tw-ob&prev=input&ttsspeed=1\\\" && amixer set Master 200 && mpg123 /tmp/tts.mp3\")' | sh 2> /dev/null",
      "tts_interpolate": "echo \"{text}\" | python3 -c 'from urllib.parse import quote_plus;from sys import stdin;print(\"wget -O /tmp/tts.mp3 -U Mozilla \\\"http://translate.google.com/translate_tts?q=\"+quote_plus(stdin.read()[:100])+\"&ie=UTF-8&tl=en&total=1&idx=0&client=tw-ob&prev=input&ttsspeed=1\\\" && amixer set Master {volume} && mpg123 /tmp/tts.mp3\")' | sh 2> /dev/null",
      "restart_lumimqtt": "/etc/init.d/lumimqtt restart",
      "reboot": "/sbin/reboot"
    }
}

Usage examples

Action	Topic	Payload
Run command "blink"	lumi/<ID>/blink/set	{"color": "red"}
Run command "tts"	lumi/<ID>/tts/set	<ANYTHING>
Run command "tts_interpolate"	lumi/<ID>/tts_interpolate/set	{"text": "Hi, it is a test", "volume": 200}
Run command "restart_lumimqtt"	lumi/<ID>/restart_lumimqtt/set	<ANYTHING>
Run command "reboot"	lumi/<ID>/reboot/set	<ANYTHING>

OpenWrt installation

opkg update 
opkg install python3-pip python3-asyncio python3-evdev
pip3 install -U lumimqtt

To upgrade you can just run

pip3 install -U lumimqtt

Example run command:

lumimqtt

or (in background):

lumimqtt &

Autorun:

To run lumimqtt on start you need a file /etc/init.d/lumimqtt with the following content:

#!/bin/sh /etc/rc.common
START=98
USE_PROCD=1
start_service()
{
    procd_open_instance

    procd_set_param env LUMIMQTT_CONFIG=/etc/lumimqtt.json
    procd_set_param command lumimqtt
    procd_set_param respawn
    procd_set_param stdout 1
    procd_set_param stderr 1
    procd_close_instance
}

To install this file on the gateway you can run

wget https://raw.githubusercontent.com/openlumi/lumimqtt/main/init.d/lumimqtt -O /etc/init.d/lumimqtt
chmod +x /etc/init.d/lumimqtt
/etc/init.d/lumimqtt enable
/etc/init.d/lumimqtt start