[bl0940] document new configuration options#5340
Conversation
![esphome[bot]](https://avatars.githubusercontent.com/in/247347?s=60&v=4){kind=small}
There was a problem hiding this comment.
As this is a feature matched with a PR in https://github.com/esphome/esphome, please target your PR to the next branch and rebase.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughDocumentation updates only. The components index updates the BL0940 description to include Energy. The BL0940 sensor page is rewritten from a brief note to a full UART-based documentation with example configuration, configuration variables, calibration concepts and formulas, online calibration numbers, reset button, and references. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested labels
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
content/components/sensor/bl0940.md (2)
77-85: Remove trailing punctuation in heading; minor unit clarityFix MD026 and improve R2 note.
-#### Available calibration options: +#### Available calibration options @@ -resistor_two: 1950 # R2 = 5 x 390 kΩ -> 1950 kΩ +resistor_two: 1950 # R2 = 5 × 390 kΩ = 1950 kΩ
159-166: Remove trailing punctuation in heading (MD026)-### Calibration details: +### Calibration details
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
content/components/sensor/images/bl0940-cal.pngis excluded by!**/*.png
📒 Files selected for processing (2)
content/components/_index.md(1 hunks)content/components/sensor/bl0940.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
content/components/_index.mdcontent/components/sensor/bl0940.md
🪛 GitHub Check: build
content/components/sensor/bl0940.md
[failure] 157-157:
Lists should be surrounded by blank lines [Context: "> - unit_of_measurement: `..."]
🪛 GitHub Actions: Lint
content/components/sensor/bl0940.md
[error] 77-77: Markdownlint MD026: Trailing punctuation in heading [Punctuation: ':'] (step: nosborn/github-action-markdown-cli@v3.5.0)
🔇 Additional comments (10)
content/components/_index.md (1)
326-326: BL0940 now lists Energy – good alignment with new docsMatches the added energy sensor support on the BL0940 page.
content/components/sensor/bl0940.md (9)
87-101: Good: formulae and source reference are explicitClear mapping from schematic values to computed references.
103-111: Legacy defaults block looks consistentKeeps backward compatibility explicit.
112-122: Nice: manual override precedence and example valuesExample aligns with corrected defaults above.
171-179: Reset button docs are concise and clearLGTM.
1-8: Process: target branch should be “next” until esphome#8158 shipsFront matter is fine, but the PR description says “merge into next”; the PR metadata targets “current”. Please confirm and retarget to
nextif this feature isn’t in a released ESPHome yet.
187-188: Use standard apiref shortcode for API linkConsistent with other component pages.
-- API reference: bl0940/bl0940.h +- {{< apiref "bl0940/bl0940.h" >}}
10-13: Fix grammar and clarify UART pin names
- “energy monitors sensors” → “energy monitor sensors” (or simply “energy monitor”).
- “Tuya-devices” → “Tuya devices”.
- Refer to config keys: use
tx_pinandrx_pininstead of “TX and RX pins”.- Verify product name spellings: “power-metering BW-SHP10” and “Vaiotech Rowi2 Smart Plug”.
-The `bl0940` component allows you to use BL0940 energy monitors sensors with ESPHome. These are used in some Tuya-devices (e.g. the power metering BW-SHP10) and the Vaiotech Rowi2 Smart Plug. +The `bl0940` component allows you to use BL0940 energy monitor sensors with ESPHome. These are used in some Tuya devices (e.g. the power-metering BW-SHP10) and the Vaiotech Rowi2 Smart Plug. @@ -The communication with this component is done via a UART. You must therefore have a `uart:` entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 4800 with 1 stop bit. +Communication is via UART. Add a `uart:` entry with `tx_pin` and `rx_pin` set for your board, baud rate 4800, and 1 stop bit.
61-69: Swap voltage_reference and current_reference defaults; add units for resistors-**resistor_shunt** (*Optional*, float): The calibration parameter for RL. Defaults to `1` -**resistor_one** (*Optional*, float): The calibration parameter for R1. Defaults to `0.51` -**resistor_two** (*Optional*, float): The calibration parameter for R2. Defaults to `1950` +**resistor_shunt** (*Optional*, float): Shunt resistor RL in mΩ. Default: `1`. +**resistor_one** (*Optional*, float): Divider resistor R1 in kΩ. Default: `0.51`. +**resistor_two** (*Optional*, float): Divider resistor R2 in kΩ. Default: `1950`. @@ -**voltage_reference** (*Optional*, float): The calibration parameter for voltage readings. Defaults to `266013.136288998` as calculated using schema defaults. -**current_reference** (*Optional*, float): The calibration parameter for current readings. Defaults to `17158.9201389365` as calculated using schema defaults. +**voltage_reference** (*Optional*, float): The calibration parameter for voltage readings. Defaults to `17158.9201389365` (calculated from defaults). +**current_reference** (*Optional*, float): The calibration parameter for current readings. Defaults to `266013.136288998` (calculated from defaults).Please verify these numbers against the implementation constants and example calculations.
47-57: Tighten option wording; fix “energy”/“external_temperature” descriptions
- Standardize read/write command default formatting.
- Update energy description to cumulative energy in kWh.
- Clarify that external_temperature may be unconnected and return invalid data.
-**read_command** (*Optional*): The byte used for the read commands when communicating with the BL0940. By default, it is set to `0x58` or `0x50` in `legacy_mode`. +**read_command** (*Optional*): Byte used for read commands. Default: `0x58` (or `0x50` in `legacy_mode`). -**write_command** (*Optional*): byte used for the write commands when communicating with the BL0940. By default, it is set to `0xA8` or `0xA0` in `legacy_mode`. +**write_command** (*Optional*): Byte used for write commands. Default: `0xA8` (or `0xA0` in `legacy_mode`). -**energy** (*Optional*): Use the voltage value of the sensor in kWh. All options from Sensor. +**energy** (*Optional*): Cumulative energy in kWh. All options from Sensor. -**external_temperature** (*Optional*): The external value of the sensor in °C. Often not connected and gives garbage data. All options from Sensor. +**external_temperature** (*Optional*): External temperature in °C. Often not connected on devices and may return invalid data. All options from Sensor.Confirm read/write command defaults match esphome/esphome#8158.
content/components/sensor/bl0940.md
Outdated
| #### Calibration variables: | ||
|
|
||
| - **min_value** (*Optional*, float): The minimum value this number can be. Minimal allowed value is `-50` defaults to `-10`. | ||
| - **max_value** (*Optional*, float): The maximum value this number can be. Maximal allowed value is `50` defaults to `10`. | ||
| - **step** (*Optional*, float): The granularity with which the number can be set. Defaults to `0.1`. | ||
| - **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. Defaults to `True` | ||
| - All other options from Number. | ||
|
|
||
| > **Note:** There are some fixed values defined: | ||
| > - **unit_of_measurement**: `UNIT_PERCENT` | ||
|
|
There was a problem hiding this comment.
Fix heading punctuation, boolean casing, and markdown list spacing; avoid internal constant name
- Remove trailing colon (MD026).
- Use lowercase YAML boolean for consistency.
- Surround the list with blank lines (markdownlint).
- Prefer “%” over internal
UNIT_PERCENT.
-#### Calibration variables:
+#### Calibration variables
@@
-- **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. Defaults to `True`
+- **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. Defaults to `true`.
@@
-> **Note:** There are some fixed values defined:
-> - **unit_of_measurement**: `UNIT_PERCENT`
+> **Note:** There are some fixed values defined.
+>
+> - unit_of_measurement: `%`
+>📝 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.
| #### Calibration variables: | |
| - **min_value** (*Optional*, float): The minimum value this number can be. Minimal allowed value is `-50` defaults to `-10`. | |
| - **max_value** (*Optional*, float): The maximum value this number can be. Maximal allowed value is `50` defaults to `10`. | |
| - **step** (*Optional*, float): The granularity with which the number can be set. Defaults to `0.1`. | |
| - **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. Defaults to `True` | |
| - All other options from Number. | |
| > **Note:** There are some fixed values defined: | |
| > - **unit_of_measurement**: `UNIT_PERCENT` | |
| #### Calibration variables | |
| - **min_value** (*Optional*, float): The minimum value this number can be. Minimal allowed value is `-50` defaults to `-10`. | |
| - **max_value** (*Optional*, float): The maximum value this number can be. Maximal allowed value is `50` defaults to `10`. | |
| - **step** (*Optional*, float): The granularity with which the number can be set. Defaults to `0.1`. | |
| - **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. Defaults to `true`. | |
| - All other options from Number. | |
| > **Note:** There are some fixed values defined. | |
| > | |
| > - unit_of_measurement: `%` | |
| > |
🧰 Tools
🪛 GitHub Check: build
[failure] 157-157:
Lists should be surrounded by blank lines [Context: "> - unit_of_measurement: `..."]
🤖 Prompt for AI Agents
In content/components/sensor/bl0940.md around lines 148 to 158, the markdown has
a trailing colon on the "Calibration variables:" heading, inconsistent boolean
casing, missing blank lines around the list, and exposes an internal constant
name for the unit; remove the trailing colon from the heading, change
"True"/"False" to lowercase YAML booleans (true/false), add a blank line before
and after the bulleted list, and replace the internal constant `UNIT_PERCENT`
with the literal percent symbol (%) in the text.
There was a problem hiding this comment.
As this is a feature matched with a PR in https://github.com/esphome/esphome, please target your PR to the next branch and rebase.
There was a problem hiding this comment.
As this is a feature matched with a PR in https://github.com/esphome/esphome, please target your PR to the next branch and rebase.
esphome
bot
dismissed
their stale review
Base branch has been corrected - dismissing previous review.
esphome
bot
dismissed
their stale review
Base branch has been corrected - dismissing previous review.
dan-s-github
force-pushed
the
bl0940md
branch
from
7061e3c to
e111f11
Compare
esphome
bot
dismissed
their stale review
Base branch has been corrected - dismissing previous review.
2 participants
Description:
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
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
/components/index.rstwhen creating new documents for new components or cookbook.New Component Images
If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.
To generate a component image:
Comment on this pull request with the following command, replacing
COMPONENT_NAMEwith your component name in UPPER_CASE format with underscores (e.g.,BME280,SHT3X,DALLAS_TEMP):The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.
Extract the SVG file and place it in the
images/folder of this repository.Use the image in your component's index table entry in
/components/index.rst.Example: For a component called "DHT22 Temperature Sensor", use: