Skip to content

Commit

Permalink
[miio] improve readme: restructure & map customizing feature (openhab…
Browse files Browse the repository at this point in the history 
…#11143)

Signed-off-by: Marcel Verpaalen <[email protected]>
  • Loading branch information
@marcelrv
marcelrv authored Aug 29, 2021
1 parent e1010e1 commit 957c9ea
Show file tree
Hide file tree
Showing 2 changed files with 84 additions and 58 deletions.
71 changes: 42 additions & 29 deletions bundles/org.openhab.binding.miio/README.base.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_
Expand Down Expand Up @@ -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


Expand Down Expand Up @@ -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

Expand Down
71 changes: 42 additions & 29 deletions bundles/org.openhab.binding.miio/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_
Expand Down Expand Up @@ -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 (<a name="cgllc-airm-cgdn1">cgllc.airm.cgdn1</a>) Channels

| Channel | Type | Description | Comment |
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 957c9ea

Please sign in to comment.