ioBroker.xiaomi-gateway3

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

BLE devices

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

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.

Homemade-Disaster/ioBroker.xiaomi-gateway3