Add host shell command helper #5830
Conversation
Added documentation for executing shell commands on the host.
![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 👍 |
esphome
bot
dismissed
their stale review
Base branch has been corrected - dismissing previous review.
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughThis PR updates ESPHome documentation across multiple components, introducing new features and standardizing type annotations. Changes include adding UART event documentation, expanding deep sleep for BK72xx multi-pin wakeup support, standardizing frequency parameter type annotations from float/int to frequency across ~11 components, clarifying platform-specific references from esp-idf to ESP32, documenting new capabilities (ESP32 OTA rollback, hub75 brightness action, update check action), and refactoring the release notes generation script to improve PR collection logic. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
content/components/sensor/ade7880.md (1)
270-270: Fix syntax error in YAML example.Line 270 has a double colon that will cause YAML parsing errors.
🔎 Proposed fix
- active_power:: Active Power + active_power: Active Power
🧹 Nitpick comments (2)
content/components/host.md (2)
40-50: LGTM - Good security warning, consider toning down exclamation marks.The documentation clearly explains the
execute_shell_commandfeature and includes an important warning about commands needing to finish. The static analysis hint about excessive exclamation marks (line 48-49) is valid but minor for documentation.Suggested minor wording adjustment
> [!NOTE] -> Commands will be ran with the same privileges as the ESPHome binary. Take extra care for the commands to finish! Running a -> command that never exits will lock up the ESPHome binary too. +> Commands will run with the same privileges as the ESPHome binary. Take extra care to ensure the commands finish. Running a +> command that never exits will lock up the ESPHome binary.
77-94: Consider adding a security note for the arbitrary command example.This example demonstrates executing commands from user-controlled text input. While useful, it could be a security risk if the text entity is exposed via the API without proper access controls. Consider adding a brief security note.
Suggested addition after line 94
mode: text + +> [!WARNING] +> The above example executes arbitrary commands from user input. Ensure proper access controls are in place if exposing such functionality via the Home Assistant API.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (32)
content/components/_index.mdcontent/components/at581x.mdcontent/components/canbus/mcp2515.mdcontent/components/deep_sleep.mdcontent/components/display/hub75.mdcontent/components/esp32.mdcontent/components/esp32_camera.mdcontent/components/event/uart.mdcontent/components/host.mdcontent/components/http_request.mdcontent/components/i2c.mdcontent/components/libretiny.mdcontent/components/mqtt.mdcontent/components/output/esp8266_pwm.mdcontent/components/output/ledc.mdcontent/components/output/libretiny_pwm.mdcontent/components/output/pca9685.mdcontent/components/packet_transport/sx126x.mdcontent/components/packet_transport/sx127x.mdcontent/components/sensor/ade7880.mdcontent/components/sensor/hm3301.mdcontent/components/sensor/mmc5603.mdcontent/components/sensor/pmsx003.mdcontent/components/servo.mdcontent/components/speaker/resampler.mdcontent/components/spi.mdcontent/components/sprinkler.mdcontent/components/sx126x.mdcontent/components/sx127x.mdcontent/components/update/_index.mddata/version.yamlscript/generate_release_notes.py
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
content/components/servo.mdcontent/components/sensor/pmsx003.mdcontent/components/output/pca9685.mdcontent/components/at581x.mddata/version.yamlcontent/components/host.mdcontent/components/spi.mdcontent/components/esp32.mdcontent/components/sensor/mmc5603.mdcontent/components/sensor/hm3301.mdcontent/components/mqtt.mdcontent/components/canbus/mcp2515.mdcontent/components/deep_sleep.mdcontent/components/output/libretiny_pwm.mdcontent/components/http_request.mdcontent/components/sx127x.mdcontent/components/packet_transport/sx126x.mdcontent/components/output/esp8266_pwm.mdcontent/components/_index.mdcontent/components/event/uart.mdcontent/components/i2c.mdcontent/components/speaker/resampler.mdcontent/components/esp32_camera.mdcontent/components/display/hub75.mdcontent/components/sprinkler.mdcontent/components/libretiny.mdcontent/components/sensor/ade7880.mdcontent/components/update/_index.mdcontent/components/sx126x.mdcontent/components/packet_transport/sx127x.mdscript/generate_release_notes.pycontent/components/output/ledc.md
🧠 Learnings (1)
📚 Learning: 2025-12-14T20:08:13.374Z
Learnt from: danielkent-net
Repo: esphome/esphome-docs PR: 5778
File: content/components/sensor/bmp581.md:10-12
Timestamp: 2025-12-14T20:08:13.374Z
Learning: In ESPHome docs, when listing sensors that support both I2C and SPI interfaces, use separate platform names with _i2c and _spi suffixes (e.g., bmp280_i2c and bmp280_spi; bmp3xx_i2c and bmp3xx_spi; bmp581_i2c and bmp581_spi). This naming convention is established and should not be flagged as incorrect. Apply this pattern across sensor documentation files under content/components/sensor and ensure examples reflect both suffix variants where applicable.
Applied to files:
content/components/sensor/pmsx003.mdcontent/components/sensor/mmc5603.mdcontent/components/sensor/hm3301.mdcontent/components/sensor/ade7880.md
🪛 LanguageTool
content/components/sensor/pmsx003.md
[style] ~143-~143: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... | 101-400 | Very High | Air quality is very poor | ### Configuration Example ```yaml s...
(EN_WEAK_ADJECTIVE)
content/components/host.md
[style] ~48-~48: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 2140 characters long)
Context: ...ke extra care for the commands to finish! Running a > command that never exits wi...
(EN_EXCESSIVE_EXCLAMATION)
content/components/esp32.md
[style] ~157-~157: ‘in conjunction with’ might be wordy. Consider a shorter alternative.
Context: ...t is marked as successful. This works in conjunction with the safe_mode ...
(EN_WORDINESS_PREMIUM_IN_CONJUNCTION_WITH)
content/components/sensor/hm3301.md
[style] ~86-~86: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... | 101-400 | Very High | Air quality is very poor | ### Configuration Example ```yaml s...
(EN_WEAK_ADJECTIVE)
content/components/deep_sleep.md
[grammar] ~51-~51: Ensure spelling is correct
Context: ...n): Only on ESP32. Use a touch event to wakeup from deep sleep. To be able to wakeup...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~52-~52: Ensure spelling is correct
Context: ...wakeup from deep sleep. To be able to wakeup from a touch event, [Binary Sensor](/co...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
content/components/http_request.md
[style] ~35-~35: To form a complete sentence, be sure to include a subject.
Context: ...eout during connection/data transfer. May be useful on slow connections or connec...
(MISSING_IT_THERE)
content/components/sprinkler.md
[style] ~229-~229: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...nsist of one valve per zone, it becomes very important for systems with some additional comple...
(EN_WEAK_ADJECTIVE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build
🔇 Additional comments (42)
content/components/update/_index.md (1)
60-66: Documentation addition looks good.The new
update.checkAction section is well-structured, clearly describes its purpose, and properly documents the required configuration variable. It follows the established documentation patterns in the file and provides a useful distinction from theupdate.performaction.content/components/sprinkler.md (8)
178-181: Clear update to pump_switch_id documentation with H-Bridge reference.The documentation now correctly directs users to H-Bridge switches for latching valves and includes an important note about not exposing these switches to the front end. The anchor link reference is appropriate given the detailed explanatory section below.
198-201: Consistent update to valve_switch_id documentation with H-Bridge reference.Mirrors the pump_switch_id update appropriately, maintaining parallel documentation structure for both switch types.
207-224: Well-articulated explanation of switch architecture and design rationale.The rewrite clearly distinguishes between the sprinkler controller's zone switches (user-facing) and the underlying hardware switches (H-Bridge/GPIO), explaining why direct manipulation of underlying switches is inadvisable. The state management rationale is comprehensive and includes concrete failure scenarios.
226-243: Strong summary section with practical configuration guidance.The section effectively reinforces the architectural pattern with a concrete coordinated pump/valve example and provides clear configuration options (
name:vsinternal: true) for preventing accidental exposure of underlying switches.
609-609: Board identifier updates are consistent and appropriate.The switch from
featheresp32to the more standardesp32devidentifier is applied consistently across all example configurations. This change improves usability for broader audience compatibility.Also applies to: 639-639, 690-690, 751-751, 817-817
738-740: Clear explanation of latching valve operation with H-Bridge reference.The documentation correctly explains the two-pin requirement for latching valves and appropriately references the H-Bridge switch component for this use case.
769-803: Complete and consistent H-Bridge switch configuration example.The example correctly demonstrates the platform switch from GPIO to H-Bridge, with all IDs properly matched between the sprinkler configuration and switch definitions. The
pulse_length: 250msis a sensible default for latching valve actuation pulses.To ensure the example is fully self-contained, please verify that the meaning and role of
pulse_lengthis documented in either the configuration variables section or the H-Bridge switch component documentation that users will reference.
973-974: Clear clarification of non-extendable switch references.The update correctly notes that
pump_switch_idandvalve_switch_idare references to separately-defined switches and therefore cannot be extended inline, maintaining the documented architectural separation.content/components/packet_transport/sx127x.md (1)
26-26: LGTM! Frequency formatting improved.The update to human-readable frequency notation (433.92MHz) improves documentation clarity while maintaining accuracy.
content/components/servo.md (1)
38-38: LGTM! Formatting standardized.The removal of the space between value and unit (50Hz) aligns with frequency formatting consistency across the documentation.
content/components/canbus/mcp2515.md (1)
48-49: LGTM! Type description clarified.Correctly identifying the
clockfield as an enum (rather than a generic frequency) better reflects that only specific predefined crystal frequencies are supported.data/version.yaml (1)
1-2: LGTM! Version bump for new release cycle.The version update to 2026.1.0-dev follows the expected versioning pattern for the new development cycle.
content/components/display/hub75.md (1)
309-326: LGTM! Well-documented action addition.The new
hub75.set_brightnessaction documentation is clear and follows ESPHome documentation conventions. The brightness range (0-255) and behavior are well-explained.content/components/_index.md (1)
806-806: LGTM! New component index entry added.The UART Event entry is properly formatted and placed in the Event Components section, consistent with other index entries.
content/components/speaker/resampler.md (1)
39-39: Address documentation inconsistency fortask_stack_in_psramqualifier.The removal of "Only with esp-idf." from this feature creates inconsistency:
speaker.md(media_player) also documents it without the qualifier, butmixer.mdstill includes "Only with esp-idf." Either all three components should have the qualifier for consistency, or all should omit it. Determine the correct platform scope for this feature and apply it uniformly across resampler.md, speaker.md, and mixer.md.content/components/esp32_camera.md (1)
60-61: The documentation is correct. The ESP32 external clock frequency range of 8MHz to 20MHz is supported by hardware and firmware. Web sources confirm that 8MHz and 10MHz are both supported frequencies (8MHz is used to trigger internal pixel-clock doublers in some sensors like OV2640), and 20MHz is the practical upper limit for stable operation on most modules.content/components/spi.md (1)
157-182: LGTM!The reframing of the limit from ESP-IDF-specific to ESP32-specific is appropriate and clearer, and the technical content about
release_deviceremains accurate.content/components/i2c.md (1)
42-44: LGTM!The type annotation change from
floattofrequencyis more semantically accurate and aligns with the broader documentation standardization across components.content/components/output/pca9685.md (1)
74-76: LGTM!The frequency type standardization, more precise lower bound (23.84Hz), and clearer default notation (1kHz) all represent improvements in documentation accuracy without changing functionality.
content/components/sensor/pmsx003.md (3)
44-46: LGTM!The AQI feature addition to the example is well-integrated and demonstrates the required
calculation_typefield.
96-101: LGTM!The configuration documentation clearly specifies the required
calculation_typefield and references the detailed section below.
109-163: LGTM!The Air Quality Index section is comprehensive with clear scale tables, standard explanations, and practical configuration examples including optional filters for value smoothing.
content/components/esp32.md (1)
155-163: LGTM!The
enable_ota_rollbackoption is well-documented with clear default behavior, interaction withsafe_mode, and an important note about bootloader requirements. The placement in Advanced Configuration is appropriate.content/components/sensor/hm3301.md (1)
52-105: LGTM!The AQI/CAQI expansion provides consistent documentation with clear scale tables and practical examples. The different filter window size (10 vs 15 in pmsx003) appears intentional for the different sensor type.
content/components/sensor/ade7880.md (1)
72-74: LGTM!The frequency type change to
frequencyis consistent with other components, and the 45-66Hz range properly covers both standard AC frequencies (50Hz/60Hz) with appropriate margins.content/components/event/uart.md (1)
1-39: LGTM!The UART event documentation is well-structured with clear examples demonstrating both string and byte patterns, and important guidance about avoiding prefix collisions. Configuration variables are well-documented.
content/components/deep_sleep.md (1)
96-113: LGTM - Clear BK72xx examples.The new YAML examples effectively demonstrate both single-pin and multi-pin wakeup configurations for BK72xx, with clear inline comments explaining the behavior of each option.
content/components/sensor/mmc5603.md (1)
53-59: LGTM - Clear documentation of auto_set_reset feature.The new
auto_set_resetconfiguration option is well-documented with a helpful note explaining the trade-off between temperature drift stability and maximum sampling rate.script/generate_release_notes.py (3)
372-407: LGTM - Good refactoring of PR collection logic.The new
_collect_prs_from_tagsmethod provides a clean, reusable abstraction for collecting PRs from a sequence of releases. The method signature is well-designed with clear parameters and the loop logic correctly breaks when a tag is not found.
409-442: LGTM - Correct implementation of previous release PR collection.The method correctly handles both beta and patch releases, with proper handling of the first beta (no previous tag to compare against). The set union cleanly combines results.
466-488: LGTM - Clean PR exclusion logic.The updated
discover_prsmethod correctly excludes PRs already included in previous release cycles, preventing duplicate entries in release notes. The informational logging about excluded PRs aids transparency.content/components/at581x.md (1)
140-140: LGTM - Clear enumeration of allowed frequency values.The documentation now clearly lists all valid frequency values (5696-5888 MHz range) and specifies the default of 5800MHz, improving user guidance.
content/components/packet_transport/sx126x.md (1)
26-26: LGTM - Improved frequency value readability.Using
433.92MHzinstead of the raw Hz value improves example readability while representing the same frequency.content/components/libretiny.md (1)
150-150: LGTM - Consistent frequency notation.Using
1kHzinstead of1000 Hzaligns with the standardized frequency notation used across the documentation.content/components/output/libretiny_pwm.md (1)
19-19: LGTM - Consistent frequency documentation updates.The frequency notation changes (
1kHzinstead of1000 Hz) and the type updates for theset_frequencyaction align with the standardized documentation patterns across the repository.Also applies to: 33-34, 55-56
content/components/output/esp8266_pwm.md (1)
20-20: ✓ Frequency standardization is consistent and well-executed.The changes to standardize frequency notation (1kHz), type annotation (frequency), and unit description (Hz) align well with the broader PR theme and improve documentation clarity and consistency.
Also applies to: 35-35, 63-64
content/components/sx126x.md (1)
31-31: ✓ Frequency examples and type standardization are clear and well-aligned.The shift to human-readable frequency notation (433.92MHz), type standardization (frequency), and explicit defaults for deviation (5kHz) all improve documentation clarity and maintain consistency with related components like SX127x.
Also applies to: 49-49, 111-111, 216-216, 256-256
content/components/output/ledc.md (1)
20-21: ✓ Frequency standardization is consistent with other PWM components.The changes to frequency type (frequency), notation (1kHz, Hz), and action documentation align well with the standardization across esp8266_pwm and other PWM/output components in this PR.
Also applies to: 78-78, 100-102, 124-125
content/components/http_request.md (1)
32-32: ✓ Platform-specific terminology is clearer and more user-friendly.The shift from esp-idf/framework-specific language to ESP32-centric descriptions (e.g., "Supported on ESP32 only") improves clarity for users and aligns with the broader documentation modernization in this PR.
Also applies to: 39-39, 64-64
content/components/sx127x.md (1)
27-27: ✓ Frequency standardization is thorough and consistent across all examples.All frequency examples have been updated to human-readable notation (433.92MHz), the frequency type is standardized across configuration and action parameters, and the deviation default (5kHz) maintains alignment with the SX126x component. Changes improve clarity and usability.
Also applies to: 40-40, 110-110, 217-217, 254-254, 292-292, 320-320, 360-360
content/components/mqtt.md (1)
100-101: ✓ Platform-specific terminology is clear and consistently applied.The shift from framework-specific language (esp-idf) to platform-centric descriptions (ESP32) improves user comprehension. Capitalization is now consistent throughout (ESP32), and section headings are simplified while maintaining technical clarity. These changes align well with updates in http_request.md and support the broader documentation modernization.
Also applies to: 108-108, 111-111, 39-39, 390-390, 392-393
Added comments to clarify the purpose of each template button.
Added links for UART and Time Source configuration when using host.
Updated documentation for host platform usage, including notes on network configuration, shell command execution, and binary retrieval.
Clarify instructions for retrieving the binary on Linux.
Updated shell commands for retrieving and copying the binary on Linux.
Removed duplicate docref entries from host.md
Clarify command execution behavior in ESPHome.
Add error handling for parsing load average
Added information about shell command privileges and provisioning requirements.
Added note about setting logger level to INFO for deployment.
Rearranged the YAML configuration for text sensors to ensure 'host_model' is defined correctly.
Updated the documentation to clarify the usage of ESPHome on a Debian system, including additional sensor configurations for hostname and free disk space.
Clarify the note about the LC_NUMERIC environment variable and adjust section header.
Updated wording for clarity and consistency in the documentation regarding shell commands, lambdas, and sensor updates.
Updated the description for the host example and clarified the timing explanation for the template switch.
|
We should also add warnings about passing untrusted input data to shell commands |
Co-authored-by: J. Nick Koston <[email protected]>
Add warning about unsandboxed access and recommend disabling reboot_timeout.
Added warning about command execution with external input.
Added template sensors for NIC eno1 download and upload rates, along with logic to calculate and publish their states based on network traffic statistics.
3 participants
Description:
Add ability to run shell commands on the host through lambdas, and capture stdout, stderr, exitcode in variables; optionally sett shelly type and envvars.
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.mdwhen 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 lower_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
/static/images/folder of this repository.Use the image in your component's index table entry in
/components/_index.md.Example: For a component called "DHT22 Temperature Sensor", use: