{"id":15654007,"url":"https://github.com/alexxit/openmiio_agent","last_synced_at":"2025-04-30T22:24:45.399Z","repository":{"id":104871741,"uuid":"559439553","full_name":"AlexxIT/openmiio_agent","owner":"AlexxIT","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-12T10:35:33.000Z","size":108,"stargazers_count":30,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T20:33:44.237Z","etag":null,"topics":["golang","lua","miio","miot","mqtt","zigbee"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexxIT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-30T05:34:41.000Z","updated_at":"2025-01-07T20:46:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"d5a8cc21-3912-4809-8cff-2f5f91fa105c","html_url":"https://github.com/AlexxIT/openmiio_agent","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fopenmiio_agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fopenmiio_agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fopenmiio_agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fopenmiio_agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexxIT","download_url":"https://codeload.github.com/AlexxIT/openmiio_agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251790583,"owners_count":21644241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","lua","miio","miot","mqtt","zigbee"],"created_at":"2024-10-03T12:48:52.798Z","updated_at":"2025-04-30T22:24:45.352Z","avatar_url":"https://github.com/AlexxIT.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openmiio_agent\n\nThis project allows you to significantly extend the functionality of your gateways on the original firmware, keeping\nalmost all default functionality of the device in the Xiaomi Mi Home ecosystem.\n\n**Features**\n\n- Full support original Xiaomi firmware\n- Access to gateway's MQTT\n- miIO to MQTT for send commands and receive device updates (also without Internet)\n- ZHA and zigbee2mqtt support (on-demand mode)\n- Lua scripts for changing default gateway logic\n- BLE events without Internet\n- Fix difference for BLE specs\n- Zigbee custom firmware support\n\n| Supported gateway  | Xiaomi Multimode Gateway     | Xiaomi Multimode Gateway 2 | Aqara Hub E1 |\n|--------------------|------------------------------|----------------------------|--------------|\n| Supported models   | `ZNDMWG03LM`\u003cbr\u003e`ZNDMWG02LM` | `DMWG03LM`\u003cbr\u003e`ZNDMWG04LM` | `ZHWG16LM`   |\n| Mi Home Zigbee     | yes                          | yes                        | yes          |\n| Mi Home BLE+Mesh   | yes                          | yes                        | no           |\n| HomeKit for Zigbee | yes                          | no                         | yes          | \n| Beeper and Alarm   | yes                          | no                         | no           |\n| Buggy hardware     | yes                          | no                         | no           |\n| Zigbee range       | high                         | unknown                    | medium       |\n\n**Comments**\n\n- For the first Multimode the Chinese and Euro model are supported, but it is recommended to use the Chinese Cloud\n  because of the supported subdevice list\n- For the Aqara Hub only Chinese model supported because only it works with Mi Home Cloud\n- First Multimode support HomeKit, but only for Zigbee devices\n- Only first Multimode has Alarm function for Mi Home ecosystem and Beeper\n- Only first Multimode has buggy hardware, you may have minor stability issues with Zigbee, BLE, Mesh devices and\n  Gateway Wi-Fi connection\n\n## Install\n\nThis binary embed into [Home Assistant](https://www.home-assistant.io/) custom\nintegration [Xiaomi Gateway 3](https://github.com/AlexxIT/XiaomiGateway3). Integration can automatically:\n\n- get the gateway's token from the MiHome cloud\n- open Telnet on gateway\n- download and run latest `openmiio_agent` binary\n- run the binary after gateway restarts\n\nBut you can download binary manually from [latest release](https://github.com/AlexxIT/openmiio_agent/releases/latest).\n\n- **MIPS** for Xiaomi Multimode Gateway\n- **ARM** for Xiaomi Multimode Gateway 2 and Aqara Hub E1\n\n## Run\n\nAll agruments are optional:\n\n`/data/openmiio_agent miio central mqtt cache z3 --zigbee.tcp=8888 --log.level=trace`\n\n- `miio` - enable miIO module for control all internal gateway communications instead of `miio_agent`\n- `central` - enable central module for catch BLE/Mesh local updates\n- `mqtt` - enable MQTT module and run gateways MQTT on public `1883` port\n- `cache` - enable cache module for process BLE sensors without Integrnet\n- `z3` - enable publish Z3GatewayHost stdout to MQTT (for reading zigbee stats)\n- `--log.level=trace` - change log level, default `warn`\n- `--zigbee.tcp=8888` - enable ser2net feature for zigbee chip\n\n## miIO\n\n- These are the same commands used in [miio proto](https://github.com/rytilahti/python-miio)\n- You can add optional `id` key\n- Some methods require empty `params`\n- Some methods don't work (ex `miIO.info`)\n\n```\nmosquitto_sub -t miio/command_ack\nmosquitto_pub -t miio/command -m '{\"method\":\"get_common_lib_version\",\"params\":[]}'\n```\n\n## ZHA and zigbee2mqtt\n\nSupport on-demand access to zigbee chip via TCP for [ZHA](https://www.home-assistant.io/integrations/zha/) and [zigbee2mqtt](https://www.zigbee2mqtt.io/) projects.\n\nBy 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.\n\n**Important:** Zigbee devices can't work simultaniously with MiHome and ZHA/zigbee2mqtt.\n\n**All of your thanks for supporting the EZSP in zigbee2mqtt can say to [@kirovilya](https://github.com/kirovilya).**\n\n| Feature                                 | ZHA       | zigbee2mqtt                                                             |\n|-----------------------------------------|-----------|-------------------------------------------------------------------------|\n| Support EFR32 EZSP (gateway's chip)     | excellent | [experimental](https://www.zigbee2mqtt.io/guide/adapters/#experimental) |\n| Support EZSPv7 (original chip firmware) | excellent | [experimental](https://github.com/Koenkk/zigbee-herdsman/pull/598)      |\n| Support EZSPv8 (custom chip firmware)   | excellent | [experimental](https://github.com/Koenkk/zigbee-herdsman/issues/319)    |\n| Keep MiHome network settings            | yes       | no                                                                      |\n\nWhen 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.\n\nWhen you return from ZHA to MiHome mode, your old MiHome devices will continue to work. But, new ZHA devices will not appear.\n\nzigbee2mqtt will replace the chip settings with its own. You will lose all your paired devices.\n\nWhen returning from zigbee2mqtt mode to MiHome mode, you need to reset the gateway to factory settings.\n\n## Lua\n\nWith lua scripts you can:\n\n- Read all miIO requests and responses between gateway apps and cloud\n- Change or prevent this requests and responses\n- Make your own miIO commands, like `cli` command in example below\n- Subscribe and publish to MQTT\n- Read and write files\n- Execute any bash scripts\n\nImportant\n\n- If you write a function, it will be processed\n- The error handler are disabled, if there is an error in the script - the whole application will crash\n- Learn lua [here](https://programming-idioms.org/cheatsheet/Python/Lua) and [here](https://www.lua.org/manual/5.1/)\n\n**Code**\n\n- `function miio_request(from, method, req)`\n    - `from` -\n      int, [app ID](https://github.com/AlexxIT/openmiio_agent/blob/1eadf485bfff62520887b0767fd26a936d6760f0/internal/miio/miio.go#L11-L19)\n    - `method` - string, miIO method\n    - `req` - string, raw JSON request (use `json.decode(req)` for parsing)\n    - `return` nothing - no change to the request\n    - `return` string - replace request\n    - `return nil` - prevent request\n- `function miio_response(to, method, req, res)`\n    - `to` - int, app ID (the original source of the request)\n    - `method` - string, miIO method from request (not response)\n    - `req` - string, raw JSON request\n    - `res` - string, raw JSON response\n    - `return` nothing - no change to the response\n    - `return` string - replace response\n    - `return nil` - prevent response\n- `function mosquitto_sub(topic, payload)`\n- `miio_send(to, msg)` - raw JSON to app ID\n- `mosquitto_pub(topic, payload, retain)`\n\nPlace file `openmiio_agent.lua` next to the binary:\n\n```lua\njson = require(\"json\")\n\nfunction miio_request(from, method, req)\n    -- prevent beeper for Motion Sensor 5 sec hack\n    if from == 4 and method == \"local.status\" and req:find(\"dev_query_connect\") then\n        return nil\n    end\n\n    if from \u003c= 0 then\n        if method == \"cli\" then\n            req = json.decode(req)\n            os.execute(\"sh -c '\" .. req.params[1] .. \"'\")\n            local res = { id = req.id, result = { \"ok\" } }\n            miio_send(from, json.encode(res))\n            return nil -- prevent request to local\n        end\n    end\nend\n\nfunction miio_response(to, method, req, res)\n    if to == 4 then\n        if method == \"_sync.zigbee3_bind\" then\n            req = json.decode(req)\n            res = { id = req.id, result = { code = 0, message = \"ok\" } }\n            return json.encode(res)\n        end\n    end\nend\n```\n\n## MQTT\n\n| Topic                     | App            | Mode      | Description                              |\n|---------------------------|----------------|-----------|------------------------------------------|\n| `gw/IEEE/commands`        | Z3GatewayHost  | subscribe | commands to zigbee stack (Silabs format) |\n| `gw/IEEE/executed`        | Z3GatewayHost  | publish   | executed commands                        |\n| `gw/IEEE/heartbeat`       | Z3GatewayHost  | publish   | zigbee network alive messages (1 min)    |\n| `gw/IEEE/MessageReceived` | Z3GatewayHost  | publish   | raw messages from zigbee stack           |\n| `miio/command`            | openmiio_agent | subscribe | commands to gateway (miIO format)        |\n| `miio/command_ack`        | openmiio_agent | publish   | response on commands                     |\n| `miio/report`             | openmiio_agent | publish   | updates from gateway to cloud            |\n| `miio/report_ack`         | openmiio_agent | publish   | response from cloud to gateway           |\n| `central/report`          | openmiio_agent | publish   | updates from bluetooth to central app    |\n| `openmiio/log`            | openmiio_agent | publish   | openmiio_agent logs in JSON format       |\n| `openmiio/report`         | openmiio_agent | publish   | openmiio_agent alive messages (30 sec)   |\n| `broker/ping`             | zigbee_agent   | publish   | zigbee_agent alive message               |\n| `zigbee/recv`             | zigbee_agent   | subscribe | commands to zigbee stack (Lumi format)   |\n| `zigbee/send`             | zigbee_agent   | publish   | response from zigbee stack               | \n\n### openmiio/report\n\n```json5\n{\n  \"gateway\": {\n    \"model\": \"lumi.gateway.mgl03\",\n    \"firmware\": \"1.5.4_0090\",\n  },\n  \"miio\": {\n    \"cloud_state\": \"cloud_connected\",\n    \"cloud_starts\": 123,    // online status attempts\n    \"cloud_uptime\": \"10s\"   // online status duration (from app start)\n  },\n  \"openmiio\": {\n    \"version\": \"1.1.1\",\n    \"uptime\": \"10s\"         // openmiio run duration\n  },\n  \"serial\": {\n    \"bluetooth_rx\": 12345,  // number of bytes read from UART\n    \"bluetooth_tx\": 12345,  // number of bytes write to UART\n    \"bluetooth_oe\": 123,    // number of errors\n    \"zigbee_rx\": 12345,\n    \"zigbee_tx\": 12345,\n    \"zigbee_oe\": 123\n  },\n  \"zigbee\": {\n    \"tcp_remote\": \"192.168.1.123:12345\",\n    \"tcp_starts\": 123,      // TCP connection attempts\n    \"tcp_uptime\": \"10s\",    // TCP connection duration\n    \"z3_starts\": 123,       // Z3 app run attempts\n    \"z3_uptime\": \"10s\"      // Z3 app run duration\n  }\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexxit%2Fopenmiio_agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexxit%2Fopenmiio_agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexxit%2Fopenmiio_agent/lists"}