/ioBroker.xiaomi-gateway3

Adapter for Xiaomi Gateway 3 integration

Primary LanguageJavaScriptMIT LicenseMIT

Logo

ioBroker.xiaomi-gateway3

NPM version Downloads Number of Installations (latest)

Test and Release

Xiaomi-gateway3 ioBroker adapter

This adapter allow ioBroker to communicate with Xiaomi Gateway 3 and use it to control Xiaomi devices. Adapter communicates with gateway over MQTT protocol (it connects to build-in MQTT broker). However you have to pair your gateway and devices by Mi Home (Cloud).

Early version

Adapter is in development stage, for now. But already has ready to go functionality.

For successful adapter development it needs community help mostly in tests adapter and devices.

Thanks

Big part of code is based on and rewrote from AlexxIT project XiaomiGateway3

How you can help?

First of all, you can simply install adapter, use it and report of any issues.

Besides, if you have a lot of different devices you can help to improve they support by enable option Debug output (to state) (see below) and give me debug output after few days collecting debug data.

Hardware and limits

Adapter supports Xiaomi Gateway 3 (ZNDMWG03LM and ZNDMWG02LM) running on original firmware these versions:

  • v1.5.0_0026 (developed on it)
  • v1.5.0_0102 (similar to 1.5.0_0026, but not tested)

You can flash gateway with custom or stock firmware these versions: wiki.

!!Attantion: Firmware versions lower than 1.4.7_0000 adapter not support and will not. Support of versions lower than v1.5.0_0026 not guaranteed.

Supported devices

  • Tested
  • Not tested

Zigbee devices

  • Aqara Bulb (ZNLDP12LM)
  • Aqara Button (WXKG11LM)
  • Aqara Cube (MFKZQ01LM)
  • Aqara Curtain (ZNCLDJ11LM)
  • Aqara Curtain B1 (ZNCLDJ12LM)
  • Aqara Door Lock S1 (ZNMS11LM)
  • Aqara Door Lock S2 (ZNMS12LM)
  • Aqara Door Lock S2 Pro (ZNMS12LM)
  • Aqara Door Sensor (MCCGQ11LM)
  • Aqara Double Wall Button (WXKG02LM)
  • Aqara Double Wall Button D1 (WXKG07LM)
  • Aqara Double Wall Switch (QBKG03LM,QBKG12LM)
  • Aqara Double Wall Switch D1 (QBKG22LM,QBKG24LM)
  • Aqara Double Wall Switch E1 (QBKG39LM,QBKG41LM)
  • Aqara Double Wall Switch H1 (WS-EUK02)
  • Aqara Double Wall Switch US (WS-USC04)
  • Aqara Motion Sensor (RTCGQ11LM)
  • Aqara Opple Four Button (WXCJKG12LM)
  • Aqara Opple MX480 (XDD13LM)
  • Aqara Opple MX650 (XDD12LM)
  • Aqara Opple Six Button (WXCJKG13LM)
  • Aqara Opple Two Button (WXCJKG11LM)
  • Aqara Plug (SP-EUC01)
  • Aqara Precision Motion Sensor (RTCGQ13LM)
  • Aqara Relay (LLKZMK11LM)
  • Aqara Relay T1 (DLKZMK11LM,SSM-U01,SSM-U02)
  • Aqara Roller Shade (ZNGZDJ11LM)
  • Aqara Roller Shade E1 (ZNJLBL01LM)
  • Aqara Shake Button (WXKG12LM)
  • Aqara Single Wall Button (WXKG03LM)
  • Aqara Single Wall Button D1 (WXKG06LM)
  • Aqara Single Wall Switch (QBKG04LM,QBKG11LM)
  • Aqara Single Wall Switch D1 (QBKG21LM,QBKG23LM)
  • Aqara Single Wall Switch E1 (QBKG38LM,QBKG40LM)
  • Aqara Single Wall Switch H1 (WS-EUK01)
  • Aqara Socket (QBCZ11LM)
  • Aqara TH Sensor (WSDCGQ11LM,WSDCGQ12LM)
  • Aqara TVOC Air Quality Monitor (VOCKQJK11LM)
  • Aqara Thermostat S2 (KTWKQ03ES)
  • Aqara Triple Wall Switch D1 (QBKG25LM,QBKG26LM)
  • Aqara Vibration Sensor (DJT11LM)
  • Aqara Water Leak Sensor (SJCGQ11LM)
  • Honeywell Gas Sensor (JTQJ-BF-01LM/BW)
  • Honeywell Smoke Sensor (JTYJ-GD-01LM/BW)
  • IKEA Bulb E14 (LED1649C5)
  • IKEA Bulb E14 400 lm (LED1536G5)
  • IKEA Bulb E27 1000 lm (LED1623G12)
  • IKEA Bulb E27 950 lm (LED1546G12)
  • IKEA Bulb E27 980 lm (LED1545G12)
  • IKEA Bulb GU10 400 lm (LED1537R6,LED1650R5)
  • Xiaomi Button (WXKG01LM)
  • Xiaomi Door Sensor (MCCGQ01LM)
  • Xiaomi Light Sensor (GZCGQ01LM)
  • Xiaomi Motion Sensor (RTCGQ01LM)
  • Xiaomi Plug (ZNCZ02LM)
  • Xiaomi Plug EU (ZNCZ04LM)
  • Xiaomi Plug TW (ZNCZ03LM)
  • Xiaomi Plug US (ZNCZ12LM)
  • Xiaomi TH Sensor (WSDCGQ01LM)

BLE devices

  • Aqara Door Lock N100 (ZNMS16LM)
  • Aqara Door Lock N200 (ZNMS17LM)
  • Honeywell Smoke Alarm (JTYJ-GD-03MI)
  • Xiaomi Alarm Clock (CGD1)
  • Xiaomi Door Lock (MJZNMS02LM,XMZNMST02YD)
  • Xiaomi Door Sensor 2 (MCCGQ02HL)
  • Xiaomi Flower Care (HHCCJCY01)
  • Xiaomi Flower Pot (HHCCPOT002)
  • Xiaomi Magic Cube (XMMF01JQD)
  • Xiaomi Mosquito Repellent (WX08ZM)
  • Xiaomi Motion Sensor 2 (RTCGQ02LM)
  • Xiaomi Night Light 2 (MJYD02YL-A)
  • Xiaomi Qingping Door Sensor (CGH1)
  • Xiaomi Qingping Motion Sensor (CGPR1)
  • Xiaomi Qingping TH Lite (CGDK2)
  • Xiaomi Qingping TH Sensor (CGG1)
  • Xiaomi Safe Box (BGX-5/X1-3001)
  • Xiaomi TH Clock (LYWSD02MMC)
  • Xiaomi TH Sensor (LYWSDCGQ/01ZM)
  • Xiaomi TH Sensor 2 (LYWSD03MMC)
  • Xiaomi Toothbrush T500 (MES601)
  • Xiaomi Water Leak Sensor (SJWS01LM)
  • Xiaomi ZenMeasure Clock (MHO-C303)
  • Xiaomi ZenMeasure TH (MHO-C401)
  • Yeelight Button S1 (YLAI003)

Note: BLE devices may not have states at first time after pairing because i don't know specs for devices and didn't define properties for all devices for now. States will added when device will update correponding propertie. I hope I will fix this over time with your help.

Some states description

Button long press

For button devices you can see combination of two states (like) long_press and long_timeout. How dos it work? Buttons which support long press sends message on press and on relese event. Some times can happed situation when button not sent message on release button. In this case timeout should help to "release" state.

By default timeout state value unset and long_press will be released in 1 second after start holding button even if you still hold it. If you set long_timeout to -1 timeout will be ignored at all and state will be "released" only by message from button.

In most cases reasonable to set timeout to some small value like 4 or 5 seconds.

Occupancy and Occupancy timeout

RTCGQ11LM and other motion sensors have delay (timeout) after motion detect from 5 to 60 second (depends on versions and modifications). This means that new motion can't be detected during this period (technicly sensor does not send message).

occupancy become true when sensor detect motion and stay true.

Goal of occupancy_timeout is set occupancy to false when sensor can send message again. By default occupancy_timeout is not set and occupancy turn back to false after 60 seconds. If your sensor have different delay it's better to set occupancy_timeout to that delay value.

If you want to back to false right after motion detected you can set occupancy_timeout to 1 second.

Configuration

To connect a gateway you need get IP and TOKEN of gateway. You can do this manually or from cloud.

Also you have to chose telnet open command (in most cases option #2). You can test connection and telnet by buttons.

Ping here not actually ping. It is more check of device availability.


You have several options to configure adapter and gatewey.

Adapter settings

  • Collect statistic
    Adapter collect statistic about zigbee devices messages: how much received, how much missed and etc. Statistic stored to state at each device and can be viewed in 'tab' page (from sidebar menu).
    Note: Adapter do reset statistic on restart.

  • Debug output (to state)
    Adapter will doing output some debug info into state for each device.

Basic Gateway3 settings

  • Telnet enabled
    Enabled by default and have to stay enabled. Here just for info.

  • Public MQTT enabled
    Enabled by default and have to stay enabled. Here just for info.

  • Lock firmware
    Set true (or false) to disable (or enable) possibility to upgrade gateway firmware.

  • Disable buzzer
    Set true to disable annoying buzzer signals or false to enable all signals.

Advanced Gateway3 settings

  • Storage in memory (Beta)
    Move devices DB files to memory. This can improve work zigbee and bluetooth devices. But can occur losing some data. Use on your own risk.

Logging settings

Note: To see debug messages in ioBroker log you have to set debug log level for adapter under Instances page (toggle expert mode into enabled)

  • Lumi MQTT messages
    Enable MQTT messages debug logging of Lumi (zigbee) devices.

  • Ble MQTT messages
    Enable MQTT messages debug logging of BLE devices.

  • All the rest
    Enable debug logging all other adapter messages.

  • Cut SPAM
    Enable cutting duplicate messages. If identical error messages repeat several times they will be hidden and after 1 hour will shown total count.

Tab page

Devices


There are devices cards on devices page in which you can see some info about device, current states values and can control some of them.

Also you can change friendly name of device.

Note: For now this page has basic functional. It well be expanded in future.

Device config

You can define some options to configure device (and device's card) by writing configuration with yaml. Available options discribed belowe in table. You can invoke device config window (window with text input area) with Config point in menu.

Device configuration options

Field Type Description
cardStates Dictionary This dictionary hold options for states in device's card
cardStates.hide List List of states (states ids) which have to be hidden from device's card

Statistic

  • Statistics are not loaded by default. You have to use button RELOAD to update statistic on page.

  • Also you can clear statistic with button CLEAR. This does not clean statistic actually as it is. You just clear states which hold statistic. This can be useful in case adapter restart because ioBroker states don't clear on restart.

Attantion: You should to keep in mind this is not really statistic of zigbee messages between gateway and device (zigbee protocol statistic). This is statistic of messages which get adapter. What does it means? No differences for adapter is gateway don't get message from device or adapter himself don't get message from gateway (by MQTT). And if by any cases (Wi-Fi connection problem, for example) adapter don't get messages from gateway it interpritate this messages as missed, but actualy zigbee is ok.

Changelog

0.3.6 (2022-06-14)

  • Fixes and improvements

0.3.5 (2022-05-08)

  • Added configuration for devices
  • Added cutting SPAM messages at log
  • Remove unnecessary Debug log option
  • Fixes and improvements

0.3.4 (2022-02-10)

  • Fix issue getting devices from cloud and switch to RC4
  • Add devices page
  • Other fixes and improvements

0.3.3 (2022-01-30)

  • Fix lumi temperature and voltage

0.3.2 (2022-01-30)

  • Bug fixes and code improvements
  • Add curtain and buttons support
  • Update README

0.3.1 (2022-01-17)

  • Bug fixes and code improvements
  • Improved support firmware 1.5.1_0032 and some devices

0.3.0 (2021-12-10)

  • Improved adapter logging

0.2.0 (2021-12-07)

  • Added states classes and rewrote code with using them
  • Added tab-page of adapter
  • Added zigbee (lumi) devices statistic
  • A lot of code improvements

0.1.0 (2021-11-09)

  • (Evgenii Abramov) Added support for BLE devices (needed tests)
  • (Evgenii Abramov) Improvements for zigbee and BLE support
  • (Evgenii Abramov) Added output for debug purpose
  • (Evgenii Abramov) A lot of code improvements

0.0.1-alpha.0 (2021-10-13)

  • (Evgenii Abramov) Initial release

License

MIT License

Copyright (c) 2022 Evgenii Abramov john.abramov@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.