Skip to content

Add Modbus alternative configuration and actions#6094

Open
autox86 wants to merge 4 commits intoesphome:currentfrom
autox86:patch-1
Open

Add Modbus alternative configuration and actions#6094
autox86 wants to merge 4 commits intoesphome:currentfrom
autox86:patch-1

Conversation

@autox86
Copy link

@autox86 autox86 commented Feb 16, 2026

Added alternative configuration section for Modbus usage with example YAML configuration and actions for online/offline states.

Description:

Related issue (if applicable): fixes

Pull request in esphome with YAML changes (if applicable):

  • esphome/esphome#

Checklist:

  • I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
    or

  • I am merging into current because 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.md when 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:

  1. Comment on this pull request with the following command, replacing component_name with your component name in lower_case format with underscores (e.g., bme280, sht3x, dallas_temp):

    @esphomebot generate image component_name
    
  2. The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.

  3. Extract the SVG file and place it in the /static/images/ folder of this repository.

  4. Use the image in your component's index table entry in /components/_index.md.

Example: For a component called "DHT22 Temperature Sensor", use:

@esphomebot generate image dht22

Added alternative configuration section for Modbus usage with example YAML configuration and actions for online/offline states.
@esphome esphome bot added the current label Feb 16, 2026
@netlify
Copy link

netlify bot commented Feb 16, 2026

Deploy Preview for esphome ready!

Name Link
🔨 Latest commit 78dc8ee
🔍 Latest deploy log https://app.netlify.com/projects/esphome/deploys/699345c535a44400085d3bb0
😎 Deploy Preview https://deploy-preview-6094--esphome.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Feb 16, 2026

No actionable comments were generated in the recent review. 🎉


Walkthrough

Adds an alternative Modbus-based configuration example to the PZEM-DC sensor documentation, including UART and modbus_controller setup, multiple modbus_controller-backed sensors (voltage, current, power, total_daily_energy), and explicit on_online/on_offline handlers that publish online state and zero sensors when offline.

Changes

Cohort / File(s) Summary
PZEMDC Sensor Documentation
content/components/sensor/pzemdc.md
Replaced "See Also" with an "Alternative configuration via Modbus" section. Added full Modbus example: UART setup, modbus + modbus_controller configuration, multiple sensor entries using modbus_controller, a sensor.total_daily_energy wired to power, and on_online/on_offline actions publishing online state and zeroing measurements with a warning log.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'Add Modbus alternative configuration and actions' directly and accurately summarizes the main changes: adding a Modbus configuration section with examples and online/offline action handling.
Description check ✅ Passed The description clearly relates to the changeset, mentioning the addition of alternative Modbus configuration section with example YAML and online/offline state actions.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection ✅ Passed ✅ No merge conflicts detected when merging into current

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.


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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🤖 Fix all issues with AI agents
In `@content/components/sensor/pzemdc.md`:
- Line 173: The markdown line uses triple backticks around inline code; change
it to use single backticks so the action names render correctly: replace the
malformed text containing ```on_offline``` and ```on_online``` with `on_offline`
and `on_online` (update the line where the action names appear in
content/components/sensor/pzemdc.md, referencing the tokens on_offline and
on_online).
- Around line 82-83: Replace the bold text used for the section title with a
proper Markdown heading and add a blank line before the fenced code block:
change the "**Example Config**" line to a heading (e.g., "## Example Config")
and ensure there is an empty line between that heading and the triple-backtick
```yaml fence so the code block renders correctly.
- Line 199: In content/components/sensor/pzemdc.md there are multiple
consecutive blank lines; remove the extra blank line(s) so only a single blank
line remains between paragraphs/sections (collapse any run of blank lines to a
single newline) to satisfy the static analysis rule.
- Around line 202-206: Replace the legacy Hugo shortcodes in
content/components/sensor/pzemdc.md (the instances of {{< docref
"/components/uart" >}}, {{< docref "/components/modbus" >}}, {{< docref
"/components/modbus_controller" >}}, {{< docref
"/components/sensor/modbus_controller" >}}, and {{< docref
"/components/sensor/total_daily_energy" >}}) with standard Markdown links; for
each shortcode use [display text](path) — e.g. replace {{< docref
"/components/uart" >}} with [Components: UART](/components/uart) (or a concise
human-friendly label you prefer) and do the same for the other four shortcodes,
ensuring the link paths match the quoted paths and the display text is clear and
consistent.
- Line 91: Update the pzemdc.md documentation to clarify the differing UART
"stop_bits" values: add a short note next to the pzemdc component example (the
native pzemdc example using stop_bits: 2) and next to the Modbus alternative
example (the Modbus-over-UART example using stop_bits: 1) stating that both
settings are correct for their respective methods — the native pzemdc driver
expects 2 stop bits, while the Modbus-over-UART configuration typically uses 1
stop bit — and include a one-line rationale that the native driver and Modbus
protocol expect different UART framing so users should keep the stop_bits as
shown for each method.
🧹 Nitpick comments (1)
content/components/sensor/pzemdc.md (1)

80-80: Minor grammar improvement needed.

The phrase "is great working for" is awkward. Consider rephrasing to "works great for" or "is great for".

✏️ Proposed fix
-While its own component is great working for a basic setup, you may want to have more possibilities while using modbus controller.
+While its own component works great for a basic setup, you may want to have more possibilities when using the modbus controller.

tx_pin: gpio03
rx_pin: gpio01
baud_rate: 9600
stop_bits: 1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, let's check if the file exists and examine the relevant sections
find . -name "pzemdc.md" -type f

Repository: esphome/esphome-docs

Length of output: 101


🏁 Script executed:

# Read the file to check the actual content around lines 31 and 91
wc -l content/components/sensor/pzemdc.md

Repository: esphome/esphome-docs

Length of output: 103


🏁 Script executed:

# Read the relevant sections
sed -n '25,35p' content/components/sensor/pzemdc.md

Repository: esphome/esphome-docs

Length of output: 211


🏁 Script executed:

# Read around line 91
sed -n '85,95p' content/components/sensor/pzemdc.md

Repository: esphome/esphome-docs

Length of output: 264


🏁 Script executed:

# Search for all stop_bits references in PZEM-related files
rg 'stop_bits' -C2 --type=md -g '*pzem*'

Repository: esphome/esphome-docs

Length of output: 555


🏁 Script executed:

# Read more context around the first configuration (stop_bits: 2)
sed -n '20,45p' content/components/sensor/pzemdc.md

Repository: esphome/esphome-docs

Length of output: 665


🏁 Script executed:

# Read more context around the second configuration (stop_bits: 1)
sed -n '75,100p' content/components/sensor/pzemdc.md

Repository: esphome/esphome-docs

Length of output: 604


🏁 Script executed:

# Check if there are any section headers or explanations
grep -n "^##\|^###\|Example\|configuration" content/components/sensor/pzemdc.md | head -20

Repository: esphome/esphome-docs

Length of output: 448


Clarify stop_bits configuration difference between PZEM component and Modbus alternative.

The documentation shows two different UART configurations for PZEM devices: the native pzemdc component uses stop_bits: 2 (line 31), while the alternative "Modbus" configuration uses stop_bits: 1 (line 91). These are presented as separate methods, but the documentation does not explain why the settings differ or which is required for proper operation. Add a note clarifying whether both settings are correct for their respective methods or if one should be standardized.

🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` at line 91, Update the pzemdc.md
documentation to clarify the differing UART "stop_bits" values: add a short note
next to the pzemdc component example (the native pzemdc example using stop_bits:
2) and next to the Modbus alternative example (the Modbus-over-UART example
using stop_bits: 1) stating that both settings are correct for their respective
methods — the native pzemdc driver expects 2 stop bits, while the
Modbus-over-UART configuration typically uses 1 stop bit — and include a
one-line rationale that the native driver and Modbus protocol expect different
UART framing so users should keep the stop_bits as shown for each method.

Comment on lines +202 to +206
- {{< docref "/components/uart" >}}
- {{< docref "/components/modbus" >}}
- {{< docref "/components/modbus_controller" >}}
- {{< docref "/components/sensor/modbus_controller" >}}
- {{< docref "/components/sensor/total_daily_energy" >}}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Replace legacy Hugo shortcodes with standard Markdown links.

These lines use the legacy {{< docref >}} shortcode, which should be replaced with standard Markdown link syntax. As per coding guidelines, Hugo shortcode {{< docref >}} is legacy and should be replaced with standard Markdown links.

🔄 Proposed fix
-- {{< docref "/components/uart" >}}
-- {{< docref "/components/modbus" >}}
-- {{< docref "/components/modbus_controller" >}}
-- {{< docref "/components/sensor/modbus_controller" >}}
-- {{< docref "/components/sensor/total_daily_energy" >}}
+- [UART](/components/uart)
+- [Modbus](/components/modbus)
+- [Modbus Controller](/components/modbus_controller)
+- [Modbus Controller Sensor](/components/sensor/modbus_controller)
+- [Total Daily Energy](/components/sensor/total_daily_energy)
📝 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.

Suggested change
- {{< docref "/components/uart" >}}
- {{< docref "/components/modbus" >}}
- {{< docref "/components/modbus_controller" >}}
- {{< docref "/components/sensor/modbus_controller" >}}
- {{< docref "/components/sensor/total_daily_energy" >}}
- [UART](/components/uart)
- [Modbus](/components/modbus)
- [Modbus Controller](/components/modbus_controller)
- [Modbus Controller Sensor](/components/sensor/modbus_controller)
- [Total Daily Energy](/components/sensor/total_daily_energy)
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` around lines 202 - 206, Replace the
legacy Hugo shortcodes in content/components/sensor/pzemdc.md (the instances of
{{< docref "/components/uart" >}}, {{< docref "/components/modbus" >}}, {{<
docref "/components/modbus_controller" >}}, {{< docref
"/components/sensor/modbus_controller" >}}, and {{< docref
"/components/sensor/total_daily_energy" >}}) with standard Markdown links; for
each shortcode use [display text](path) — e.g. replace {{< docref
"/components/uart" >}} with [Components: UART](/components/uart) (or a concise
human-friendly label you prefer) and do the same for the other four shortcodes,
ensuring the link paths match the quoted paths and the display text is clear and
consistent.

Copy link
Author

@autox86 autox86 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

🤖 Fix all issues with AI agents
In `@content/components/sensor/pzemdc.md`:
- Line 98: Update the YAML comment "#Lets intiate the Modbus Controller:" to
correct spelling and punctuation by changing it to "#Let's initiate the Modbus
Controller:" so the contraction and the verb are correct.
- Line 93: Update the YAML/Markdown comment string "#Lets define the modbus to
use:" to use the correct contraction with an apostrophe; change the text to
"#Let's define the modbus to use:" so the comment reads correctly. Reference the
existing comment line "#Lets define the modbus to use:" in
content/components/sensor/pzemdc.md to locate and update it.
- Line 188: Update the inline YAML comment that currently reads "//additionally
lets zero all sensors as the device is offline" to use the correct contraction
by replacing "lets" with "let's" (i.e., "//additionally let's zero all sensors
as the device is offline") so the comment is grammatically correct.
- Line 84: Update the YAML comment string "Where is the modbus hardware connect
to?" to the correct grammar "Where is the modbus hardware connected to?" in the
sensor/pzemdc.md content (locate the comment text itself to change).
- Line 173: Replace the hyphenated phrase "off- or online" with "offline or
online" in the Scenario sentence that references the binary sensor id
bs_pzem_online so it reads: "A binary sensor (id: bs_pzem_online) shall indicate
if the device is offline or online."
- Around line 80-81: Replace the unclear introductory sentence that starts
"While its own component is great working for a basic setup, you may want to
have more possibilities while using modbus controller." with a clearer phrasing;
update it to something like: "The native component works great for basic setups,
but you may want more flexibility when using the Modbus controller." Ensure
"Modbus" is capitalized and the sentence flow is corrected in the pzemdc.md
introductory paragraph.
- Line 181: Replace the grammatically incorrect YAML comment "Also possible
writing it in lambdas:" with a corrected phrasing such as "Also possible to
write it using lambdas:" (or "Also possible to write it with lambdas:") so the
comment is clear; locate the exact comment string "Also possible writing it in
lambdas:" in the sensor/pzemdc.md content and update it accordingly.
- Around line 172-174: Add blank lines before and after the heading
"`on_offline` and `on_online` Action" and also ensure there is a blank line
immediately before the fenced code block starting with "```yaml" and one after
the closing "```" so the heading and code block are separated from surrounding
text; edit the markdown around the heading and the fenced code block in
content/components/sensor/pzemdc.md to insert those blank lines.

Comment on lines +80 to +81
While its own component is great working for a basic setup, you may want to have more possibilities while using modbus controller.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Improve grammar and clarity of the introductory paragraph.

The text has grammatical issues and unclear phrasing:

  • "its own component is great working" should be "its own component works great" or "the native component is great"
  • "more possibilities while using modbus controller" should be "more flexibility when using the modbus controller"
📝 Proposed fix
-While its own component is great working for a basic setup, you may want to have more possibilities while using modbus controller.
+While the native component works great for basic setups, you may want more flexibility when using the modbus controller.
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` around lines 80 - 81, Replace the
unclear introductory sentence that starts "While its own component is great
working for a basic setup, you may want to have more possibilities while using
modbus controller." with a clearer phrasing; update it to something like: "The
native component works great for basic setups, but you may want more flexibility
when using the Modbus controller." Ensure "Modbus" is capitalized and the
sentence flow is corrected in the pzemdc.md introductory paragraph.


### Example Config
```yaml
#Where is the modbus hardware connect to?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix grammatical error in YAML comment.

The comment "Where is the modbus hardware connect to?" has a grammatical error. It should be "connected to" instead of "connect to".

📝 Proposed fix
-#Where is the modbus hardware connect to?
+#Where is the modbus hardware connected to?
📝 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.

Suggested change
#Where is the modbus hardware connect to?
`#Where` is the modbus hardware connected to?
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` at line 84, Update the YAML comment
string "Where is the modbus hardware connect to?" to the correct grammar "Where
is the modbus hardware connected to?" in the sensor/pzemdc.md content (locate
the comment text itself to change).

stop_bits: 1
parity: NONE

#Lets define the modbus to use:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix apostrophe in YAML comment.

"Lets" should be "Let's" (contraction of "let us").

📝 Proposed fix
-#Lets define the modbus to use:
+#Let's define the modbus to use:
📝 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.

Suggested change
#Lets define the modbus to use:
`#Let`'s define the modbus to use:
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` at line 93, Update the YAML/Markdown
comment string "#Lets define the modbus to use:" to use the correct contraction
with an apostrophe; change the text to "#Let's define the modbus to use:" so the
comment reads correctly. Reference the existing comment line "#Lets define the
modbus to use:" in content/components/sensor/pzemdc.md to locate and update it.

uart_id: modbus_uart
id: my_modbus

#Lets intiate the Modbus Controller:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix spelling and apostrophe in YAML comment.

The comment has two errors: "Lets" should be "Let's", and "intiate" should be "initiate".

📝 Proposed fix
-#Lets intiate the Modbus Controller:
+#Let's initiate the Modbus Controller:
📝 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.

Suggested change
#Lets intiate the Modbus Controller:
`#Let`'s initiate the Modbus Controller:
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` at line 98, Update the YAML comment
"#Lets intiate the Modbus Controller:" to correct spelling and punctuation by
changing it to "#Let's initiate the Modbus Controller:" so the contraction and
the verb are correct.

```

### `on_offline` and `on_online` Action
Scenario: A binary sensor (id: bs_pzem_online) shall indicate if the device is off- or online.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix hyphenation in sentence.

"off- or online" should be "offline or online" without the awkward hyphen.

📝 Proposed fix
-Scenario: A binary sensor (id: bs_pzem_online) shall indicate if the device is off- or online.
+Scenario: A binary sensor (id: bs_pzem_online) shall indicate if the device is offline or online.
📝 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.

Suggested change
Scenario: A binary sensor (id: bs_pzem_online) shall indicate if the device is off- or online.
Scenario: A binary sensor (id: bs_pzem_online) shall indicate if the device is offline or online.
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` at line 173, Replace the hyphenated
phrase "off- or online" with "offline or online" in the Scenario sentence that
references the binary sensor id bs_pzem_online so it reads: "A binary sensor
(id: bs_pzem_online) shall indicate if the device is offline or online."

id: bs_pzem_online
state: ON

#Also possible writing it in lambdas:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix grammar in YAML comment.

The comment "Also possible writing it in lambdas:" is grammatically incorrect.

📝 Proposed fix
-#Also possible writing it in lambdas:
+#It's also possible to write it in lambdas:
📝 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.

Suggested change
#Also possible writing it in lambdas:
`#It`'s also possible to write it in lambdas:
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` at line 181, Replace the grammatically
incorrect YAML comment "Also possible writing it in lambdas:" with a corrected
phrasing such as "Also possible to write it using lambdas:" (or "Also possible
to write it with lambdas:") so the comment is clear; locate the exact comment
string "Also possible writing it in lambdas:" in the sensor/pzemdc.md content
and update it accordingly.

ESP_LOGW("pzem_hub", "Controller: Device is offline, zero'ing all sensors");
id(bs_pzem_online).publish_state(false);

//additionally lets zero all sensors as the device is offline
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix apostrophe in YAML comment.

"lets" should be "let's" (contraction of "let us").

📝 Proposed fix
-            //additionally lets zero all sensors as the device is offline
+            //additionally let's zero all sensors as the device is offline
📝 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.

Suggested change
//additionally lets zero all sensors as the device is offline
//additionally let's zero all sensors as the device is offline
🤖 Prompt for AI Agents
In `@content/components/sensor/pzemdc.md` at line 188, Update the inline YAML
comment that currently reads "//additionally lets zero all sensors as the device
is offline" to use the correct contraction by replacing "lets" with "let's"
(i.e., "//additionally let's zero all sensors as the device is offline") so the
comment is grammatically correct.

Copy link
Author

@autox86 autox86 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

check2

uart:
- id: modbus_uart
tx_pin: gpio03
rx_pin: gpio01
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we don't specify concrete GPIO pin numbers, because they are user-dependent

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks so much @nagyrobi
I modified the documentation.

Updated UART pin configuration to be user-defined.
Copy link
Author

@autox86 autox86 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kindly check.
Removed gpio pin and added # user-defined GPIO pin

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

Comments