demus/openhab-addons
1
0
Fork 0
mirror of https://github.com/openhab/openhab-addons.git synced 2025-01-10 15:11:59 +01:00
Code Issues Packages Projects Releases Wiki Activity

[miio] Update readme wrt unsupported devices (#14512)

Browse Source 
* Rename channel names to better reflect purpose
* Update readme

Signed-off-by: Marcel Verpaalen <marcel@verpaalen.com>
This commit is contained in:
Marcel 2023-05-10 20:58:44 +02:00 committed by GitHub
parent 518283de50
commit 6784d22ab9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 42 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
bundles/org.openhab.binding.miio/README.base.md
View File

@ -102,13 +102,16 @@ in case of gateway, instead of defining it as a Thing, use Bridge
`Bridge miio:gateway:lumigateway "Mi Smarter Gateway" [ host="10.10.x.x", token="put here your token", deviceId="326xxxx", model="lumi.gateway.mieu01", communication="direct", cloudServer="de" ]`
# Advanced: Unsupported devices
# Advanced: Getting unsupported devices to work with the binding
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.
There are 3 ways to get unsupported devices working:
- by overriding the model with the model of a similar supported device. E.g. this works great for roborock vacuum devices and yeelight devices). See [Substitute model for unsupported devices](#substitute-model-for-unsupported-devices)
- by switching on the `(experimental) Create channels for new/unsupported devices (MIOT protocol)` channel, this works for most newer devices. See [Create support for new devices based on online published spec database](#create-support-for-new-devices-based-on-online-published-spec-database)
- by switching on the `(experimental) Create channels / test properties for unsupported devices (legacy protocol)` channel. This works for older / legacy devices. It test all known properties to see which are supported by your device. See [Supported property test for unsupported devices](#supported-property-test-for-unsupported-devices)
## Substitute model for unsupported devices
@ -116,7 +119,18 @@ 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.
Look at the openHAB forum, or the openHAB GitHub repository or this readme for the modelId of similar devices.
## Create support for new devices based on online published spec database
The unsupported device has a `(experimental) Create channels for new/unsupported devices (MIOT protocol)` channel. When switching on, it will try to build support based on the published spec from [https://home.miot-spec.com/](https://home.miot-spec.com/).
It will test all properties are in the spec for your device, which may take few minutes.
A test report will be shown in the log and is saved in the `userdata/miio` folder with a filename `test-[your model]-[timestamp].txt`.
The 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.
If this does not happen automatically, restart the binding or restart openHAB in order to have the new database file picked up.
Please validate and feedback if all channels and actions are working, and share the logfile and json files on the openHAB forum or the openHAB GitHub to build future support for this model.
## Supported property test for unsupported devices

20
bundles/org.openhab.binding.miio/README.md
View File

@ -102,13 +102,16 @@ in case of gateway, instead of defining it as a Thing, use Bridge
`Bridge miio:gateway:lumigateway "Mi Smarter Gateway" [ host="10.10.x.x", token="put here your token", deviceId="326xxxx", model="lumi.gateway.mieu01", communication="direct", cloudServer="de" ]`
# Advanced: Unsupported devices
# Advanced: Getting unsupported devices to work with the binding
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.
There are 3 ways to get unsupported devices working:
- by overriding the model with the model of a similar supported device. E.g. this works great for roborock vacuum devices and yeelight devices). See [Substitute model for unsupported devices](#substitute-model-for-unsupported-devices)
- by switching on the `(experimental) Create channels for new/unsupported devices (MIOT protocol)` channel, this works for most newer devices. See [Create support for new devices based on online published spec database](#create-support-for-new-devices-based-on-online-published-spec-database)
- by switching on the `(experimental) Create channels / test properties for unsupported devices (legacy protocol)` channel. This works for older / legacy devices. It test all known properties to see which are supported by your device. See [Supported property test for unsupported devices](#supported-property-test-for-unsupported-devices)
## Substitute model for unsupported devices
@ -116,7 +119,18 @@ 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.
Look at the openHAB forum, or the openHAB GitHub repository or this readme for the modelId of similar devices.
## Create support for new devices based on online published spec database
The unsupported device has a `(experimental) Create channels for new/unsupported devices (MIOT protocol)` channel. When switching on, it will try to build support based on the published spec from [https://home.miot-spec.com/](https://home.miot-spec.com/).
It will test all properties are in the spec for your device, which may take few minutes.
A test report will be shown in the log and is saved in the `userdata/miio` folder with a filename `test-[your model]-[timestamp].txt`.
The 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.
If this does not happen automatically, restart the binding or restart openHAB in order to have the new database file picked up.
Please validate and feedback if all channels and actions are working, and share the logfile and json files on the openHAB forum or the openHAB GitHub to build future support for this model.
## Supported property test for unsupported devices

6
bundles/org.openhab.binding.miio/src/main/resources/OH-INF/i18n/miio.properties
View File

@ -143,9 +143,9 @@ channel-type.miio.state.label = State
channel-type.miio.state_id.label = State ID
channel-type.miio.string.label = Generic String Channel
channel-type.miio.switch.label = Generic Switch Channel
channel-type.miio.testcommands.label = (experimental)Execute test to find supported channels
channel-type.miio.testcommands.description = Execute test for all known properties to find channels supported by your device. Check your log, share your results.
channel-type.miio.testmiot.label = (experimental) Create experimental support for new MIOT protocol devices
channel-type.miio.testcommands.label = (experimental) Create channels / test properties for unsupported devices (legacy protocol)
channel-type.miio.testcommands.description = Execute test for all known properties to find channels supported by your device. This is for older /legacy devices, newer devices mostly use MIOT. Check your log, share your results.
channel-type.miio.testmiot.label = (experimental) Create channels for new/unsupported devices (MIOT protocol)
channel-type.miio.testmiot.description = Create experimental support for MIOT protocol devices based on the online specification. Check your log, share your results.
channel-type.miio.total_clean_area.label = Total Cleaning Area
channel-type.miio.total_clean_count.label = Total Cleanings

10
bundles/org.openhab.binding.miio/src/main/resources/OH-INF/thing/unsupportedThing.xml
View File

@ -25,23 +25,23 @@
<channel id="power" typeId="power"/>
<channel id="commands" typeId="commands"/>
<channel id="rpc" typeId="rpc"/>
<channel id="testcommands" typeId="testcommands"/>
<channel id="testmiot" typeId="testmiot"/>
<channel id="testcommands" typeId="testcommands"/>
</channels>
</channel-group-type>
<channel-type id="testcommands">
<item-type>Switch</item-type>
<label>(experimental)Execute test to find supported channels</label>
<description>Execute test for all known properties to find channels supported by your device. Check your log, share
<label>(experimental) Create channels / test properties for unsupported devices (legacy protocol)</label>
<description>Execute test for all known properties to find channels supported by your device. This is for older /
legacy devices, newer devices mostly use MIOT. Check your log, share
your results.</description>
<category>settings</category>
</channel-type>
<channel-type id="testmiot">
<item-type>Switch</item-type>
<label>(experimental) Create experimental support for new MIOT protocol devices</label>
<label>(experimental) Create channels for new/unsupported devices (MIOT protocol)</label>
<description>Create experimental support for MIOT protocol devices based on the online specification. Check your log,
share your results.</description>
<category>settings</category>