Skip to content

Latest commit

 

History

History
227 lines (183 loc) · 10.2 KB

README.md

File metadata and controls

227 lines (183 loc) · 10.2 KB

openmiio_agent

This project allows you to significantly extend the functionality of your gateways on the original firmware, keeping almost all default functionality of the device in the Xiaomi Mi Home ecosystem.

Features

  • Full support original Xiaomi firmware
  • Access to gateway's MQTT
  • miIO to MQTT for send commands and receive device updates (also without Internet)
  • ZHA and zigbee2mqtt support (on-demand mode)
  • Lua scripts for changing default gateway logic
  • BLE events without Internet
  • Fix difference for BLE specs
  • Zigbee custom firmware support
Supported gateway Xiaomi Multimode Gateway Xiaomi Multimode Gateway 2 Aqara Hub E1
Supported models ZNDMWG03LM
ZNDMWG02LM
DMWG03LM
ZNDMWG04LM
ZHWG16LM
Mi Home Zigbee yes yes yes
Mi Home BLE+Mesh yes yes no
HomeKit for Zigbee yes no yes
Beeper and Alarm yes no no
Buggy hardware yes no no
Zigbee range high unknown medium

Comments

  • For the first Multimode the Chinese and Euro model are supported, but it is recommended to use the Chinese Cloud because of the supported subdevice list
  • For the Aqara Hub only Chinese model supported because only it works with Mi Home Cloud
  • First Multimode support HomeKit, but only for Zigbee devices
  • Only first Multimode has Alarm function for Mi Home ecosystem and Beeper
  • Only first Multimode has buggy hardware, you may have minor stability issues with Zigbee, BLE, Mesh devices and Gateway Wi-Fi connection

Install

This binary embed into Home Assistant custom integration Xiaomi Gateway 3. Integration can automatically:

  • get the gateway's token from the MiHome cloud
  • open Telnet on gateway
  • download and run latest openmiio_agent binary
  • run the binary after gateway restarts

But you can download binary manually from latest release.

  • MIPS for Xiaomi Multimode Gateway
  • ARM for Xiaomi Multimode Gateway 2 and Aqara Hub E1

Run

All agruments are optional:

/data/openmiio_agent miio central mqtt cache z3 --zigbee.tcp=8888 --log.level=trace

  • miio - enable miIO module for control all internal gateway communications instead of miio_agent
  • central - enable central module for catch BLE/Mesh local updates
  • mqtt - enable MQTT module and run gateways MQTT on public 1883 port
  • cache - enable cache module for process BLE sensors without Integrnet
  • z3 - enable publish Z3GatewayHost stdout to MQTT (for reading zigbee stats)
  • --log.level=trace - change log level, default warn
  • --zigbee.tcp=8888 - enable ser2net feature for zigbee chip

miIO

  • These are the same commands used in miio proto
  • You can add optional id key
  • Some methods require empty params
  • Some methods don't work (ex miIO.info)
mosquitto_sub -t miio/command_ack
mosquitto_pub -t miio/command -m '{"method":"get_common_lib_version","params":[]}'

ZHA and zigbee2mqtt

Support on-demand access to zigbee chip via TCP for ZHA and zigbee2mqtt projects.

By default, the standard gateway software will work with the zigbee chip. At the first connection to the TCP port the standard software will be stopped.

Important: Zigbee devices can't work simultaniously with MiHome and ZHA/zigbee2mqtt.

All of your thanks for supporting the EZSP in zigbee2mqtt can say to @kirovilya.

Feature ZHA zigbee2mqtt
Support EFR32 EZSP (gateway's chip) excellent experimental
Support EZSPv7 (original chip firmware) excellent experimental
Support EZSPv8 (custom chip firmware) excellent experimental
Keep MiHome network settings yes no

When using ZHA, you can switch from MiHome mode to ZHA mode at any time. You won't need to repair your devices. But may need additional reconfiguration.

When you return from ZHA to MiHome mode, your old MiHome devices will continue to work. But, new ZHA devices will not appear.

zigbee2mqtt will replace the chip settings with its own. You will lose all your paired devices.

When returning from zigbee2mqtt mode to MiHome mode, you need to reset the gateway to factory settings.

Lua

With lua scripts you can:

  • Read all miIO requests and responses between gateway apps and cloud
  • Change or prevent this requests and responses
  • Make your own miIO commands, like cli command in example below
  • Subscribe and publish to MQTT
  • Read and write files
  • Execute any bash scripts

Important

  • If you write a function, it will be processed
  • The error handler are disabled, if there is an error in the script - the whole application will crash
  • Learn lua here and here

Code

  • function miio_request(from, method, req)
    • from - int, app ID
    • method - string, miIO method
    • req - string, raw JSON request (use json.decode(req) for parsing)
    • return nothing - no change to the request
    • return string - replace request
    • return nil - prevent request
  • function miio_response(to, method, req, res)
    • to - int, app ID (the original source of the request)
    • method - string, miIO method from request (not response)
    • req - string, raw JSON request
    • res - string, raw JSON response
    • return nothing - no change to the response
    • return string - replace response
    • return nil - prevent response
  • function mosquitto_sub(topic, payload)
  • miio_send(to, msg) - raw JSON to app ID
  • mosquitto_pub(topic, payload, retain)

Place file openmiio_agent.lua next to the binary:

json = require("json")

function miio_request(from, method, req)
    -- prevent beeper for Motion Sensor 5 sec hack
    if from == 4 and method == "local.status" and req:find("dev_query_connect") then
        return nil
    end

    if from <= 0 then
        if method == "cli" then
            req = json.decode(req)
            os.execute("sh -c '" .. req.params[1] .. "'")
            local res = { id = req.id, result = { "ok" } }
            miio_send(from, json.encode(res))
            return nil -- prevent request to local
        end
    end
end

function miio_response(to, method, req, res)
    if to == 4 then
        if method == "_sync.zigbee3_bind" then
            req = json.decode(req)
            res = { id = req.id, result = { code = 0, message = "ok" } }
            return json.encode(res)
        end
    end
end

MQTT

Topic App Mode Description
gw/IEEE/commands Z3GatewayHost subscribe commands to zigbee stack (Silabs format)
gw/IEEE/executed Z3GatewayHost publish executed commands
gw/IEEE/heartbeat Z3GatewayHost publish zigbee network alive messages (1 min)
gw/IEEE/MessageReceived Z3GatewayHost publish raw messages from zigbee stack
miio/command openmiio_agent subscribe commands to gateway (miIO format)
miio/command_ack openmiio_agent publish response on commands
miio/report openmiio_agent publish updates from gateway to cloud
miio/report_ack openmiio_agent publish response from cloud to gateway
central/report openmiio_agent publish updates from bluetooth to central app
openmiio/log openmiio_agent publish openmiio_agent logs in JSON format
openmiio/report openmiio_agent publish openmiio_agent alive messages (30 sec)
broker/ping zigbee_agent publish zigbee_agent alive message
zigbee/recv zigbee_agent subscribe commands to zigbee stack (Lumi format)
zigbee/send zigbee_agent publish response from zigbee stack

openmiio/report

{
  "gateway": {
    "model": "lumi.gateway.mgl03",
    "firmware": "1.5.4_0090",
  },
  "miio": {
    "cloud_state": "cloud_connected",
    "cloud_starts": 123,    // online status attempts
    "cloud_uptime": "10s"   // online status duration (from app start)
  },
  "openmiio": {
    "version": "1.1.1",
    "uptime": "10s"         // openmiio run duration
  },
  "serial": {
    "bluetooth_rx": 12345,  // number of bytes read from UART
    "bluetooth_tx": 12345,  // number of bytes write to UART
    "bluetooth_oe": 123,    // number of errors
    "zigbee_rx": 12345,
    "zigbee_tx": 12345,
    "zigbee_oe": 123
  },
  "zigbee": {
    "tcp_remote": "192.168.1.123:12345",
    "tcp_starts": 123,      // TCP connection attempts
    "tcp_uptime": "10s",    // TCP connection duration
    "z3_starts": 123,       // Z3 app run attempts
    "z3_uptime": "10s"      // Z3 app run duration
  }
}