aa98737e9f
* [miio] Improved unsupported handler that build experimental support New unsupported handler that tries to find channels for unsupported devices and creates experimental database file for it. * [miio] logger fixes Signed-off-by: Marcel Verpaalen <marcel@verpaalen.com>
13 KiB
Xiaomi Mi IO Binding
This binding is used to control Xiaomi products implementing the Mi IO protocol. This is a set of wifi devices from Xiaomi that are part of the Mi Ecosystem which is branded as MiJia.
Supported Things
The following things types are available:
| ThingType | Description |
|---|---|
| miio:generic | Generic type for discovered devices. Once the token is available and the device model is determined, this ThingType will automatically change to the appropriate ThingType |
| miio:vacuum | For Xiaomi Robot Vacuum products |
| miio:basic | For several basic devices like yeelights, airpurifiers. Channels and commands are determined by database configuration |
| miio:unsupported | For experimenting with other devices which use the Mi IO protocol |
Discovery
The binding has 2 methods for discovering devices. Depending on your network setup and the device model, your device may be discovered by one or both methods. If both methods discover your device, 2 discovery results may be in your inbox for the same device.
The mDNS discovery method will discover your device type, but will not discover a (required) token. The basic discovery will not discovery the type, but will discover a token for models that support it. Accept only one of the 2 discovery results, the alternate one can further be ignored.
Tokens
The binding needs a token from the Xiaomi Mi Device in order to be able to control it. The binding can retrieve the needed tokens from the Xiaomi cloud. Go to the binding config page and enter your cloud username and password. The server(s) to which your devices are connected need to be entered as well. Use the one of the regional servers: ru,us,tw,sg,cn,de. Multiple servers can be separated with comma, or leave blank to test all known servers.
Tokens without cloud access
Some devices provide the token upon discovery. This may depends on the firmware version. If the device does not discover your token, it needs to be retrieved from the Mi Home app.
The easiest way to obtain tokens is to browse through log files of the Mi Home app version 5.4.49 for Android. It seems that version was released with debug messages turned on by mistake. An APK file with the old version can be easily found using one of the popular web search engines. After downgrading use a file browser to navigate to directory SmartHome/logs/plug_DeviceManager, then open the most recent file and search for the token. When finished, use Google Play to get the most recent version back.
For iPhone, use an un-encrypted iTunes-Backup and unpack it and use a sqlite tool to view the files in it: Then search in "RAW, com.xiaomi.home," for "USERID_mihome.sqlite" and look for the 32-digit-token or 96 digit encrypted token.
Note. The Xiaomi devices change the token when inclusion is done. Hence if you get your token after reset and than include it with the Mi Home app, the token will change.
Binding Configuration
No binding configuration is required. However to enable cloud functionality enter your Xiaomi username, password and server(s). After succesfull Xiaomi cloud login, the binding will use the connection to retrieve the required device tokens from the cloud. For Xiaomi vacuums the map can be visualized in openHAB using the cloud connection.
Thing Configuration
Each Xiaomi device (thing) needs the IP address and token configured to be able to communicate. See discovery for details. Optional configuration is the refresh interval and the deviceID. Note that the deviceID is automatically retrieved when it is left blank. The configuration for model is automatically retrieved from the device in normal operation. However, for devices that are unsupported, you may override the value and try to use a model string from a similar device to experimentally use your device with the binding.
| Parameter | Type | Required | Description |
|---|---|---|---|
| host | text | true | Device IP address |
| token | text | true | Token for communication (in Hex) |
| deviceId | text | true | Device ID number for communication (in Hex) |
| model | text | false | Device model string, used to determine the subtype |
| refreshInterval | integer | false | Refresh interval for refreshing the data in seconds. (0=disabled) |
| timeout | integer | false | Timeout time in milliseconds |
Example Thing file
Thing miio:basic:light "My Light" [ host="192.168.x.x", token="put here your token", deviceId="0326xxxx" ]
or in case of unknown models include the model information e.g.:
Thing miio:vacuum:s50 "vacuum" @ "livingroom" [ host="192.168.15.20", token="xxxxxxx", deviceId=“0470DDAA”, model="roborock.vacuum.s5" ]
Mi IO Devices
!!!devices
Advanced: Unsupported devices
Newer devices may not yet be supported. However, many devices share large similarities with existing devices. The binding allows to try/test if your new device is working with database files of older devices as well.
There are 2 ways to get unsupported devices working, by overriding the model with the model of a supported item or by test all known properties to see which are supported by your device.
Substitute model for unsupported devices
Replace the model with the model which is already supported. For this, first remove your unsupported thing. Manually add a miio:basic thing. Besides the regular configuration (like ip address, token) the modelId needs to be provided. Normally the modelId is populated with the model of your device, however in this case, use the modelId of a similar device. Look at the openHAB forum, or the openHAB GitHub repository for the modelId of similar devices.
Supported property test
The unsupported device has a test channel with switch. When switching on, all known properties are tested, this may take few minutes. A test report will be shown in the log and is saved in the userdata/miio folder. If supported properties are found, an experimental database file is saved to the conf/misc/miio folder (see below chapter). The thing will go offline and will come back online as basic device, supporting the found channels. The database file may need to be modified to display the right channel names. After validation, please share the logfile and json files on the openHAB forum or the openHAB GitHub to build future support for this model.
Advanced: adding local database files to support new devices
Things using the basic handler (miio:basic things) are driven by json 'database' files.
This instructs the binding which channels to create, which properties and actions are associated with the channels etc.
The conf/misc/miio (e.g. in Linux /opt/openhab2/conf/misc/miio/) is scanned for database files and will be used for your devices.
Note that local database files take preference over build-in ones, hence if a json file is local and in the database the local file will be used.
For format, please check the current database files in openHAB GitHub.
Channels
Depending on the device, different channels are available.
All devices have available the following channels (marked as advanced) besides the device specific channels
| Channel | Type | Description |
|---|---|---|
| network#ssid | String | Network SSID |
| network#bssid | String | Network BSSID |
| network#rssi | Number | Network RSSI |
| network#life | Number | Network Life |
| actions#commands | String | send commands. see below |
note: the ADVANCED actions#commands channel can be used to send commands that are not automated via the binding. This is available for all devices
e.g. smarthome:send actionCommand 'upd_timer["1498595904821", "on"]' would enable a pre-configured timer. See https://github.com/marcelrv/XiaomiRobotVacuumProtocol for all known available commands.
!!!channelList
Example item file Rockrobo vacuum
Group gVac "Xiaomi Robot Vacuum" <fan>
Group gVacStat "Status Details" <status> (gVac)
Group gVacCons "Consumables Usage" <line-increase> (gVac)
Group gVacDND "Do Not Disturb Settings" <moon> (gVac)
Group gVacHist "Cleaning History" <calendar> (gVac)
Group gVacLast "Last Cleaning Details" <calendar> (gVac)
String actionControl "Vacuum Control" {channel="miio:vacuum:034F0E45:actions#control" }
String actionCommand "Vacuum Command" {channel="miio:vacuum:034F0E45:actions#commands" }
Number statusBat "Battery Level [%1.0f%%]" <battery> (gVac,gVacStat) {channel="miio:vacuum:034F0E45:status#battery" }
Number statusArea "Cleaned Area [%1.0fm²]" <zoom> (gVac,gVacStat) {channel="miio:vacuum:034F0E45:status#clean_area" }
Number statusTime "Cleaning Time [%1.0f']" <clock> (gVac,gVacStat) {channel="miio:vacuum:034F0E45:status#clean_time" }
String statusError "Error [%s]" <error> (gVac,gVacStat) {channel="miio:vacuum:034F0E45:status#error_code" }
Number statusFanPow "Fan Power [%1.0f%%]" <signal> (gVacStat) {channel="miio:vacuum:034F0E45:status#fan_power" }
Number statusClean "In Cleaning Status [%1.0f]" <switch> (gVacStat) {channel="miio:vacuum:034F0E45:status#in_cleaning" }
Switch statusDND "DND Activated" (gVacStat) {channel="miio:vacuum:034F0E45:status#dnd_enabled" }
Number statusStatus "Status [%1.0f]" <status> (gVacStat) {channel="miio:vacuum:034F0E45:status#state"}
Number consumableMain "Main Brush [%1.0f]" (gVacCons) {channel="miio:vacuum:034F0E45:consumables#main_brush_time"}
Number consumableSide "Side Brush [%1.0f]" (gVacCons) {channel="miio:vacuum:034F0E45:consumables#side_brush_time"}
Number consumableFilter "Filter Time[%1.0f]" (gVacCons) {channel="miio:vacuum:034F0E45:consumables#filter_time" }
Number consumableSensor "Sensor [%1.0f]" (gVacCons) {channel="miio:vacuum:034F0E45:consumables#sensor_dirt_time"}
Switch dndFunction "DND Function" <moon> (gVacDND) {channel="miio:vacuum:034F0E45:dnd#dnd_function"}
String dndStart "DND Start Time [%s]" <clock> (gVacDND) {channel="miio:vacuum:034F0E45:dnd#dnd_start"}
String dndEnd "DND End Time [%s]" <clock-on> (gVacDND) {channel="miio:vacuum:034F0E45:dnd#dnd_end"}
Number historyArea "Total Cleaned Area [%1.0fm²]" <zoom> (gVacHist) {channel="miio:vacuum:034F0E45:history#total_clean_area"}
String historyTime "Total Clean Time [%s]" <clock> (gVacHist) {channel="miio:vacuum:034F0E45:history#total_clean_time"}
Number historyCount "Total # Cleanings [%1.0f]" <office> (gVacHist) {channel="miio:vacuum:034F0E45:history#total_clean_count"}
String lastStart "Last Cleaning Start time [%s]" <clock> (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#last_clean_start_time"}
String lastEnd "Last Cleaning End time [%s]" <clock> (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#last_clean_end_time"}
Number lastArea "Last Cleaned Area [%1.0fm²]" <zoom> (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#last_clean_area"}
Number lastTime "Last Clean Time [%1.0f']" <clock> (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#last_clean_duration"}
Number lastError "Error [%s]" <error> (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#last_clean_error" }
Switch lastCompleted "Last Cleaning Completed" (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#last_clean_finish" }
Image map "Cleaning Map" (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#map"}
Note: cleaning map is only available with cloud access.
Additionally depending on the capabilities of your robot vacuum other channels may be enabled at runtime
| Type | Channel | Description |
|---|---|---|
| Switch | status#water_box_status | Water Box Status |
| Switch | status#lock_status | Lock Status |
| Number | status#water_box_mode | Water Box Mode |
| Switch | status#water_box_carriage_status | Water Box Carriage Status |
| Switch | status#mop_forbidden_enable | Mop Forbidden |
| Number | actions#segment | Room Clean (enter room #) |
!!!itemFileExamples