Xiaomi Miio: convert tables to lists to improve readability and display on mobile #35143
Conversation
c0ffeeca7
requested review from
rytilahti,
syssi and
starkillerOG
as code owners
home-assistant
bot
added
current
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 Walkthrough📝 WalkthroughWalkthroughThe changes in the pull request involve structural and content modifications to the documentation of the Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Documentation
User->>Documentation: Request information on supported devices
Documentation-->>User: Provide organized list of devices
User->>Documentation: Inquire about troubleshooting
Documentation-->>User: Offer detailed troubleshooting steps
User->>Documentation: Check available device actions
Documentation-->>User: List of actions and parameters
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
source/_integrations/xiaomi_miio.markdown (3)
141-206: Enhanced readability for supported subdevicesThe restructuring of the supported subdevices section from a table to a bullet-point list improves consistency with the previous section and enhances overall readability. Each subdevice is now clearly presented with its Zigbee ID and features.
Consider adding a brief introductory sentence before the list to provide context, such as:
"The following subdevices are fully implemented in Home Assistant:"
347-354: Improved readability for Air Purifier 2 sensorsThe restructuring of the Air Purifier 2 sensors from a table to a bullet-point list enhances readability and provides clear descriptions for each sensor. However, the "Enabled by default" information has been removed.
Consider retaining the "Enabled by default" information for each sensor. You could add it to the end of each description, for example:
"- Filter Lifetime Remaining: The remaining life of the filter. (Enabled by default)"
This would preserve the improved readability while maintaining all the original information.
Line range hint
2075-2095: Excellent addition of Xiaomi Cloud Tokens Extractor methodThe addition of the Xiaomi Cloud Tokens Extractor method at the beginning of the "Retrieving the Access Token" section is a significant improvement. This new method provides users with an easier way to retrieve tokens for all their devices, which will greatly simplify the setup process.
Consider adding a brief note explaining why this new method is preferred over the others, such as its ease of use and ability to retrieve tokens for multiple devices at once. This would help users understand why they might choose this method over the others listed.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
- source/_integrations/xiaomi_miio.markdown (3 hunks)
🧰 Additional context used
🔇 Additional comments (5)
source/_integrations/xiaomi_miio.markdown (5)
85-122: Improved structure for supported Xiaomi gateway modelsThe reformatting of the supported Xiaomi gateway models from a table to a bullet-point list enhances readability and makes it easier for users to find specific information about each model. The new structure clearly presents the model number, Zigbee ID, and support status for each gateway type.
212-241: Improved presentation of recognized subdevicesThe restructuring of the recognized subdevices section enhances consistency with the previous sections. The added introductory paragraph provides useful context, and the bullet-point list format improves readability.
Line range hint
28-36: Greatly improved troubleshooting sectionThe expansion of the troubleshooting section is a significant improvement. The detailed explanations of common issues and the addition of links to external documentation will be extremely helpful for users encountering problems. This enhancement will likely reduce user frustration and support requests.
Line range hint
1190-1203: Enhanced readability for Xiaomi Air Quality Monitor sectionThe reformatting of the Xiaomi Air Quality Monitor section to use bullet points for features and attributes improves readability and consistency with other sections of the document. The information remains accurate and complete.
Line range hint
1-2190: Overall excellent improvements to the Xiaomi Miio integration documentationThe changes made to this documentation file significantly enhance its readability and usefulness. Key improvements include:
- Restructuring of device and subdevice lists for better clarity
- Expanded troubleshooting section with more detailed explanations
- Improved formatting consistency throughout the document
- Addition of the Xiaomi Cloud Tokens Extractor method for easier token retrieval
These changes will make it easier for users to set up and troubleshoot their Xiaomi Miio devices, potentially reducing support requests and improving user satisfaction.
c0ffeeca7
changed the title
|
I'm fine with cleaning up the tables, but I think most of the cases they could be removed altogether as they are not that useful. I had a PR at some point to clean up the docs accordingly, but it went stale. Perhaps worth revisiting? |
The goal is not fully revisiting, but more about fixing the tables & combining all platform pages. More improvements are always welcome, but let's try to avoid making a big bang overhaul and instead see if we can approach this iteratively. ../Frenck |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (7)
source/_integrations/xiaomi_miio.markdown (7)
Line range hint
66-74: Consider restructuring the troubleshooting section for improved readabilityThe troubleshooting section provides valuable information about common issues and their solutions. To enhance its usefulness, consider restructuring it into a more easily scannable format, such as a bulleted or numbered list. This would make it easier for users to quickly identify and address their specific issues.
Here's a suggested structure:
## Troubleshooting Common issues and their solutions: 1. **Cross-subnet/VLAN communication**: Xiaomi Miio devices may not communicate across subnets/VLANs due to UDP packet source address issues. [More information and solutions](https://python-miio.readthedocs.io/en/latest/troubleshooting.html#discover-devices-across-subnets) 2. **Roborock vacuum detection**: Ensure Roborock vacuums are connected to the Xiaomi Home app, not the Roborock app. [More information](https://python-miio.readthedocs.io/en/latest/troubleshooting.html#roborock-vacuum-not-detected) 3. **Intermittent connection issues**: Blocking network access to the device can cause intermittent connection problems. [More information](https://python-miio.readthedocs.io/en/latest/troubleshooting.html#intermittent-connection-issues-timeouts-xiaomi-vacuum)
Line range hint
75-237: Consider using a table for supported Xiaomi gateway modelsThe Xiaomi Gateway section provides valuable information about supported models and their features. To enhance readability and make it easier for users to compare different models, consider converting the list of supported gateway models into a table format.
Here's a suggested table structure:
| Gateway Name | Model | Zigbee ID | Supported | |--------------|-------|-----------|-----------| | Chinese version | DGNWG02LM | lumi.gateway.v3 | Yes | | European version | ZHWG11LM-763 / DGNWQ05LM | lumi.gateway.mieu01 | Yes (cloud credentials needed) | | Aqara hub | ZHWG11LM | lumi.gateway.aqhm01 | Yes | | Mijia Zigbee 3.0 | ZNDMWG03LM | lumi.gateway.mgl03 | Yes | | Aqara AC Companion | KTBL01LM | lumi.acpartner.v1 | Untested | | Mi AC Companion | KTBL02LM | lumi.acpartner.v2 | Untested | | Aqara AC Companion | KTBL11LM | lumi.acpartner.v3 | Yes |This format would make it easier for users to quickly find and compare the information for each gateway model.
Line range hint
238-321: Enhance formatting of supported and recognized subdevices listsThe Supported subdevices section provides valuable information about fully implemented and recognized subdevices. To improve readability and consistency, consider the following suggestions:
For fully implemented subdevices:
- Use a consistent format for each entry, preferably a table or a structured list.
- Include headers for Device Name, Zigbee ID, and Features.
For recognized but not yet implemented subdevices:
- Use a table format similar to the gateway models table suggested earlier.
Here's an example of how you could structure the fully implemented subdevices:
### Fully Implemented Subdevices | Device Name | Zigbee ID | Features | |-------------|-----------|----------| | Weather sensor (WSDCGQ01LM) | lumi.sensor_ht | Temperature, Humidity | | Weather sensor (WSDCGQ11LM) | lumi.weather.v1 | Temperature, Humidity, Pressure | | Wall switch single (QBKG11LM) | lumi.ctrl_ln1, lumi.ctrl_ln1.aq1 | Load power, Status, Turn on/off, Toggle | ...And for the recognized subdevices:
### Recognized Subdevices (Not Yet Implemented) | Device Name | Model | Zigbee ID | |-------------|-------|-----------| | Button | WXKG01LM | lumi.sensor_switch | | Button | WXKG11LM 2015 | lumi.sensor_switch.aq2 | | Button | WXKG12LM | lumi.sensor_switch.aq3 | ...These changes would make the information more scannable and easier to reference.
Line range hint
322-501: Improve readability of supported devices listThe Xiaomi Air Purifier, Air Humidifier and Standing Fan section provides comprehensive information about supported devices and their features. To enhance readability, consider restructuring the list of supported devices into a table format.
Here's a suggested table structure:
| Device Type | Model Number | Model Identifier | |-------------|--------------|-------------------| | Air Purifier | - | zhimi.airpurifier.v1 | | Air Purifier 2 | FJY4006CN | zhimi.airpurifier.v2 | | Air Purifier V3 | - | zhimi.airpurifier.v3 | ...This format would make it easier for users to quickly find and identify their specific device model. Additionally, consider grouping the devices by type (Air Purifiers, Air Humidifiers, Standing Fans) for better organization.
Line range hint
502-735: Standardize formatting across Air Purifier model sectionsThe sections detailing specific Air Purifier models provide comprehensive information about features, attributes, and entities. To improve consistency and readability across all model sections, consider adopting a standardized format for each model. This could include:
- A brief introduction to the model
- A table for attributes
- A table for number entities
- A table for sensor entities
- A table for switch entities
- Any model-specific notes or additional information
Here's an example of how this could be structured:
### Air Purifier Model X (model.identifier) Brief description of the model and its key features. #### Attributes | Attribute | Description | |-----------|-------------| | attribute_1 | Description of attribute_1 | | attribute_2 | Description of attribute_2 | ... #### Number Entities | Entity | Description | |--------|-------------| | entity_1 | Description of entity_1 | | entity_2 | Description of entity_2 | ... #### Sensor Entities | Sensor | Description | Enabled by Default | |--------|-------------|---------------------| | sensor_1 | Description of sensor_1 | Yes/No | | sensor_2 | Description of sensor_2 | Yes/No | ... #### Switch Entities | Switch | Description | |--------|-------------| | switch_1 | Description of switch_1 | | switch_2 | Description of switch_2 | ... Additional notes or information specific to this model.Applying this structure consistently across all model sections would significantly improve the overall organization and readability of the documentation.
Line range hint
736-1185: Extend standardized formatting to Air Humidifier and Fan sectionsThe sections covering Air Humidifier and Fan models, like the Air Purifier sections, contain comprehensive information about features, attributes, and entities. To further improve the documentation's consistency and readability, the standardized format suggested for the Air Purifier models should be applied to these sections as well.
Applying a consistent structure across all device types (Air Purifiers, Air Humidifiers, and Fans) would:
- Make it easier for users to find specific information regardless of device type.
- Improve the overall organization of the documentation.
- Facilitate easier comparisons between different models and device types.
Consider using the same table structures and section headings for attributes, number entities, sensor entities, and switch entities across all device types. This consistency will greatly enhance the user experience when referencing the documentation for multiple device types.
Line range hint
1186-2092: Enhance organization of the Access Token retrieval sectionThe Actions section is well-structured and provides clear information about available actions for different device types. However, the Access Token retrieval section, while comprehensive, could benefit from improved organization to enhance readability and user navigation.
Consider the following improvements for the Access Token retrieval section:
- Start with a brief overview of why the access token is needed and when it's required.
- Organize the different retrieval methods into clear subsections, each with a descriptive heading.
- Use a consistent format for each method, including:
- Required tools or prerequisites
- Step-by-step instructions
- Any warnings or limitations
- Consider using a table to summarize the different methods, their difficulty levels, and which devices they work for.
Here's a suggested structure:
## Retrieving the Access Token Brief explanation of the access token's importance and when it's needed. ### Summary of Retrieval Methods | Method | Difficulty | Supported Devices | Notes | |--------|------------|-------------------|-------| | Xiaomi Cloud Tokens Extractor | Easy | All | Recommended method | | Mi Home app | Medium | Specific devices | Requires developer mode | | ... | ... | ... | ... | ### Method 1: Xiaomi Cloud Tokens Extractor Prerequisites: - List of required tools Steps: 1. Step 1 2. Step 2 ... ### Method 2: Mi Home app Prerequisites: - List of required tools Steps: 1. Step 1 2. Step 2 ... ... (repeat for each method) ### Important Notes and Warnings - Note about token regeneration after Wi-Fi reset - Warning about using the correct app version - Any other crucial informationThis structure would make it easier for users to choose the most appropriate method for their situation and follow the instructions more easily.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
- source/_integrations/xiaomi_miio.markdown (31 hunks)
🧰 Additional context used
🔇 Additional comments (3)
source/_integrations/xiaomi_miio.markdown (3)
Line range hint
1-40: LGTM: Well-structured introduction and metadataThe initial section of the Xiaomi Miio integration documentation is well-organized and provides comprehensive information about the integration, including supported device categories and integration details. The introduction gives a clear overview of the supported devices.
Line range hint
41-54: LGTM: Clear and informative prerequisites sectionThe prerequisites section effectively communicates the setup requirements for Xiaomi Miio devices. It clarifies UI configuration support, mentions exceptions, and provides important advice about using the Mi Home app. The note about complex network setups with a link to additional documentation is particularly helpful.
Line range hint
55-65: LGTM: Comprehensive configuration and cloud credentials guidanceThis section effectively guides users through the configuration process, emphasizing the importance of providing Xiaomi cloud credentials. The information about specifying the correct cloud server and the link to determine the server by country are particularly valuable for ensuring a smooth setup process.
For future reviews, please don't suggest to convert lists into tables. |
Proposed change
Xiaomi Miio: convert first tables to list to improve readability and mobile
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit