Add documentation on Shelly Dimmer calibration capability #4443
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
WalkthroughThe pull request updates the documentation for the Changes
Possibly related PRs
Suggested reviewers
Warning Rate limit exceeded@olegtarasov has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 20 minutes and 31 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 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 (4)
components/light/shelly_dimmer.rst (4)
106-108: Consider using more confident language.The phrase "An attempt was made" might undermine user confidence in the feature. Consider rephrasing to something more assertive like "ESPHome now implements automatic calibration similar to the original Shelly firmware."
-An attempt was made to replicate this process in Shelly Dimmer component for ESPHome. In order to be able to calibrate +The Shelly Dimmer component for ESPHome now implements automatic calibration similar to the original firmware. To calibrate your dimmer, you need to take several steps:
121-130: Document the hardcoded component ID pattern.The lambda code uses a hardcoded ID
shelly_dimmer_shellydimmer_id, but it's not clear how this ID is constructed. Add a note explaining the ID naming pattern to help users adapt the code for their configuration.
112-115: Clarify the update_interval purpose.The explanation about
update_intervalcould be more precise. Consider mentioning that this speeds up calibration by increasing the frequency of power measurements, which are essential for the calibration process.-2. Add ``update_interval: 1s`` to your Shelly ``light`` section. This is not strictly required, but will greatly - increase the speed of calibration process. ``update_interval`` can be removed after calibration. This - change will result in power, voltage and current sensors being reported to HA every second instead of every 10 - seconds. +2. Add ``update_interval: 1s`` to your Shelly ``light`` section. While optional, this significantly speeds up the + calibration process by increasing the frequency of power measurements from every 10 seconds to every second. + You can remove this setting after calibration is complete.
147-154: Consider adding error handling information.The calibration process description is clear, but consider adding information about:
- What happens if calibration fails
- Whether the process can be safely interrupted
- How to verify if calibration was successful beyond visual observation
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
components/light/shelly_dimmer.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
components/light/shelly_dimmer.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
🔇 Additional comments (2)
components/light/shelly_dimmer.rst (2)
99-105: LGTM! Clear and informative introduction.
The introduction effectively explains the problem of non-linear dimming characteristics and why calibration is beneficial.
96-155: LGTM! Well-structured and comprehensive documentation.
The new calibration documentation is clear, well-organized, and provides all necessary information for users to implement and use the feature. The step-by-step instructions are easy to follow, and the technical explanations are accurate.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (2)
components/light/shelly_dimmer.rst (2)
106-113: Consider adding a reference to lambda documentation.The setup instructions are clear, but consider adding a link to ESPHome's lambda documentation when mentioning "lambdas" in step 2, as this term might not be familiar to all users.
-2. Add ``output_id`` to your ``light`` configuration. This id will be used to access calibration functions from lambdas. +2. Add ``output_id`` to your ``light`` configuration. This id will be used to access calibration functions from :doc:`lambdas </guides/automations>`.
147-156: Consider adding error handling information.The calibration process description is detailed, but it would be helpful to add information about:
- What happens if calibration fails
- How to verify if calibration was successful
- Troubleshooting steps if the results are not satisfactory
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
components/light/shelly_dimmer.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
components/light/shelly_dimmer.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
🔇 Additional comments (2)
components/light/shelly_dimmer.rst (2)
96-105: LGTM! Clear and informative introduction.
The introduction effectively explains the problem of non-linear dimming characteristics and why automatic calibration is beneficial.
133-146: LGTM! Well-formatted configuration example.
The clear calibration button example is clear and follows proper YAML formatting.
components/light/shelly_dimmer.rst
Outdated
| button: | ||
| - platform: template | ||
| id: calibrate_button | ||
| name: "Calibrate" | ||
| entity_category: config | ||
| on_press: | ||
| then: | ||
| - lambda: |- | ||
| id(shelly)->start_calibration(); | ||
|
|
There was a problem hiding this comment.
Fix YAML indentation in the template button example.
The indentation in the template button configuration is inconsistent. The id, name, entity_category, and on_press fields should be aligned.
button:
- platform: template
- id: calibrate_button
- name: "Calibrate"
- entity_category: config
- on_press:
- then:
- - lambda: |-
- id(shelly)->start_calibration();
+ id: calibrate_button
+ name: "Calibrate"
+ entity_category: config
+ on_press:
+ then:
+ - lambda: |-
+ id(shelly)->start_calibration();📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| button: | |
| - platform: template | |
| id: calibrate_button | |
| name: "Calibrate" | |
| entity_category: config | |
| on_press: | |
| then: | |
| - lambda: |- | |
| id(shelly)->start_calibration(); | |
| button: | |
| - platform: template | |
| id: calibrate_button | |
| name: "Calibrate" | |
| entity_category: config | |
| on_press: | |
| then: | |
| - lambda: |- | |
| id(shelly)->start_calibration(); |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
components/light/shelly_dimmer.rst (3)
109-114: Consider adding information about calibration data persistence.The setup instructions are clear and well-organized. Consider adding a note about whether calibration data persists across device reboots/power cycles.
133-146: Consider adding a warning about clearing calibration.The clear calibration button configuration is correct. However, consider adding a note about the implications of clearing calibration data (e.g., whether it requires recalibration immediately after clearing).
147-157: Consider adding error handling information.The calibration process description is clear and detailed. However, consider adding information about:
- What happens if calibration fails
- How to identify if calibration was successful
- Common troubleshooting steps
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
components/light/shelly_dimmer.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
components/light/shelly_dimmer.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
🔇 Additional comments (2)
components/light/shelly_dimmer.rst (2)
96-108: LGTM! Clear and informative introduction.
The explanation of non-linear characteristics and the need for calibration is well-written and technically accurate.
115-132: LGTM! Well-structured configuration example.
The YAML configuration is correctly formatted and provides a clear example of setting up the calibration button.
Description:
This PR documents the process of calibrating Shelly Dimmer using its new capability.
Related issue (if applicable):
Pull request in esphome with YAML changes (if applicable): esphome/esphome#7773
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/index.rstwhen creating new documents for new components or cookbook.