diff --git a/bundles/org.openhab.binding.miio/README.base.md b/bundles/org.openhab.binding.miio/README.base.md
index 7f2fb4192..538bf9690 100644
--- a/bundles/org.openhab.binding.miio/README.base.md
+++ b/bundles/org.openhab.binding.miio/README.base.md
@@ -74,13 +74,13 @@ However, for devices that are unsupported, you may override the value and try to
### Example Thing file
-`Thing miio:basic:light "My Light" [ host="192.168.x.x", token="put here your token", deviceId="0326xxxx" ]`
+`Thing miio:basic:light "My Light" [ host="192.168.x.x", token="put here your token", deviceId="0326xxxx", model="philips.light.bulb" ]`
-or in case of unknown models include the model information e.g.:
+or in case of unknown models include the model information of a similar device that is supported:
-`Thing miio:vacuum:s50 "vacuum" @ "livingroom" [ host="192.168.15.20", token="xxxxxxx", deviceId=“0470DDAA”, model="roborock.vacuum.s5" ]`
+`Thing miio:vacuum:s50 "vacuum" @ "livingroom" [ host="192.168.15.20", token="xxxxxxx", deviceId=“0470DDAA”, model="roborock.vacuum.s4" ]`
-## Mi IO Devices
+# Mi IO Devices
!!!devices
@@ -93,6 +93,7 @@ The binding allows to try/test if your new device is working with database files
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.
@@ -100,6 +101,7 @@ Normally the modelId is populated with the model of your device, however in this
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).
@@ -115,6 +117,43 @@ The conf/misc/miio (e.g. in Linux `/opt/openhab2/conf/misc/miio/`) is scanned fo
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.
+# FAQ.. what to do in case of problems
+
+If your device is not getting online:
+
+_Are you using text config?_
+Make sure you define all the fields as per above example.
+Or, better, try to get it going first without text config.
+
+_The token is wrong_
+The most common cause of non responding devices is a wrong token.
+When you reset, or change wifi or update firmware, and possibly other cases as well, the token may change. You'll need to get a refreshed token.
+
+_My token is coming from the cloud... how can it be wrong?_
+Is not very likely but still can happen._
+This can happen e.g. if your device is defined on multiple country servers.
+The binding may pull the token from the wrong country server.
+First try to get the token from all country servers by leave the county setting empty.
+If that does not solve it, you define only the country that the device is on in the binding config page (where the cloud userid/pwd is entered) this should pull the right token.
+
+_You have the same device added multiple times._
+The communication each time send a sequential number.
+If the device is twice defined, the numbers received by the device are no longer sequential and it will stop responding for some time.
+
+_The connection is not too good, so you have timeouts etc._
+Position your device closer to wifi / check in the mihome app if the wifi strength is good enough.
+Alternatively as described above, double check for multiple connections for single device.
+
+_Your device is on a different subnet?_
+This is in most cases not working.
+Firmware of the device don't accept commands coming from other subnets.
+
+_Cloud connectivity is not working_
+The most common problem is a wrong userId/password. Try to fix your userId/password.
+If it still fails, you're bit out of luck. You may try to restart OpenHAB (not just the binding) to clean the cookies.
+As the cloud logon process is still little understood, your only luck might be to enable trace logging and see if you can translate the Chinese error code that it returns.
+
+
# Channels
Depending on the device, different channels are available.
@@ -199,10 +238,10 @@ Additionally depending on the capabilities of your robot vacuum other channels m
!!!itemFileExamples
-###(Country Servers)
+### Country Servers
Known country Servers: cn, de, i2, ru, sg, us
-Mapping of countries in mihome app to server
+Mapping of countries in mihome app to server:
| Country | Country Code | Server |
|--------------------------|--------------|--------|
diff --git a/bundles/org.openhab.binding.miio/README.md b/bundles/org.openhab.binding.miio/README.md
index 1d9022944..d66b6a114 100644
--- a/bundles/org.openhab.binding.miio/README.md
+++ b/bundles/org.openhab.binding.miio/README.md
@@ -74,13 +74,13 @@ However, for devices that are unsupported, you may override the value and try to
### Example Thing file
-`Thing miio:basic:light "My Light" [ host="192.168.x.x", token="put here your token", deviceId="0326xxxx" ]`
+`Thing miio:basic:light "My Light" [ host="192.168.x.x", token="put here your token", deviceId="0326xxxx", model="philips.light.bulb" ]`
-or in case of unknown models include the model information e.g.:
+or in case of unknown models include the model information of a similar device that is supported:
-`Thing miio:vacuum:s50 "vacuum" @ "livingroom" [ host="192.168.15.20", token="xxxxxxx", deviceId=“0470DDAA”, model="roborock.vacuum.s5" ]`
+`Thing miio:vacuum:s50 "vacuum" @ "livingroom" [ host="192.168.15.20", token="xxxxxxx", deviceId=“0470DDAA”, model="roborock.vacuum.s4" ]`
-## Mi IO Devices
+# Mi IO Devices
| Device | ThingType | Device Model | Supported | Remark |
|------------------------------|------------------|------------------------|-----------|------------|
@@ -327,6 +327,7 @@ The binding allows to try/test if your new device is working with database files
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.
@@ -334,6 +335,7 @@ Normally the modelId is populated with the model of your device, however in this
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).
@@ -349,6 +351,43 @@ The conf/misc/miio (e.g. in Linux `/opt/openhab2/conf/misc/miio/`) is scanned fo
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.
+# FAQ.. what to do in case of problems
+
+If your device is not getting online:
+
+_Are you using text config?_
+Make sure you define all the fields as per above example.
+Or, better, try to get it going first without text config.
+
+_The token is wrong_
+The most common cause of non responding devices is a wrong token.
+When you reset, or change wifi or update firmware, and possibly other cases as well, the token may change. You'll need to get a refreshed token.
+
+_My token is coming from the cloud... how can it be wrong?_
+Is not very likely but still can happen._
+This can happen e.g. if your device is defined on multiple country servers.
+The binding may pull the token from the wrong country server.
+First try to get the token from all country servers by leave the county setting empty.
+If that does not solve it, you define only the country that the device is on in the binding config page (where the cloud userid/pwd is entered) this should pull the right token.
+
+_You have the same device added multiple times._
+The communication each time send a sequential number.
+If the device is twice defined, the numbers received by the device are no longer sequential and it will stop responding for some time.
+
+_The connection is not too good, so you have timeouts etc._
+Position your device closer to wifi / check in the mihome app if the wifi strength is good enough.
+Alternatively as described above, double check for multiple connections for single device.
+
+_Your device is on a different subnet?_
+This is in most cases not working.
+Firmware of the device don't accept commands coming from other subnets.
+
+_Cloud connectivity is not working_
+The most common problem is a wrong userId/password. Try to fix your userId/password.
+If it still fails, you're bit out of luck. You may try to restart OpenHAB (not just the binding) to clean the cookies.
+As the cloud logon process is still little understood, your only luck might be to enable trace logging and see if you can translate the Chinese error code that it returns.
+
+
# Channels
Depending on the device, different channels are available.
@@ -6381,10 +6420,10 @@ Number usedhours "Run Time" (G_heater) {channel="miio:basic:heater:usedhours"}
-###(Country Servers)
+### Country Servers
Known country Servers: cn, de, i2, ru, sg, us
-Mapping of countries in mihome app to server
+Mapping of countries in mihome app to server:
| Country | Country Code | Server |
|--------------------------|--------------|--------|