Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[miio] Improve readme: restructure & map customizing feature #11143

Merged
merged 1 commit into from
Aug 29, 2021
Merged

[miio] Improve readme: restructure & map customizing feature #11143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 42 additions & 29 deletions bundles/org.openhab.binding.miio/README.base.md
View file
Open in desktop
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
Open in desktop
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