search

lasthead0 / ioBroker.xiaomi-gateway3

Adapter for Xiaomi Gateway 3 integration
MIT License
6 stars 4 forks source link
iobroker smarthome xiaomi xiaomi-gateway zigbee

readme

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:

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

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

Basic Gateway3 settings

Advanced Gateway3 settings

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)

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

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)

0.3.5 (2022-05-08)

0.3.4 (2022-02-10)

0.3.3 (2022-01-30)

0.3.2 (2022-01-30)

0.3.1 (2022-01-17)

0.3.0 (2021-12-10)

0.2.0 (2021-12-07)

0.1.0 (2021-11-09)

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

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.