From 87dd146ddc22336a8abd778da778cf1a5a37330f Mon Sep 17 00:00:00 2001 From: Marcel Verpaalen Date: Sun, 22 Aug 2021 13:04:05 +0200 Subject: [PATCH] [miio] improve readme: restructure & map customizing feature Signed-off-by: Marcel Verpaalen --- .../org.openhab.binding.miio/README.base.md | 71 +++++++++++-------- bundles/org.openhab.binding.miio/README.md | 71 +++++++++++-------- 2 files changed, 84 insertions(+), 58 deletions(-) diff --git a/bundles/org.openhab.binding.miio/README.base.md b/bundles/org.openhab.binding.miio/README.base.md index 1398a2a7f409e..7cde488e60f66 100644 --- a/bundles/org.openhab.binding.miio/README.base.md +++ b/bundles/org.openhab.binding.miio/README.base.md @@ -164,7 +164,7 @@ Set the communication in the thing configuration to 'cloud'. _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. +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. _My Roborock vacuum is not found or not reacting_ @@ -196,6 +196,47 @@ note: the ADVANCED `actions#commands` and `actions#rpc` channels can be used to e.g. `openhab:send actionCommand 'upd_timer["1498595904821", "on"]'` would enable a pre-configured timer. See https://github.com/marcelrv/XiaomiRobotVacuumProtocol for all known available commands. +### Robo Rock vacuum Channels + +| Type | Channel | Description | +|---------|-----------------------------------|----------------------------| +| Number | status#segment_status | Segment Status | +| Number | status#map_status | Map Box Status | +| Number | status#led_status | Led Box Status | +| String | info#carpet_mode | Carpet Mode details | +| String | info#fw_features | Firmware Features | +| String | info#room_mapping | Room Mapping details | +| String | info#multi_maps_list | Maps Listing details | + +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 | +| Switch | status#is_locating | Robot is locating | +| Number | actions#segment | Room Clean (enter room #) | + +Note: cleaning map is only available with cloud access. + +There are several advanced channels, which may be useful in rules (e.g. for individual room cleaning etc) +In case your vacuum does not support one of these commands, it will show "unsupported_method" for string channels or no value for numeric channels. + +### Advanced: Vacuum Map Customization + +In case the default rendering of the vacuum map is not meeting your integration needs, the rendering can be tailored. +The way to customize this is to create a file with the name `mapConfig.json` in the `userdata/miio` folder. +If the binding finds this file it will read the map rendering preferences from there. +If the file is available but invalid json, it will create a new file with all the default values for you to customize. +This allows you to control the colors, if logo is displayed, if and what text is rendered etc. +To (re-)read the file either restart openHAB, restart the binding or alternatively edit the thing and make (any) minor change. +Note, cropping is disabled (hence showing like the maps in OH3.1 and earlier) for any `cropBorder` value < 0. +Note, not all the values need to be in the json file, e.g. a subset of the parameters also works, the parameters not in the `mapConfig.json` will take the default values. + + !!!channelList @@ -245,34 +286,6 @@ Switch lastCompleted "Last Cleaning Completed" (gVacLast) {channel="miio:vac Image map "Cleaning Map" (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#map"} ``` -Note: cleaning map is only available with cloud access. - -There are several advanced channels, which may be useful in rules (e.g. for individual room cleaning etc) -In case your vacuum does not support one of these commands, it will show "unsupported_method" for string channels or no value for numeric channels. - -| Type | Channel | Description | -|---------|-----------------------------------|----------------------------| -| Number | status#segment_status | Segment Status | -| Number | status#map_status | Map Box Status | -| Number | status#led_status | Led Box Status | -| String | info#carpet_mode | Carpet Mode details | -| String | info#fw_features | Firmware Features | -| String | info#room_mapping | Room Mapping details | -| String | info#multi_maps_list | Maps Listing details | - -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 | -| Switch | status#is_locating | Robot is locating | -| Number | actions#segment | Room Clean (enter room #) | - - !!!itemFileExamples diff --git a/bundles/org.openhab.binding.miio/README.md b/bundles/org.openhab.binding.miio/README.md index f4fd5108bb8c5..b56de128dc35a 100644 --- a/bundles/org.openhab.binding.miio/README.md +++ b/bundles/org.openhab.binding.miio/README.md @@ -164,7 +164,7 @@ Set the communication in the thing configuration to 'cloud'. _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. +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. _My Roborock vacuum is not found or not reacting_ @@ -523,6 +523,47 @@ note: the ADVANCED `actions#commands` and `actions#rpc` channels can be used to e.g. `openhab:send actionCommand 'upd_timer["1498595904821", "on"]'` would enable a pre-configured timer. See https://github.com/marcelrv/XiaomiRobotVacuumProtocol for all known available commands. +### Robo Rock vacuum Channels + +| Type | Channel | Description | +|---------|-----------------------------------|----------------------------| +| Number | status#segment_status | Segment Status | +| Number | status#map_status | Map Box Status | +| Number | status#led_status | Led Box Status | +| String | info#carpet_mode | Carpet Mode details | +| String | info#fw_features | Firmware Features | +| String | info#room_mapping | Room Mapping details | +| String | info#multi_maps_list | Maps Listing details | + +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 | +| Switch | status#is_locating | Robot is locating | +| Number | actions#segment | Room Clean (enter room #) | + +Note: cleaning map is only available with cloud access. + +There are several advanced channels, which may be useful in rules (e.g. for individual room cleaning etc) +In case your vacuum does not support one of these commands, it will show "unsupported_method" for string channels or no value for numeric channels. + +### Advanced: Vacuum Map Customization + +In case the default rendering of the vacuum map is not meeting your integration needs, the rendering can be tailored. +The way to customize this is to create a file with the name `mapConfig.json` in the `userdata/miio` folder. +If the binding finds this file it will read the map rendering preferences from there. +If the file is available but invalid json, it will create a new file with all the default values for you to customize. +This allows you to control the colors, if logo is displayed, if and what text is rendered etc. +To (re-)read the file either restart openHAB, restart the binding or alternatively edit the thing and make (any) minor change. +Note, cropping is disabled (hence showing like the maps in OH3.1 and earlier) for any `cropBorder` value < 0. +Note, not all the values need to be in the json file, e.g. a subset of the parameters also works, the parameters not in the `mapConfig.json` will take the default values. + + ### Qingping Air Monitor Lite (cgllc.airm.cgdn1) Channels | Channel | Type | Description | Comment | @@ -5102,34 +5143,6 @@ Switch lastCompleted "Last Cleaning Completed" (gVacLast) {channel="miio:vac Image map "Cleaning Map" (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#map"} ``` -Note: cleaning map is only available with cloud access. - -There are several advanced channels, which may be useful in rules (e.g. for individual room cleaning etc) -In case your vacuum does not support one of these commands, it will show "unsupported_method" for string channels or no value for numeric channels. - -| Type | Channel | Description | -|---------|-----------------------------------|----------------------------| -| Number | status#segment_status | Segment Status | -| Number | status#map_status | Map Box Status | -| Number | status#led_status | Led Box Status | -| String | info#carpet_mode | Carpet Mode details | -| String | info#fw_features | Firmware Features | -| String | info#room_mapping | Room Mapping details | -| String | info#multi_maps_list | Maps Listing details | - -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 | -| Switch | status#is_locating | Robot is locating | -| Number | actions#segment | Room Clean (enter room #) | - - ### Qingping Air Monitor Lite (cgllc.airm.cgdn1) item file lines