diff --git a/.gitattributes b/.gitattributes
index 11a6b0680f..f6569e6af9 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -7,3 +7,4 @@
*.mp3 binary
*.gif binary
*.avif binary
+*.webp binary
diff --git a/public/images/hdc302x.svg b/public/images/hdc302x.svg
new file mode 100644
index 0000000000..81076791ac
--- /dev/null
+++ b/public/images/hdc302x.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/public/images/sen6x.webp b/public/images/sen6x.webp
new file mode 100644
index 0000000000..97871443fc
Binary files /dev/null and b/public/images/sen6x.webp differ
diff --git a/script/generate_release_notes.py b/script/generate_release_notes.py
index 87abbe6dae..215e4a1979 100755
--- a/script/generate_release_notes.py
+++ b/script/generate_release_notes.py
@@ -88,6 +88,7 @@
LABEL_BREAKING_CHANGE = "breaking-change"
LABEL_NEW_FEATURE = "new-feature"
LABEL_NEW_COMPONENT = "new-component"
+LABEL_UNDOCUMENTED_API_CHANGE = "undocumented-api-change"
@dataclass
@@ -567,6 +568,9 @@ def generate_prompts(self, prs: list[PullRequest]) -> None:
breaking_changes = [pr for pr in prs if LABEL_BREAKING_CHANGE in pr.labels]
new_features = [pr for pr in prs if LABEL_NEW_FEATURE in pr.labels]
new_components = [pr for pr in prs if LABEL_NEW_COMPONENT in pr.labels]
+ undocumented_api_changes = [
+ pr for pr in prs if LABEL_UNDOCUMENTED_API_CHANGE in pr.labels
+ ]
# Generate Combined Overview + Feature Highlights Prompt
overview_and_highlights_prompt = self._generate_overview_and_highlights_prompt(
@@ -575,13 +579,13 @@ def generate_prompts(self, prs: list[PullRequest]) -> None:
overview_highlights_file = self.prompts_dir / "overview_and_highlights.txt"
overview_highlights_file.write_text(overview_and_highlights_prompt)
- # Generate Combined Breaking Changes Prompt (user + developer)
- if breaking_changes:
- breaking_prompt = self._generate_combined_breaking_changes_prompt(
- breaking_changes
- )
- breaking_file = self.prompts_dir / "breaking_changes.txt"
- breaking_file.write_text(breaking_prompt)
+ # Generate Breaking Changes + Upgrade Checklist + Undocumented API Changes Prompt
+ # Always generated because the Upgrade Checklist is always needed
+ breaking_prompt = self._generate_breaking_changes_and_checklist_prompt(
+ breaking_changes, undocumented_api_changes, prs
+ )
+ breaking_file = self.prompts_dir / "breaking_changes.txt"
+ breaking_file.write_text(breaking_prompt)
# Print instructions
print("\n" + "=" * 80)
@@ -590,21 +594,24 @@ def generate_prompts(self, prs: list[PullRequest]) -> None:
print("\nStart Claude Code CLI and read the prompt files:\n")
print(" claude")
print(f" > Please read {overview_highlights_file} and follow the instructions")
- if breaking_changes:
- print(f" > Please read {breaking_file} and follow the instructions")
+ print(f" > Please read {breaking_file} and follow the instructions")
print("\nPrompt 1: Overview + Feature Highlights (COMBINED)")
print(f" Prompt: {overview_highlights_file}")
print(f" Outputs: {self.responses_dir / 'release_overview.md'}")
print(f" {self.responses_dir / 'feature_highlights.md'}")
- if breaking_changes:
- print("\nPrompt 2: Breaking Changes - Users + Developers (COMBINED)")
- print(f" Prompt: {breaking_file}")
- print(f" Outputs: {self.responses_dir / 'breaking_changes_users.md'}")
- print(f" {self.responses_dir / 'breaking_changes_developers.md'}")
+ print(
+ "\nPrompt 2: Breaking Changes + Upgrade Checklist + Undocumented API Changes"
+ )
+ print(f" Prompt: {breaking_file}")
+ print(f" Outputs: {self.responses_dir / 'breaking_changes_users.md'}")
+ print(f" {self.responses_dir / 'breaking_changes_developers.md'}")
+ print(f" {self.responses_dir / 'upgrade_checklist.md'}")
+ if undocumented_api_changes:
+ print(f" {self.responses_dir / 'undocumented_api_changes.md'}")
- print("\nNote: Each prompt will generate TWO output files automatically.")
+ print("\nNote: Each prompt will generate multiple output files automatically.")
print("\n" + "=" * 80)
print("STEP 2: Assemble the changelog")
@@ -654,18 +661,25 @@ def _generate_overview_and_highlights_prompt(
breaking_changes=breaking_changes,
)
- def _generate_combined_breaking_changes_prompt(
- self, breaking_prs: list[PullRequest]
+ def _generate_breaking_changes_and_checklist_prompt(
+ self,
+ breaking_prs: list[PullRequest],
+ undocumented_api_prs: list[PullRequest],
+ all_prs: list[PullRequest],
) -> str:
- """Generate combined prompt for both user and developer breaking changes"""
+ """Generate prompt for breaking changes, upgrade checklist, and undocumented API changes"""
template = self.jinja_env.get_template("breaking_changes.txt")
return template.render(
version=str(self.version),
users_file=self.responses_dir / "breaking_changes_users.md",
devs_file=self.responses_dir / "breaking_changes_developers.md",
+ checklist_file=self.responses_dir / "upgrade_checklist.md",
+ undocumented_file=self.responses_dir / "undocumented_api_changes.md",
prs_cache_dir=self.prs_cache_dir,
breaking_changes=breaking_prs,
+ undocumented_api_changes=undocumented_api_prs,
+ all_prs=all_prs,
)
def assemble_changelog(self) -> bool:
@@ -731,6 +745,16 @@ def assemble_changelog(self) -> bool:
if highlights_file.exists():
highlights = highlights_file.read_text().strip()
+ upgrade_checklist_file = self.responses_dir / "upgrade_checklist.md"
+ upgrade_checklist = ""
+ if upgrade_checklist_file.exists():
+ upgrade_checklist = upgrade_checklist_file.read_text().strip()
+
+ undocumented_api_file = self.responses_dir / "undocumented_api_changes.md"
+ undocumented_api = ""
+ if undocumented_api_file.exists():
+ undocumented_api = undocumented_api_file.read_text().strip()
+
# Load the PR numbers for this version from a manifest file
manifest_file = self.version_dir / "pr_numbers.txt"
if not manifest_file.exists():
@@ -754,6 +778,11 @@ def assemble_changelog(self) -> bool:
# Replace AI-generated sections
template = self._replace_marker_content(template, "RELEASE_OVERVIEW", overview)
+ if upgrade_checklist:
+ template = self._replace_marker_content(
+ template, "UPGRADE_CHECKLIST", upgrade_checklist
+ )
+
if highlights:
template = self._replace_marker_content(
template, "FEATURE_HIGHLIGHTS", highlights
@@ -764,6 +793,11 @@ def assemble_changelog(self) -> bool:
template, "BREAKING_CHANGES_USERS", breaking_users
)
+ if undocumented_api:
+ template = self._replace_marker_content(
+ template, "UNDOCUMENTED_API_CHANGES", undocumented_api
+ )
+
if breaking_devs:
template = self._replace_marker_content(
template, "BREAKING_CHANGES_DEVELOPERS", breaking_devs
@@ -828,11 +862,15 @@ def _generate_auto_sections(self, template: str, prs: list[PullRequest]) -> str:
new_features = [pr for pr in prs if "new-feature" in pr.labels]
new_components = [pr for pr in prs if "new-component" in pr.labels]
breaking_changes = [pr for pr in prs if "breaking-change" in pr.labels]
+ undocumented_api_changes = [
+ pr for pr in prs if "undocumented-api-change" in pr.labels
+ ]
# Generate lists
features_list = self._format_pr_list(new_features)
components_list = self._format_pr_list(new_components)
breaking_list = self._format_pr_list(breaking_changes)
+ undocumented_list = self._format_pr_list(undocumented_api_changes)
all_list = self._format_pr_list(prs)
# Replace sections
@@ -845,6 +883,11 @@ def _generate_auto_sections(self, template: str, prs: list[PullRequest]) -> str:
template = self._replace_marker_content(
template, "AUTO_GENERATED_BREAKING_CHANGES_LIST", breaking_list
)
+ template = self._replace_marker_content(
+ template,
+ "AUTO_GENERATED_UNDOCUMENTED_API_CHANGES_LIST",
+ undocumented_list,
+ )
return self._replace_marker_content(
template, "AUTO_GENERATED_ALL_CHANGES", all_list
)
diff --git a/script/prompt_templates/breaking_changes.txt b/script/prompt_templates/breaking_changes.txt
index 6834a019a4..4913c9740d 100644
--- a/script/prompt_templates/breaking_changes.txt
+++ b/script/prompt_templates/breaking_changes.txt
@@ -1,16 +1,23 @@
-SAVE YOUR RESPONSES TO TWO FILES:
+SAVE YOUR RESPONSES TO THESE FILES:
1. User-Facing Breaking Changes: {{ users_file }}
2. Developer-Facing Breaking Changes: {{ devs_file }}
+ 3. Upgrade Checklist: {{ checklist_file }}
+{% if undocumented_api_changes %}
+ 4. Undocumented API Changes: {{ undocumented_file }}
+{% endif %}
NOTE: The output files and directories may not exist yet - that's fine, create them.
You can use: Write tool with the full path, or create directories first if needed.
════════════════════════════════════════════════════════════════════════════════
-TASK: Write BOTH User and Developer Breaking Changes for ESPHome {{ version }}.
+TASK: Write Breaking Changes, Upgrade Checklist,
+{%- if undocumented_api_changes %} Undocumented API Changes,{% endif %} for ESPHome {{ version }}.
WHY COMBINED: These must be written together so you can properly categorize each change as
-user-facing (YAML config changes) or developer-facing (C++ API changes) without duplication.
+user-facing (YAML config changes) or developer-facing (C++ API changes) without duplication,
+and generate a comprehensive upgrade checklist from both breaking changes and undocumented
+API changes.
════════════════════════════════════════════════════════════════════════════════
PART 1: USER-FACING BREAKING CHANGES (save to {{ users_file }})
@@ -76,10 +83,89 @@ OUTPUT FORMAT FOR DEVELOPER CHANGES:
- Very brief descriptions
- Link to developers.esphome.io at the end
+════════════════════════════════════════════════════════════════════════════════
+PART 3: UPGRADE CHECKLIST (save to {{ checklist_file }})
+════════════════════════════════════════════════════════════════════════════════
+
+CONTEXT:
+A concise, actionable checklist for users upgrading to ESPHome {{ version }}.
+This checklist is generated from breaking changes, undocumented API changes, and any other
+PRs that may require user action.
+It appears near the top of the release notes, right after the Release Overview.
+
+AUDIENCE: ESPHome users who want a quick scan of what might affect them
+
+STYLE EXAMPLE from ESPHome 2026.2.0:
+
+- If you use `bmp581`, update your configuration to use `bmp581_i2c` as the platform
+- If you use `on_open` in cover automations, rename it to `on_opened`
+- If you have DSMR `fw_core_version` or `fw_module_version` under `sensor:`, move them to `text_sensor:`
+- If you call Arduino library APIs directly in lambdas (e.g., `Preferences`, `WiFi`), add them to `esphome: libraries:`
+- If you connect to HTTPS servers using uncommon CAs, add `use_full_certificate_bundle: true` under `esp32: framework: advanced:`
+- If you use BL0942 sensors, expect readings to change after recalibration to match corrected reference values
+
+INSTRUCTIONS:
+
+1. **Every item starts with "If you..."** followed by a concise condition and action
+2. **Include items from breaking changes, undocumented API changes, AND any other PRs that may require user action**
+3. **Order by impact** - most widely-affecting changes first
+4. **Be very concise** - one line per item, no code blocks, no PR links
+5. **Include lambda/API changes** if they affect users who write lambdas
+6. **Skip pure internal changes** that don't require any user action
+7. **Use backticks** for config keys, component names, and code references
+8. If there are no changes requiring user action, write: "No action required for this upgrade."
+
+OUTPUT FORMAT FOR UPGRADE CHECKLIST:
+- Bullet points only (no headings)
+- Each starts with "- If you..."
+- One line per item
+- No PR links (those are in Breaking Changes)
+- Typically 3-10 items
+
+{% if undocumented_api_changes %}
+════════════════════════════════════════════════════════════════════════════════
+PART 4: UNDOCUMENTED API CHANGES (save to {{ undocumented_file }})
+════════════════════════════════════════════════════════════════════════════════
+
+CONTEXT:
+These are C++ API changes that are NOT covered by the formal breaking change policy because
+the APIs are internal/undocumented. However, they may affect users who write lambdas or
+developers who maintain external components.
+
+Per the ESPHome public API policy (https://developers.esphome.io/contributing/code/#c-user-expectations),
+undocumented public methods on components are not guaranteed to remain stable. However, lambda
+users often discover and depend on these methods, so we document the changes here.
+
+AUDIENCE: Advanced users with lambdas, external component developers
+
+STYLE EXAMPLE from ESPHome 2026.1.0 "Lambda API Changes":
+
+Users with lambdas that access component state should note the following changes. These methods now return `StringRef` instead of `const char*`, which is safer but requires minor syntax changes:
+
+- **Fan**: `get_preset_mode()` returns `StringRef`. Use `.empty()` instead of `!= nullptr` checks, and `==` for string comparison instead of `strcmp()`. [#13092](https://github.com/esphome/esphome/pull/13092)
+
+- **Select**: `current_option()` returns `StringRef`. Use `.empty()` instead of `!= nullptr` checks. [#13095](https://github.com/esphome/esphome/pull/13095)
+
+INSTRUCTIONS:
+
+1. **Group related changes together** if there's a common theme (e.g., return type changes)
+2. **Explain the change and how to migrate** - include before/after patterns
+3. **Use bullet points** with bold component/class names
+4. **Include PR links**: [#12345](https://github.com/esphome/esphome/pull/12345)
+5. **Skip changes already covered** in Parts 1 or 2 (breaking changes)
+6. **Focus on what lambda users need to know** - method renames, return type changes, removed methods
+
+OUTPUT FORMAT FOR UNDOCUMENTED API CHANGES:
+- Optional introductory paragraph explaining the theme
+- Bullet points with bold names and PR links
+- Before/after code patterns where helpful
+{% endif %}
+
────────────────────────────────────────────────────────────────────────────────
📁 PR DATA FILES - CRITICAL: You MUST read ALL of these files using the Read tool
────────────────────────────────────────────────────────────────────────────────
+{% if breaking_changes %}
BREAKING CHANGE PULL REQUESTS ({{ breaking_changes|length }} total):
⚠️ CRITICAL INSTRUCTIONS FOR LOADING PR DATA:
@@ -89,15 +175,41 @@ BREAKING CHANGE PULL REQUESTS ({{ breaking_changes|length }} total):
3. Do NOT assume you know the content - you must READ each file
4. Each JSON file contains: number, title, body (with migration details), author, labels, url
5. Read ALL files in parallel for efficiency, then analyze the complete data
-6. After reading: categorize each as user-facing or developer-facing, then write BOTH files
+6. After reading: categorize each as user-facing or developer-facing, then write ALL files
BREAKING CHANGE PR FILES - READ ALL {{ breaking_changes|length }} FILES:
{% for pr in breaking_changes %}
{{ prs_cache_dir }}/{{ pr.number }}.json
{% endfor %}
+{% endif %}
+
+{% if undocumented_api_changes %}
+UNDOCUMENTED API CHANGE PULL REQUESTS ({{ undocumented_api_changes|length }} total):
+
+These PRs have the "undocumented-api-change" label. They change internal C++ APIs that
+may affect lambda users or external component developers, but are NOT formal breaking changes.
+
+UNDOCUMENTED API CHANGE PR FILES - READ ALL {{ undocumented_api_changes|length }} FILES:
+{% for pr in undocumented_api_changes %}
+ {{ prs_cache_dir }}/{{ pr.number }}.json
+{% endfor %}
+{% endif %}
+
+ALL PULL REQUESTS ({{ all_prs|length }} total):
+
+Scan ALL PR titles below for any changes that might require user action but weren't labeled
+as breaking changes. Include these in the Upgrade Checklist if relevant.
+
+{% for pr in all_prs %}
+ #{{ pr.number }}: {{ pr.title }} (labels: {{ pr.labels|join(', ') }})
+{% endfor %}
────────────────────────────────────────────────────────────────────────────────
-⚠️ REMINDER: Read ALL files above, then write BOTH files:
+⚠️ REMINDER: Read ALL PR JSON files above, then write ALL output files:
1. User Changes: {{ users_file }} (### headings, detailed)
2. Developer Changes: {{ devs_file }} (bullet points, brief)
+ 3. Upgrade Checklist: {{ checklist_file }} (bullet points, "If you..." format)
+{% if undocumented_api_changes %}
+ 4. Undocumented API Changes: {{ undocumented_file }} (bullet points with migration guidance)
+{% endif %}
────────────────────────────────────────────────────────────────────────────────
diff --git a/script/release_notes_template.md b/script/release_notes_template.md
index 64eddeacaf..3d7fef77a0 100644
--- a/script/release_notes_template.md
+++ b/script/release_notes_template.md
@@ -29,6 +29,16 @@ import ImgTable from '@components/ImgTable.astro';
-->
+## Upgrade Checklist
+
+
+
+
+
+### Undocumented API Changes
+
+
+
+
+
### Breaking Changes for Developers
@@ -114,6 +143,12 @@ import ImgTable from '@components/ImgTable.astro';
+### Undocumented API Changes
+
+
+
+
+
### All changes
diff --git a/src/content/docs/components/binary_sensor/esp32_touch.mdx b/src/content/docs/components/binary_sensor/esp32_touch.mdx
index 3afb02545b..120c7d4ca2 100644
--- a/src/content/docs/components/binary_sensor/esp32_touch.mdx
+++ b/src/content/docs/components/binary_sensor/esp32_touch.mdx
@@ -8,7 +8,7 @@ import esp32TouchUiImg from './images/esp32_touch-ui.png';
import esp32TouchFindingThresholdsImg from './images/esp32_touch-finding_thresholds.png';
import APIRef from '@components/APIRef.astro';
-Capacitive touch detection is possible on ESP32, ESP32-S2 or ESP32-S3 processors.
+Capacitive touch detection is possible on ESP32, ESP32-S2, ESP32-S3 and ESP32-P4 processors.
In ESPHome, it is configured in two parts:
- [Component/Hub](#esp32-touch-component)
@@ -19,7 +19,7 @@ In ESPHome, it is configured in two parts:
## Component/Hub
The `esp32_touch` component creates a global hub enabling (capacitive) touch detection on GPIO pins
-[supported by ESP32, ESP32-S2 or ESP32-S3 processors](#esp32-touch-pad-pins). With this enabled,
+[supported by ESP32, ESP32-S2, ESP32-S3 and ESP32-P4 processors](#esp32-touch-pad-pins). With this enabled,
[binary sensors](#esp32-touch-binary-sensor) may then be configured to permit touch detection.
```yaml
@@ -52,13 +52,15 @@ the sensors aren't behaving as expected.
time for all touch pads. A longer conversion time means that more charge/discharge cycles of the touch pad
can be performed, therefore increasing accuracy. Default is about 8ms, the maximum amount.
+#### ESP32, ESP32-S2 and ESP32-S3 only
+
- **low_voltage_reference** (*Optional*): The low voltage reference to use for the charge cycles. One of `0.5V`,
`0.6V`, `0.7V`, `0.8V`. Default is `0.5V`.
- **high_voltage_reference** (*Optional*): The high voltage reference to use for the charge cycles. One of `2.4V`,
`2.5V`, `2.6V`, `2.7V`. Default is `2.7V`.
-- **voltage_attenuation** (*Optional*): The voltage attenuation to use for the charge cycles. One of `1.5V`, `1V`,
+- **voltage_attenuation** (*Optional*, ESP32 only): The voltage attenuation to use for the charge cycles. One of `1.5V`, `1V`,
`0.5V`, `0V`. Default is `0V`.
For a more detailed explanation of the parameters above, please see the
@@ -71,7 +73,7 @@ For a more detailed explanation of the parameters above, please see the
filter should be applied to all touch pads. This can increase the accuracy of the touch pads a lot, but higher values
decrease the response time. A good value to start with is `10ms`. By default, the IIR filter is inactive.
-#### ESP32-S2 and ESP32-S3 only
+#### ESP32-S2, ESP32-S3 and ESP32-P4 only
**For each configuration category below, if one option is specified, all options must be specified.** The configuration
options below do not have any default values; in other words, they are inactive by default.
@@ -79,7 +81,7 @@ options below do not have any default values; in other words, they are inactive
Filter configuration:
- **filter_mode** (*Optional*): Sets the filter mode. Must be one of `IIR_4`, `IIR_8`, `IIR_16`,
- `IIR_32`, `IIR_64`, `IIR_128`, `IIR_256` or `JITTER`.
+ `IIR_32`, `IIR_64`, `IIR_128`, `IIR_256` (S2/S3 only) or `JITTER`.
- **debounce_count** (*Optional*, `int` range 0-7): Sets the debounce count; if the measured values continue to
exceed the threshold for `n + 1` times, the touch sensor state changes.
@@ -94,7 +96,7 @@ Filter configuration:
For a more detailed explanation of the filter configuration, please see the
[ESP-IDF documentation.](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/touch_pad.html#_CPPv419touch_filter_config)
-Denoise configuration:
+Denoise configuration (ESP32-S2 and ESP32-S3 only, not available on ESP32-P4):
- **denoise_grade** (*Optional*): Sets the denoise range of the denoise channel. Determined by measuring the noise
amplitude of the denoise channel. Must be one of `BIT12`, `BIT10`, `BIT8` or `BIT4`.
@@ -188,12 +190,12 @@ under a flexible object like a plastic mat, add the raw values, and apply a thre
## Touch Pad Pins
-Various pins on the ESP32, ESP32-S2 and ESP32-S3 can be used to detect touches. They are as follows (using the default
+Various pins on the ESP32, ESP32-S2, ESP32-S3 and ESP32-P4 can be used to detect touches. They are as follows (using the default
"raw" pin names/numbers):
-| ESP32 | ESP32-S2 | ESP32-S3 |
-| --------------------------------------------------------------------------- | -------------- | -------------- |
-| GPIO4, GPIO0, GPIO2, GPIO15, GPIO13, GPIO12, GPIO14, GPIO27, GPIO33, GPIO32 | GPIO1 - GPIO14 | GPIO1 - GPIO14 |
+| ESP32 | ESP32-S2 | ESP32-S3 | ESP32-P4 |
+| --------------------------------------------------------------------------- | -------------- | -------------- | -------------- |
+| GPIO4, GPIO0, GPIO2, GPIO15, GPIO13, GPIO12, GPIO14, GPIO27, GPIO33, GPIO32 | GPIO1 - GPIO14 | GPIO1 - GPIO14 | GPIO2 - GPIO15 |
@@ -239,21 +241,21 @@ reduce the ESP's overall performance.
-## S2 and S3 Variants
+## S2, S3 and P4 Variants
> [!NOTE]
-> **ESP32-S2 and ESP32-S3 Touch Configuration**
+> **ESP32-S2, ESP32-S3 and ESP32-P4 Touch Configuration**
>
> The default `measurement_duration` and `sleep_duration` values are optimized for the original ESP32 and
-> **may not work at all on S2/S3 variants**. The S2/S3 touch hardware requires different timing settings.
+> **may not work at all on S2/S3/P4 variants**. These variants have different touch hardware requiring different timing settings.
>
> Key differences:
>
> - **Touch values increase** when touched (opposite of ESP32 which decreases)
> - **Higher raw values** are returned compared to original ESP32
-> - **Lower measurement duration required** - the default 8ms is often too high for S2/S3
+> - **Lower measurement duration required** - the default 8ms is often too high for S2/S3/P4
>
-> **Example settings for S2/S3:**
+> **Example settings for S2/S3/P4:**
>
> ```yaml
> esp32_touch:
@@ -264,25 +266,25 @@ reduce the ESP's overall performance.
> binary_sensor:
> - platform: esp32_touch
> name: "Touch Sensor"
-> pin: GPIO1
+> pin: GPIOXX
> threshold: 1000 # Adjust based on your hardware
> ```
-If you're familiar with the ESP32 hardware and pick up an S2 or S3 variant, you're likely to notice some behavioral
+If you're familiar with the ESP32 hardware and pick up an S2, S3 or P4 variant, you're likely to notice some behavioral
differences between them. In particular:
-- Raw touch sensor readings on the S2 and S3 variants will generally return larger numeric values than the original
+- Raw touch sensor readings on the S2, S3 and P4 variants will generally return larger numeric values than the original
ESP32 hardware.
-- Contact with the touch sensor on the S2 and S3 variants will result in the raw sensor value reading *increasing*; on
+- Contact with the touch sensor on the S2, S3 and P4 variants will result in the raw sensor value reading *increasing*; on
the original ESP32, contact would cause this value to *decrease*.
These behavioral differences are due to changes in the hardware and software (ESP-IDF) interfaces and should be
-expected -- if you are moving your configuration from an original ESP32 to an S2 or S3 variant, expect that you'll need
+expected -- if you are moving your configuration from an original ESP32 to an S2, S3 or P4 variant, expect that you'll need
to make some adjustments to your configuration to accommodate this behavior.
Most importantly, the default `measurement_duration` of 8ms (optimized for original ESP32) is often too high for
-S2/S3 variants and can prevent touch detection from working entirely. Using a much lower value like 0.25ms has been
+S2/S3/P4 variants and can prevent touch detection from working entirely. Using a much lower value like 0.25ms has been
found to work across many S2/S3 devices, though specific parameters may still need tuning per hardware implementation.
## See Also
diff --git a/src/content/docs/components/cc1101.mdx b/src/content/docs/components/cc1101.mdx
index ac2919a5f8..f9690ce83d 100644
--- a/src/content/docs/components/cc1101.mdx
+++ b/src/content/docs/components/cc1101.mdx
@@ -184,6 +184,140 @@ on_...:
data: [0x12, 0x34, 0x56, 0x78]
```
+### `cc1101.set_frequency` Action
+
+This [action](/automations/actions#all-actions) changes the operating frequency at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, frequency):
+ The frequency to set. Range: `300MHz` to `928MHz`.
+
+```yaml
+on_...:
+ - cc1101.set_frequency: 433.92MHz
+ - cc1101.set_frequency:
+ value: !lambda "return 868.0e6;"
+```
+
+### `cc1101.set_output_power` Action
+
+This [action](/automations/actions#all-actions) changes the transmission power at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, float): The output power in dBm. Range: `-30` to `11`.
+
+### `cc1101.set_modulation_type` Action
+
+This [action](/automations/actions#all-actions) changes the modulation type at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, enum): The modulation type.
+ Options: `ASK/OOK`, `2-FSK`, `4-FSK`, `GFSK`, `MSK`.
+
+```yaml
+on_...:
+ - cc1101.set_modulation_type: "GFSK"
+ - cc1101.set_modulation_type:
+ value: !lambda |-
+ return cc1101::Modulation::MODULATION_2_FSK;
+```
+
+### `cc1101.set_symbol_rate` Action
+
+This [action](/automations/actions#all-actions) changes the symbol rate at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, float): The symbol rate in baud. Range: `600` to `500000`.
+
+### `cc1101.set_rx_attenuation` Action
+
+This [action](/automations/actions#all-actions) changes the internal RX attenuation at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, enum): The attenuation level.
+ Options: `0dB`, `6dB`, `12dB`, `18dB`.
+
+```yaml
+on_...:
+ - cc1101.set_rx_attenuation: "12dB"
+ - cc1101.set_rx_attenuation:
+ value: !lambda |-
+ return cc1101::RxAttenuation::RX_ATTENUATION_0DB;
+```
+
+### `cc1101.set_dc_blocking_filter` Action
+
+This [action](/automations/actions#all-actions) enables or disables the DC blocking filter at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, boolean): `true` to enable, `false` to disable.
+
+### `cc1101.set_manchester` Action
+
+This [action](/automations/actions#all-actions) enables or disables Manchester encoding at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, boolean): `true` to enable, `false` to disable.
+
+### `cc1101.set_filter_bandwidth` Action
+
+This [action](/automations/actions#all-actions) changes the receive filter bandwidth at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, frequency):
+ The filter bandwidth. Range: `58kHz` to `812kHz`.
+
+### `cc1101.set_fsk_deviation` Action
+
+This [action](/automations/actions#all-actions) changes the FSK/GFSK frequency deviation at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, frequency):
+ The frequency deviation. Range: `1.5kHz` to `381kHz`.
+
+### `cc1101.set_msk_deviation` Action
+
+This [action](/automations/actions#all-actions) changes the MSK deviation index at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, int): The deviation index. Range: `1` to `8`.
+
+### `cc1101.set_channel` Action
+
+This [action](/automations/actions#all-actions) changes the channel number at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, int): The channel number. Range: `0` to `255`.
+
+### `cc1101.set_channel_spacing` Action
+
+This [action](/automations/actions#all-actions) changes the channel spacing at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, frequency):
+ The spacing between channels. Range: `25kHz` to `405kHz`.
+
+### `cc1101.set_if_frequency` Action
+
+This [action](/automations/actions#all-actions) changes the intermediate frequency at runtime.
+
+#### Configuration variables
+
+- **value** (**Required**, frequency):
+ The intermediate frequency. Range: `25kHz` to `788kHz`.
+
## Integration with Remote Receiver/Transmitter
For ASK/OOK modulation, the CC1101 integrates with Remote Receiver/Transmitter for protocol encoding
diff --git a/src/content/docs/components/climate/pid.mdx b/src/content/docs/components/climate/pid.mdx
index 22b25bb4ed..caa25dc376 100644
--- a/src/content/docs/components/climate/pid.mdx
+++ b/src/content/docs/components/climate/pid.mdx
@@ -382,6 +382,36 @@ Configuration variables:
- **kd** (*Optional*, float, [templatable](/automations/templates)): The factor for the derivative term of the PID controller.
Defaults to `0`.
+This action updates the active runtime PID controller. The new values are used on the
+next PID computation cycle.
+
+## `climate.pid.set_deadband_control_parameters_multipliers` Action
+
+This action sets runtime multipliers for the deadband PID terms. This can be used to tune
+how strongly the P/I/D terms are applied while the controller is in deadband.
+
+```yaml
+on_...:
+ - climate.pid.set_deadband_control_parameters_multipliers:
+ id: pid_climate
+ kp_multiplier: 0.0
+ ki_multiplier: 0.0
+ kd_multiplier: 0.0
+```
+
+Configuration variables:
+
+- **id** (**Required**, [ID](/guides/configuration-types#id)): ID of the PID Climate to update.
+- **kp_multiplier** (**Required**, float, [templatable](/automations/templates)): Deadband multiplier for the proportional term.
+- **ki_multiplier** (*Optional*, float, [templatable](/automations/templates)): Deadband multiplier for the integral term.
+ Defaults to `0`.
+
+- **kd_multiplier** (*Optional*, float, [templatable](/automations/templates)): Deadband multiplier for the derivative term.
+ Defaults to `0`.
+
+This action updates the active runtime PID controller. The new values are used on the
+next PID computation cycle.
+
## `climate.pid.reset_integral_term` Action
This action resets the integral term of the PID controller to 0. This might be necessary under certain
@@ -423,6 +453,9 @@ Configuration variables:
- `KP` - The current factor for the proportional term of the PID controller.
- `KI` - The current factor for the integral term of the PID controller.
- `KD` - The current factor for the differential term of the PID controller.
+ - `KP_DEADBAND_MULTIPLIER` - The current deadband multiplier for the proportional term.
+ - `KI_DEADBAND_MULTIPLIER` - The current deadband multiplier for the integral term.
+ - `KD_DEADBAND_MULTIPLIER` - The current deadband multiplier for the differential term.
- All other options from [Sensor](/components/sensor).
diff --git a/src/content/docs/components/display/epaper_spi.mdx b/src/content/docs/components/display/epaper_spi.mdx
index 58af346f3d..d0e182c924 100644
--- a/src/content/docs/components/display/epaper_spi.mdx
+++ b/src/content/docs/components/display/epaper_spi.mdx
@@ -45,6 +45,10 @@ the pins used to interface to the display to be specified.
| Waveshare-1.54in-G | Waveshare | [https://www.waveshare.com/1.54inch-e-paper-g.htm](https://www.waveshare.com/1.54inch-e-paper-g.htm) |
| Waveshare-2.13in-v3 | Waveshare | [https://www.waveshare.com/pico-epaper-2.13.htm](https://www.waveshare.com/pico-epaper-2.13.htm) |
| Waveshare-4.26in | Waveshare | [https://www.waveshare.com/4.26inch-e-paper.htm](https://www.waveshare.com/4.26inch-e-paper.htm) |
+| Waveshare-7.5in-H | Waveshare | [https://www.waveshare.com/7.5inch-e-paper-hat-h.htm](https://www.waveshare.com/7.5inch-e-paper-hat-h.htm) |
+| WeAct-2.13in-3c | WeAct | 2.13" 3-color e-paper (250x122, SSD1683) |
+| WeAct-2.9in-3c | WeAct | 2.9" 3-color e-paper (128x296, SSD1683) |
+| WeAct-4.2in-3c | WeAct | 4.2" 3-color e-paper (400x300, SSD1683) |
## Supported integrated display boards
@@ -65,6 +69,11 @@ but can be overridden if needed.
- **cs_pin** (**Required**, [Pin Schema](/guides/configuration-types#pin-schema)): The CS pin. Predefined for integrated boards.
- **dc_pin** (**Required**, [Pin Schema](/guides/configuration-types#pin-schema)): The DC pin. Predefined for integrated boards.
- **busy_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The BUSY pin, if used.
+
+ > [!NOTE]
+ > Some displays use inverted busy pin polarity (LOW = busy, HIGH = idle). For these models, set `inverted: true`
+ > on the busy pin. This applies to: `Waveshare-1.54in-G`, `Waveshare-7.5in-H`.
+
- **reset_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The RESET pin, if used.
Make sure you pull this pin high (by connecting it to 3.3V with a resistor) if not connected to a GPIO pin.
- **dimensions** (**Required**, dict): Dimensions of the screen, specified either as *width* **x** *height* (e.g `320x240` )
@@ -113,6 +122,38 @@ display:
busy_pin: { number: GPIOXX, inverted: False, mode: { input: True, pulldown: True } }
```
+### 4-color display example
+
+Some displays support 4 colors (black, white, red, yellow). Colors are mapped from RGB automatically.
+Full refresh times for 4-color displays are typically around 20 seconds.
+
+```yaml
+spi:
+ clk_pin: GPIO13
+ mosi_pin: GPIO14
+
+display:
+ - platform: epaper_spi
+ model: Waveshare-7.5in-H
+ cs_pin: GPIO15
+ dc_pin: GPIO27
+ reset_pin: GPIO26
+ busy_pin:
+ number: GPIO25
+ inverted: true
+ update_interval: 5min
+ lambda: |-
+ auto BLACK = Color(0, 0, 0);
+ auto WHITE = Color(255, 255, 255);
+ auto RED = Color(255, 0, 0);
+ auto YELLOW = Color(255, 255, 0);
+
+ it.fill(WHITE);
+ it.filled_rectangle(50, 50, 80, 80, BLACK);
+ it.filled_rectangle(150, 50, 80, 80, RED);
+ it.filled_rectangle(250, 50, 80, 80, YELLOW);
+```
+
## See Also
- [ESPHome Display Rendering Engine](/components/display#display-engine)
diff --git a/src/content/docs/components/display/mipi_dsi.mdx b/src/content/docs/components/display/mipi_dsi.mdx
index 5cb3bd243e..1fd9c78c38 100644
--- a/src/content/docs/components/display/mipi_dsi.mdx
+++ b/src/content/docs/components/display/mipi_dsi.mdx
@@ -32,34 +32,50 @@ The display panels controlled by the driver may be of various types, including T
chip and panel combination requires a specific set of initialisation commands, and standard initialisation sequences are provided for many common
boards and chips, but the driver is also designed to be customisable in YAML for other displays.
-## Supported boards and driver chips
+## Supported driver chips, display panels and boards
-There are specific configurations for several ESP32 boards with integrated displays. For those boards
-the predefined configuration will set the correct pins and dimensions for the display.
+### Driver chips
For custom displays, the driver can be configured with the correct pins and dimensions, and the driver chip can be
specified, or a custom init sequence can be provided.
-### Driver chips
-
| Driver Chip | Typical Dimensions |
| ----------- | ------------------ |
| CUSTOM | Customisable |
+### Standalone displays
+
+These are standalone display panels incorporating a driver chip and display panel. The `transform`, `rotation`, or other
+layout parameters may need to be specified to suit a specific usage scenario. These displays typically do not
+physically expose reset or enable pins but they may have a connector for an I²C bus for a touchscreen or to
+control the backlight. Check the manufacturer's documentation for information on how to use them.
+Some of these displays are used by ESP32 boards defined in the next section.
+
+| Model | Manufacturer | Dimensions | Product Link |
+| -------------------------- | ------------ | ------------------- | -------------------------------------------------------------------------------- |
+| WAVESHARE-10.1-DSI-TOUCH-A | Waveshare | 800x1280 | [10.1-DSI-TOUCH-A product page](https://www.waveshare.com/wiki/10.1-DSI-TOUCH-A) |
+| WAVESHARE-8-DSI-TOUCH-A | Waveshare | 800x1280 | [8-DSI-TOUCH-A product page](https://www.waveshare.com/wiki/8-DSI-TOUCH-A) |
+| WAVESHARE-7-DSI-TOUCH-A | Waveshare | 720x1280 | [7-DSI-TOUCH-A product page](https://www.waveshare.com/wiki/7-DSI-TOUCH-A) |
+| WAVESHARE-4-DSI-TOUCH-C | Waveshare | 720x720 (round) | [4-DSI-TOUCH-C product page](https://www.waveshare.com/wiki/4-DSI-TOUCH-C) |
+| WAVESHARE-3.4-DSI-TOUCH-C | Waveshare | 800x800 (round) | [3.4-DSI-TOUCH-C product page](https://www.waveshare.com/wiki/3.4-DSI-TOUCH-C) |
+
### Boards with integrated displays
-| Model | Manufacturer | Product Description |
-| ---------------------- | ------------ | ----------------------------------------------------------------------------- |
-| JC1060P470 | Guition | [https://aliexpress.com/item/1005008328088576.html](https://aliexpress.com/item/1005008328088576.html) |
-| JC4880P443 | Guition | [https://aliexpress.com/item/1005009618259341.html](https://aliexpress.com/item/1005009618259341.html) |
-| JC8012P4A1 | Guition | [https://aliexpress.com/item/1005008789890066.html](https://aliexpress.com/item/1005008789890066.html) |
-| M5STACK-TAB5 | M5Stack | [https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4](https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4) |
-| M5STACK-TAB5-V2 | M5Stack | [https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4](https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4) |
-| WAVESHARE-P4-NANO-10.1 | Waveshare | [https://www.waveshare.com/esp32-p4-nano.htm?sku=29031](https://www.waveshare.com/esp32-p4-nano.htm?sku=29031) |
-| WAVESHARE-P4-86-PANEL | Waveshare | [https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm?sku=31570](https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm?sku=31570) |
-| WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-7B | Waveshare | [https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-7B](https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-7B) |
-| WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-3.4C | Waveshare | [https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-3.4C](https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-3.4C) |
-| WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-4C | Waveshare | [https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-4C](https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-4C) |
+These are specific configurations for several ESP32 boards with integrated displays. The predefined configuration
+will set the correct pins and dimensions for the display.
+
+| Model | Manufacturer | Product Link |
+| ---------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| JC1060P470 | Guition | [JC1060P470 product page](https://aliexpress.com/item/1005008328088576.html) |
+| JC4880P443 | Guition | [JC4880P443 product page](https://aliexpress.com/item/1005009618259341.html) |
+| JC8012P4A1 | Guition | [JC8012P4A1 product page](https://aliexpress.com/item/1005008789890066.html) |
+| M5STACK-TAB5 | M5Stack | [TAB5 product page](https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4) |
+| M5STACK-TAB5-V2 | M5Stack | [TAB5-V2 product page](https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4) |
+| WAVESHARE-P4-NANO-10.1 | Waveshare | [P4-NANO-10.1 product page](https://www.waveshare.com/esp32-p4-nano.htm?sku=29031) |
+| WAVESHARE-P4-86-PANEL | Waveshare | [P4-86-PANEL product page](https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm?sku=31570) |
+| WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-7B | Waveshare | [P4-WIFI6-TOUCH-LCD-7B product page](https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-7B) |
+| WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-3.4C | Waveshare | [P4-WIFI6-TOUCH-LCD-3.4C product page](https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-3.4C) |
+| WAVESHARE-ESP32-P4-WIFI6-TOUCH-LCD-4C | Waveshare | [P4-WIFI6-TOUCH-LCD-4C product page](https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-4C) |
> [!NOTE]
The M5Stack Tab5 has two hardware revisions with different display chips requiring different model selections.
diff --git a/src/content/docs/components/display/mipi_spi.mdx b/src/content/docs/components/display/mipi_spi.mdx
index dee5e8d755..e87fce1fe5 100644
--- a/src/content/docs/components/display/mipi_spi.mdx
+++ b/src/content/docs/components/display/mipi_spi.mdx
@@ -46,6 +46,7 @@ using an octal SPI bus, so references here to parallel and octal SPI are equival
| ILI9488 | 320x480 |
| ILI9488_A | 320x480 |
| ST7796 | 320x480 |
+| ST7789P | 240x320 |
| ST7789V | 240x320 |
| GC9A01A | 240x240 |
| GC9D01N | 240x240 |
diff --git a/src/content/docs/components/esp32.mdx b/src/content/docs/components/esp32.mdx
index dcedee9d68..60c1ee07a6 100644
--- a/src/content/docs/components/esp32.mdx
+++ b/src/content/docs/components/esp32.mdx
@@ -27,6 +27,10 @@ esp32:
> the board configuration will be automatically filled using a standard Espressif devkit board
> suitable for that variant. Both may be specified (for backwards compatibility) but they must define the same variant.
+- **engineering_sample** (*Optional*, boolean): **ESP32-P4 only.** Set to `true` if your board has engineering
+ sample silicon (rev < 3.0). When using `variant: esp32p4` without specifying a `board`, a warning is logged
+ if this option is not explicitly set. Defaults to `false`.
+
- **flash_size** (*Optional*, string): The amount of flash memory available on the ESP32 board/module. One of `2MB`,
`4MB`, `8MB`, `16MB` or `32MB`. Defaults to `4MB`. **Warning: specifying a size larger than that available
on your board will cause the ESP32 to fail to boot.**
@@ -130,8 +134,8 @@ esp32:
[Espressif's documentation](https://docs.espressif.com/projects/esp-idf/en/v5.3.3/esp32/api-reference/kconfig.html#config-lwip-esp-lwip-assert)
for more information.
-- **execute_from_psram** (*Optional*, boolean): On ESP32S3 only may be set to `true` to enable executing code from PSRAM.
- With octal PSRAM this can be faster than executing from FLASH memory, and enables code such as display drawing
+- **execute_from_psram** (*Optional*, boolean): On ESP32S3 and ESP32P4 only may be set to `true` to enable executing code from PSRAM.
+ With octal or hex PSRAM this can be faster than executing from FLASH memory, and enables code such as display drawing
to execute normally when writing to FLASH, e.g. during an OTA update. The default is `false`.
- **ignore_efuse_custom_mac** (*Optional*, boolean): Can be set to `true` for devices on which the burned-in custom
diff --git a/src/content/docs/components/esp32_ble.mdx b/src/content/docs/components/esp32_ble.mdx
index 11e2cf9027..5c738889fe 100644
--- a/src/content/docs/components/esp32_ble.mdx
+++ b/src/content/docs/components/esp32_ble.mdx
@@ -25,6 +25,9 @@ esp32_ble:
max_connections: 3 # Default, total BLE connections
# advertising: true # Only needed for advanced use cases
max_notifications: 12 # Default, increase if needed
+ # auth_req_mode: sc_mitm_bond # Optional, for advanced security
+ # max_key_size: 16 # Optional, encryption key size (7-16)
+ # min_key_size: 7 # Optional, encryption key size (7-16)
```
## Configuration variables
@@ -84,6 +87,23 @@ esp32_ble:
> [!NOTE]
> The `max_notifications` option controls the `CONFIG_BT_GATTC_NOTIF_REG_MAX` ESP-IDF setting. This limit is per GATT client interface, not per connection. If you're using ESPHome as a Bluetooth proxy with multiple devices that have many characteristics requiring notifications, you may need to increase this value. The error `status=128` in logs indicates you've hit this limit.
+- **max_key_size** (*Optional*, integer): Maximum encryption key size to support. Must be between `7` and `16`. Leave unspecified to use the ESP32 default unless your device needs special handling.
+
+- **min_key_size** (*Optional*, integer): Minimum encryption key size requirement from peer. Must be between `7` and `16`. Leave unspecified to use the ESP32 default unless your device needs special handling.
+
+- **auth_req_mode** (*Optional*, enum): The authentication request mode. Defaults to the ESP-IDF default. Leave unspecified unless your device needs special handling.
+
+ - `no_bond` - No bonding
+ - `bond` - Bonding
+ - `mitm` - MITM only
+ - `bond_mitm` - Bonding with MITM
+ - `sc_only` - Secure connections only
+ - `sc_bond` - Secure connections with bonding
+ - `sc_mitm` - Secure connections with MITM
+ - `sc_mitm_bond` - Secure connections with MITM and bonding
+
+ See [ESP32 SDK Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/esp_gap_ble.html#c.ESP_LE_AUTH_NO_BOND) for details on these modes.
+
## `ble.disable` Action
This action turns off the BLE interface on demand.
diff --git a/src/content/docs/components/esp32_ble_server.mdx b/src/content/docs/components/esp32_ble_server.mdx
index 6414d399d0..0bda4ca498 100644
--- a/src/content/docs/components/esp32_ble_server.mdx
+++ b/src/content/docs/components/esp32_ble_server.mdx
@@ -38,6 +38,10 @@ esp32_ble_server:
- **manufacturer_data** (*Optional*, list of bytes): The manufacturer-specific data to include in the advertising
packet. Should be a list of bytes, where the first two are the little-endian representation of the 16-bit
manufacturer ID as assigned by the Bluetooth SIG.
+- **max_clients** (*Optional*, int): The maximum number of simultaneous BLE client connections the server will
+ accept. When set to a value greater than 1, the server resumes advertising after a client connects so that
+ additional clients can discover and connect, up to this limit. Must not exceed the `max_connections` value
+ configured in the [ESP32 BLE](/components/esp32_ble) component. Defaults to `1`. Range: 1 to 9.
- **on_connect** (*Optional*, [Automation](/automations)): An action to be performed when a client connects to the BLE server. It provides the `id` variable which contains the ID of the client that connected.
- **on_disconnect** (*Optional*, [Automation](/automations)): An action to be performed when a client disconnects from the BLE server. It provides the `id` variable which contains the ID of the client that disconnected.
diff --git a/src/content/docs/components/esp32_camera.mdx b/src/content/docs/components/esp32_camera.mdx
index 4dc672c849..3bf70698ce 100644
--- a/src/content/docs/components/esp32_camera.mdx
+++ b/src/content/docs/components/esp32_camera.mdx
@@ -108,8 +108,23 @@ Image Settings:
- `1080x1920` (Portrait FHD, 9:16)
- `2560x1920` (QSXGA, 4:3)
+- **pixel_format** (*Optional*, enum): The pixel format to use for the images.
+ Defaults to ``jpeg`` (JPEG compressed image) which may not be supported by all cameras.
+ Other formats require more CPU and memory and may not be supported by all cameras.
+
+ - ``jpeg``: JPEG compressed image
+ - ``rgb565``: RGB565 uncompressed image
+ - ``yuv422``: YUV422 uncompressed image
+ - ``yuv420``: YUV420 uncompressed image
+ - ``grayscale``: Grayscale uncompressed image
+ - ``rgb888``: RGB888 uncompressed image
+ - ``raw``: Raw uncompressed image
+ - ``rgb444``: RGB444 uncompressed image
+ - ``rgb555``: RGB555 uncompressed image
+
- **jpeg_quality** (*Optional*, int): The JPEG quality that the camera should encode images with.
- From 10 (best) to 63 (worst). Defaults to `10`.
+ From 6 (best) to 63 (worst). Defaults to `10`. Set this to ``0`` to disable JPEG compression/conversion.
+ Manual JPEG compression/conversion requires `psram` component to be enabled and configured.
- **vertical_flip** (*Optional*, boolean): Whether to flip the image vertically. Defaults to `true`.
- **horizontal_mirror** (*Optional*, boolean): Whether to mirror the image horizontally. Defaults to `true`.
@@ -292,6 +307,52 @@ esp32_camera:
reset_pin: GPIO15
```
+**M5Stack AtomS3R-CAM**:
+
+```yaml
+# Example configuration entry
+psram: # required for JPEG compression/conversion
+ mode: octal
+ speed: 80MHz
+
+switch: # required to initialize the camera
+ - platform: gpio
+ name: Activate My Camera
+ pin:
+ number: GPIO18
+ inverted: true
+ restore_mode: ALWAYS_ON
+
+i2c:
+ - id: camera_i2c
+ sda: GPIO12 # CAM_SDA
+ scl: GPIO9 # CAM_SCL
+
+esp32_camera:
+ setup_priority: -200 # delay after GPIO18 was set to low
+ i2c_id: camera_i2c
+ vsync_pin: GPIO10 # VSYNC
+ href_pin: GPIO14 # HREF
+ external_clock: # XCLK
+ pin: GPIO21
+ frequency: 20MHz
+ pixel_clock_pin: GPIO40 # PCLK
+ data_pins: [GPIO3, GPIO42, GPIO46, GPIO48, GPIO4, GPIO17, GPIO11, GPIO13] # Y2-9
+
+ # Image settings
+ name: My Camera
+ max_framerate: 15.0 fps
+ resolution: 320x240
+ frame_buffer_count: 1
+ frame_buffer_location: DRAM
+ pixel_format: YUV422
+ jpeg_quality: 6
+ agc_mode: manual
+ vertical_flip: true
+ horizontal_mirror: false
+ # ...
+```
+
**Wrover Kit Boards**:
```yaml
diff --git a/src/content/docs/components/esp32_hosted.mdx b/src/content/docs/components/esp32_hosted.mdx
index 0ca2a72edd..c7b7a4c1d1 100644
--- a/src/content/docs/components/esp32_hosted.mdx
+++ b/src/content/docs/components/esp32_hosted.mdx
@@ -20,6 +20,7 @@ esp32_hosted:
d2_pin: GPIOXX
d3_pin: GPIOXX
active_high: true
+ sdio_frequency: 10MHz
wifi:
ssid: !secret wifi_ssid
@@ -43,6 +44,9 @@ wifi:
- **reset_pin** (*Required*, [Pin](/guides/configuration-types#pin)): The reset pin of the co-processor.
- **active_high** (*Required*, boolean): If enabled, the co-processor is active when reset is
high. If disabled, the co-processor is active when reset is low.
+- **sdio_frequency** (*Optional*): Set the speed of communication between the master and
+ the slave. If you experience loss of communication, or reboots, then try reducing this value.
+ The value can be between 400KHz and 50MHz, with a default of 40MHz.
## Updating co-processor firmware
diff --git a/src/content/docs/components/esp_ldo.mdx b/src/content/docs/components/esp_ldo.mdx
index 656f23e0dd..d877c3df46 100644
--- a/src/content/docs/components/esp_ldo.mdx
+++ b/src/content/docs/components/esp_ldo.mdx
@@ -8,22 +8,37 @@ import APIRef from '@components/APIRef.astro';
The ESP32-P4 has 4 Low-Dropout linear regulators that can be used to power on- and off-chip peripherals. This
component allows those regulators to be configured and enabled.
+Channels 3 and 4 are available for general use. Channels 1 and 2 are normally reserved by the chip for powering
+internal flash and PSRAM — they can only be configured with an explicit acknowledgement option (see below).
+
```yaml
# Example configuration entry
esp_ldo:
- channel: 3
voltage: 2.5V
+ - channel: 4
+ voltage: passthrough
```
## Configuration variables
-- **channel** (**Required**, int): The channel number of the LDO regulator to configure. Only channels 3 and 4 are supported (1 and 2 are used internally by the chip.)
-- **voltage** (**Required**, voltage): The desired output voltage - must be in the range 0.5V to 2.7V.
-- **adjustable** (*Optional*, bool): If true, the output voltage can be adjusted at run-time. Defaults to false.
+- **channel** (**Required**, int): The channel number of the LDO regulator to configure. Valid values are 1–4.
+ Channels 3 and 4 are available for general use. Channels 1 and 2 are reserved for internal chip use (flash/PSRAM)
+ and require ``allow_internal_channel: true`` to be set.
+- **voltage** (**Required**, voltage): The desired output voltage. Must be in the range ``0.5V`` to ``2.7V``, or
+ ``passthrough`` to enable pass-through mode (output follows the supply voltage). Note: the actual output voltage
+ may deviate by approximately 50–100 mV from the configured value.
+- **adjustable** (*Optional*, bool): If true, the output voltage can be adjusted at runtime using the
+ ``esp_ldo.voltage.adjust`` action. Defaults to ``false``. Cannot be set to ``true`` when ``voltage`` is
+ ``passthrough``, as pass-through mode does not support runtime voltage adjustment.
+- **allow_internal_channel** (*Optional*, bool): Must be set to ``true`` to use channels 1 or 2. These channels are
+ normally reserved by the chip for flash and PSRAM power. Incorrect use can cause system instability, data
+ corruption, or a permanently bricked device. Only set this if you have verified via your board's datasheet and
+ schematics that the channel is unused. Setting this option on channels 3 or 4 is an error. Defaults to ``false``.
## `esp_ldo.voltage.adjust` Action
-If the LDO is adjustable, the voltage can be updated at runtime:
+If the LDO is configured with ``adjustable: true``, the voltage can be updated at runtime:
```yaml
on_...:
@@ -36,7 +51,17 @@ on_...:
### Configuration variables
- **id** (**Required**, [ID](/guides/configuration-types#id)): The ID of the LDO to adjust.
-- **voltage** (**Required**, voltage, [templatable](/automations/templates)): The desired output voltage - must be in the range 0.5V to 2.7V.
+- **voltage** (**Required**, voltage, [templatable](/automations/templates)): The desired output voltage. Must be in the range ``0.5V`` to ``2.7V``.
+
+## Notes
+
+- The LDO output voltage may deviate by approximately 50-100 mV from the configured value.
+- Channels 1 and 2 are connected to the chip's internal flash and PSRAM power domains on most ESP32-P4 modules.
+ Only use these channels if your specific board schematic confirms they are routed to an external pad and are
+ not powering internal components.
+- ``passthrough`` mode passes the supply voltage directly to the output and does not support runtime voltage
+ adjustment. Setting ``adjustable: true`` together with ``voltage: passthrough`` is a configuration error and
+ will be rejected during validation.
## See Also
diff --git a/src/content/docs/components/index.mdx b/src/content/docs/components/index.mdx
index d365661df1..6f8c61ae23 100644
--- a/src/content/docs/components/index.mdx
+++ b/src/content/docs/components/index.mdx
@@ -256,6 +256,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
["SDS011 Sensor", "/components/sensor/sds011/", "sds011.jpg", "Particulate"],
["SEN0321", "/components/sensor/sen0321/", "sen0321.jpg", "Ozone"],
["SEN5x", "/components/sensor/sen5x/", "sen54.jpg", "Temperature & Humidity & Volatile organics & NOx"],
+ ["SEN6x", "/components/sensor/sen6x/", "sen6x.webp", "Particulate & Temperature & Humidity & VOC & NOx & CO2"],
["SenseAir", "/components/sensor/senseair/", "senseair_s8.jpg", "CO2"],
["SFA30", "/components/sensor/sfa30/", "sfa30.jpg", "Formaldehyde"],
["SGP30", "/components/sensor/sgp30/", "sgp30.jpg", "CO2 & Volatile organics"],
@@ -387,6 +388,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
["ENS210", "/components/sensor/ens210/", "ens210.jpg", "Temperature & Humidity"],
["HDC1080", "/components/sensor/hdc1080/", "hdc1080.jpg", "Temperature & Humidity"],
["HDC2010", "/components/sensor/hdc2010/", "hdc2010.png", "Temperature & Humidity"],
+ ["HDC302x", "/components/sensor/hdc302x/", "hdc302x.svg", "Temperature & Humidity"],
["HHCCJCY10 (MiFlora Pink)", "/components/sensor/xiaomi_hhccjcy10/", "xiaomi_hhccjcy10.jpg", "Soil moisture & Temperature & Light"],
["Honeywell ABP", "/components/sensor/honeywellabp/", "honeywellabp.jpg", "Pressure & Temperature"],
["Honeywell ABP2 I2C", "/components/sensor/honeywellabp2_i2c/", "honeywellabp.jpg", "Pressure & Temperature"],
@@ -884,6 +886,12 @@ Used for creating infrared (IR) remote control transmitters and/or receivers.
["Generic Output Lock", "/components/lock/output/", "upload.svg", "dark-invert"],
]} />
+## Media Source Components
+
+
+
## Media Player Components
## Hardware UARTs
diff --git a/src/content/docs/components/media_player/index.mdx b/src/content/docs/components/media_player/index.mdx
index 425bc94bc9..f0b5aff8f0 100644
--- a/src/content/docs/components/media_player/index.mdx
+++ b/src/content/docs/components/media_player/index.mdx
@@ -52,11 +52,13 @@ Configuration variables:
All `media_player` actions can be used without specifying an `id` if you have only one `media_player` in
your configuration YAML.
-The actions `turn_off` and `turn_on` are optional and based on the platform implementing the `supports_turn_off_on` trait.
+> [!NOTE]
+> Not all actions are supported by every media player platform. The availability of an action depends on the specific platform and its implemented features.
Configuration variables:
**id** (*Optional*, [ID](/guides/configuration-types#id)): The media player to control. Defaults to the only one in YAML.
+**announcement** (*Optional*, boolean): Whether to target announcements or regular media files, if supported by the media player. Defaults to `false`. Available on all command actions.
@@ -100,10 +102,6 @@ This action pauses the current playback.
This action stops the current playback.
-Configuration variables:
-
-**announcement** (*Optional*, boolean): Whether to target announcements or regular media files, if supported by the media player. Defaults to `false`.
-
### `media_player.toggle` Action
@@ -134,6 +132,72 @@ This action will increase the volume of the media player.
This action will decrease the volume of the media player.
+
+
+### `media_player.mute` Action
+
+This action will mute the media player.
+
+
+
+### `media_player.unmute` Action
+
+This action will unmute the media player.
+
+
+
+### `media_player.next` Action
+
+This action will skip to the next track.
+
+
+
+### `media_player.previous` Action
+
+This action will skip to the previous track.
+
+
+
+### `media_player.repeat_off` Action
+
+This action will turn off repeat mode.
+
+
+
+### `media_player.repeat_one` Action
+
+This action will set the media player to repeat the current track.
+
+
+
+### `media_player.repeat_all` Action
+
+This action will set the media player to repeat all tracks.
+
+
+
+### `media_player.shuffle` Action
+
+This action will enable shuffle mode.
+
+
+
+### `media_player.unshuffle` Action
+
+This action will disable shuffle mode.
+
+
+
+### `media_player.group_join` Action
+
+This action will join the media player to a group.
+
+
+
+### `media_player.clear_playlist` Action
+
+This action will clear the media player's playlist.
+
### `media_player.volume_set` Action
@@ -341,6 +405,20 @@ on_...:
media_player.is_on:
```
+
+
+### `media_player.is_muted` Condition
+
+This condition checks if the media player is muted.
+
+```yaml
+# In some trigger:
+on_...:
+ if:
+ condition:
+ media_player.is_muted:
+```
+
## Play media in order
You can use wait automation to play files one after the other:
diff --git a/src/content/docs/components/media_player/speaker.mdx b/src/content/docs/components/media_player/speaker.mdx
index 1e20fe4f0f..c97ed12275 100644
--- a/src/content/docs/components/media_player/speaker.mdx
+++ b/src/content/docs/components/media_player/speaker.mdx
@@ -7,7 +7,7 @@ The `speaker` media player platform allows you to play on-device and online audi
This platform greatly benefits from having external PSRAM. See the [performance section](#media_player-speaker-performance) for details.
-It natively supports decoding `FLAC`, `MP3`, and `WAV` audio files. Home Assistant (since version 2024.10) can proxy any media it sends and transcode it to a specified format and sample rate to minimize the device's computational load.
+It natively supports decoding `FLAC`, `MP3`, `OPUS`, and `WAV` audio files. Home Assistant (since version 2024.10) can proxy any media it sends and transcode it to a specified format and sample rate to minimize the device's computational load.
It supports two different audio pipelines: announcement and media. Each audio pipeline must output to a unique speaker. Use a [mixer speaker](/components/speaker/mixer/) component to create two different speakers that output to a single audio speaker.
@@ -35,13 +35,13 @@ media_player:
- **announcement_pipeline** (**Required**, Pipeline Schema): Configuration settings for the announcement pipeline.
- **speaker** (**Required**, [ID](/guides/configuration-types#id)): The [speaker](/components/speaker/) to output the audio.
- - **format** (*Optional*, enum): The audio format Home Assistant will transcode audio to before sending it to the device. One of `FLAC`, `MP3`, `WAV`, or `NONE`. `NONE` disables transcoding in Home Assistant. Defaults to `FLAC`.
- - **sample_rate** (*Optional*, positive integer): Sample rate for the transcoded audio. Should be supported by the configured `speaker` component. Defaults to the speaker's sample rate.
+ - **format** (*Optional*, enum): The audio format Home Assistant will transcode audio to before sending it to the device. One of `FLAC`, `MP3`, `OPUS`, `WAV`, or `NONE`. `NONE` disables transcoding in Home Assistant. Defaults to `FLAC`.
+ - **sample_rate** (*Optional*, positive integer): Sample rate for the transcoded audio. Should be supported by the configured `speaker` component. Defaults to the speaker's sample rate. The `OPUS` codec only supports a `48000` sample rate.
- **num_channels** (*Optional*, positive integer): Number of channels for the transcoded audio. Must be either `1` or `2`. Defaults to the speaker's number of channels.
- **media_pipeline** (*Optional*, Pipeline Schema): Configuration settings for the media pipeline. Same options as the `announcement_pipeline`.
- **buffer_size** (*Optional*, positive integer): The buffer size in bytes for each pipeline. Must be between `4000` and `4000000`. Defaults to `1000000`.
-- **codec_support_enabled** (*Optional*, boolean): Enables the MP3 and FLAC decoders. Defaults to `true`.
+- **codec_support_enabled** (*Optional*, enum): Controls which audio codecs (MP3, FLAC, Opus) are compiled. One of `ALL` (all available codecs are supported), `NEEDED` (only codecs needed to play the pipelines' preferred formats and included files), or `NONE` (only supports WAV files). Defaults to `NEEDED`.
- **task_stack_in_psram** (*Optional*, boolean): Run the audio tasks in external memory. Defaults to `false`.
- **volume_increment** (*Optional*, percentage): Increment amount that the `media_player.volume_up` and `media_player.volume_down` actions will increase or decrease volume by. Defaults to `5%`.
- **volume_initial** (*Optional*, percentage): The default volume that mediaplayer uses for first boot where a volume has not been previously saved. Defaults to `50%`.
@@ -165,7 +165,7 @@ Configuration variables:
## Performance
-Decoding audio files is CPU and memory intensive. PSRAM external memory is strongly recommended. To use the component on a memory constrained device, define only the announcement pipeline, decrease the buffer size, set `codec_support_enabled` to false, and set the pipeline transcode setting format to `WAV` with a low sample rate and only 1 channel.
+Decoding audio files is CPU and memory intensive. PSRAM external memory is strongly recommended. To use the component on a memory constrained device, define only the announcement pipeline, decrease the buffer size, and set the pipeline transcode setting format to `WAV` with a low sample rate and only 1 channel.
### Network Optimizations
@@ -180,6 +180,8 @@ If you experience out-of-memory issues, you can disable these optimizations by s
In general, decoding FLAC has the lowest CPU usage, but requires a strong WiFi connection. Decoding MP3 requires less data to be sent over WiFi but is more CPU intensive to decode. Decoding WAV is only recommended at low sample rates if streamed over a network connection.
+Decoding OPUS is extremely CPU and memory intensive and may not even decode in real-time on an ESP32. It is only suitable for ESP32-S3 devices with PSRAM.
+
Increasing the buffer size may reduce stuttering, but do not set it to the entire size of the external memory. Each pipeline allocates the configured amount, and this setting also does not take into account other smaller buffers allocated throughout the audio stack.
Only set `task_stack_in_psram` to true if you have many components configured and your logs show that memory allocation failed. It is slower, especially if your PSRAM doesn't support `octal` mode.
diff --git a/src/content/docs/components/media_source/index.mdx b/src/content/docs/components/media_source/index.mdx
new file mode 100644
index 0000000000..7fd6adf470
--- /dev/null
+++ b/src/content/docs/components/media_source/index.mdx
@@ -0,0 +1,23 @@
+---
+description: "Instructions for setting up media sources in ESPHome."
+title: "Media Source Components"
+sidebar:
+ label: "Media Source Components"
+---
+
+The `media_source` domain contains common functionality shared across the
+media source platforms. A media source produces audio data and delivers it
+to a media player, which handles the audio output.
+
+
+
+## Base Media Source Configuration
+
+```yaml
+media_source:
+ - platform: ...
+```
+
+## Platforms
+
+## See Also
diff --git a/src/content/docs/components/modbus_controller.mdx b/src/content/docs/components/modbus_controller.mdx
index 197aec2af9..ba3383d775 100644
--- a/src/content/docs/components/modbus_controller.mdx
+++ b/src/content/docs/components/modbus_controller.mdx
@@ -542,10 +542,12 @@ The response is mapped to the sensor based on `register_count` and offset in byt
> These methods can be called from a lambda.
>
> Here is an example how to set config values to for an EPEVER Trace AN controller.
-> The code synchronizes the localtime of MCU to the epever controller
+> The code synchronizes the local time of the MCU to the epever controller.
> The time is set by writing 12 bytes to register 0x9013.
> Then battery charge settings are sent.
>
+> This example requires a [time component](/components/time/) to be configured (e.g., `homeassistant`, `sntp`).
+>
> ```yaml
> esphome:
> on_boot:
@@ -555,17 +557,16 @@ The response is mapped to the sensor based on `register_count` and offset in byt
> then:
> - lambda: |-
> // get local time and sync to controller
-> time_t now = ::time(nullptr);
-> struct tm *time_info = ::localtime(&now);
-> int seconds = time_info->tm_sec;
-> int minutes = time_info->tm_min;
-> int hour = time_info->tm_hour;
-> int day = time_info->tm_mday;
-> int month = time_info->tm_mon + 1;
-> int year = time_info->tm_year % 100;
+> auto time = ESPTime::from_epoch_local(::time(nullptr));
+> int seconds = time.second;
+> int minutes = time.minute;
+> int hour = time.hour;
+> int day = time.day_of_month;
+> int month = time.month;
+> int year = time.year % 100;
> esphome::modbus_controller::ModbusController *controller = id(epever);
-> // if there is no internet connection localtime returns year 70
-> if (year != 70) {
+> // if time is not yet synced, skip RTC update
+> if (time.is_valid()) {
> // create the payload
> std::vector rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour),
> uint16_t((year << 8) | month)};
diff --git a/src/content/docs/components/mqtt.mdx b/src/content/docs/components/mqtt.mdx
index 3e414c968d..15888b13f4 100644
--- a/src/content/docs/components/mqtt.mdx
+++ b/src/content/docs/components/mqtt.mdx
@@ -93,10 +93,6 @@ mqtt:
- **shutdown_message** (*Optional*, [MQTTMessage](#mqtt-message)): The message to send when
the node shuts down and the connection is closed cleanly. See [Last Will And Birth Messages](#mqtt-last_will_birth) for more information.
-- **ssl_fingerprints** (*Optional*, list): Only on ESP8266. A list of SHA1 hashes used
- for verifying SSL connections. See [SSL Fingerprints](#mqtt-ssl_fingerprints).
- for more information.
-
- **certificate_authority** (*Optional*, string): Only on ESP32. CA certificate in PEM format. See
[TLS (ESP32)](#mqtt-tls-idf) for more information.
@@ -358,33 +354,6 @@ If the birth message and last will message have empty topics or topics
that are different from each other, availability reporting will be
disabled.
-
-
-## SSL Fingerprints
-
-On the ESP8266 you have the option to use SSL connections for MQTT. This feature
-will get expanded to the ESP32 once the base library, AsyncTCP, supports it. Please
-note that the SSL feature only checks the SHA1 hash of the SSL certificate to verify
-the integrity of the connection, so every time the certificate changes, you'll have to
-update the fingerprints variable. Additionally, SHA1 is known to be partially insecure
-and with some computing power the fingerprint can be faked.
-
-To get this fingerprint, first put the broker and port options in the configuration and
-then run the `mqtt-fingerprint` script of ESPHome to get the certificate:
-
-```bash
-esphome mqtt-fingerprint livingroom.yaml
-> SHA1 Fingerprint: a502ff13999f8b398ef1834f1123650b3236fc07
-> Copy above string into mqtt.ssl_fingerprints section of livingroom.yaml
-```
-
-```yaml
-mqtt:
- # ...
- ssl_fingerprints:
- - a502ff13999f8b398ef1834f1123650b3236fc07
-```
-
## TLS (ESP32)
diff --git a/src/content/docs/components/openthread.mdx b/src/content/docs/components/openthread.mdx
index 0d34581a94..7d1a88a16f 100644
--- a/src/content/docs/components/openthread.mdx
+++ b/src/content/docs/components/openthread.mdx
@@ -69,6 +69,10 @@ openthread:
> [!NOTE]
> esphome.ota does not work when poll_period > 0, instead use http_request.ota, timeout and watchdog_timeout need to be tested to find the correct values. Values greater than 100sec may be required.
+- **output_power** (*Optional*, integer): The amount of TX power for the Thread 802.15.4 radio in dBm.
+ Range depends on the chip variant: ESP32-C5/C6 from ``-15dBm`` to ``20dBm``, ESP32-H2 from ``-24dBm`` to ``20dBm``.
+ Defaults to the platform default (typically ``0dBm``). Ensure the configured value complies with local regulatory limits.
+
## Dataset TLV Configuration
It is also possible to supply the entire dataset TLVs from the Thread information in Home Assistant and the individual values will be automatically extracted from it.
diff --git a/src/content/docs/components/safe_mode.mdx b/src/content/docs/components/safe_mode.mdx
index 1b199a3e09..af606cd2cd 100644
--- a/src/content/docs/components/safe_mode.mdx
+++ b/src/content/docs/components/safe_mode.mdx
@@ -46,6 +46,19 @@ safe_mode:
>
> **All other components (for example, displays and sensors) are disabled and cannot be used.**
+
+
+## `safe_mode.mark_successful` Action
+
+This action marks the boot as successful, preventing safe mode from being invoked. This is useful for devices that
+take a sensor reading and then enter deep sleep, rather than waiting for the `boot_is_good_after` time to elapse.
+
+```yaml
+on_...:
+ then:
+ - safe_mode.mark_successful
+```
+
## See Also
- [Safe Mode Button](/components/button/safe_mode/)
diff --git a/src/content/docs/components/sensor/hdc302x.mdx b/src/content/docs/components/sensor/hdc302x.mdx
new file mode 100644
index 0000000000..ca252f7dcd
--- /dev/null
+++ b/src/content/docs/components/sensor/hdc302x.mdx
@@ -0,0 +1,179 @@
+---
+description: "Instructions for setting up HDC302x temperature and humidity sensors."
+title: "HDC302x Temperature and Humidity Sensor"
+---
+
+import { Image } from 'astro:assets';
+import hdc302xFullImg from './images/hdc302x-full.png';
+import temperatureHumidityImg from './images/temperature-humidity.png';
+import APIRef from '@components/APIRef.astro';
+import Figure from '@components/Figure.astro';
+
+The `hdc302x` sensor platform allows you to use your HDC3020, HDC3021, or HDC3022
+([datasheet](https://www.ti.com/lit/ds/symlink/hdc3020.pdf),
+[Users Guide](https://www.ti.com/lit/pdf/snau265),
+[Adafruit](https://www.adafruit.com/product/5989)) sensors with ESPHome.
+
+The HDC3020 is an open cavity package, the HDC3021 includes a removable protective tape for PCB assembly,
+and the HDC3022 has a permanent IP67 PTFE filter for protection against dust and water condensation.
+
+The [I²C Bus](/components/i2c) is required to be set up in your configuration for this sensor to work.
+
+
+
+
+
+```yaml
+# Example configuration entry
+sensor:
+ - platform: hdc302x
+ temperature:
+ name: "Living Room Temperature"
+ humidity:
+ name: "Living Room Humidity"
+ update_interval: 60s
+```
+
+## Configuration variables
+
+- **temperature** (*Optional*): The information for the temperature sensor.
+
+ - All options from [Sensor](/components/sensor/).
+
+- **humidity** (*Optional*): The information for the humidity sensor.
+
+ - All options from [Sensor](/components/sensor/).
+
+- **power_mode** (*Optional*, enum): The power mode used when triggering temperature and humidity measurements. This
+ affects measurement accuracy and sensor power usage.
+ - `HIGH_ACCURACY` (Default): Highest accuracy, slower, higher power usage.
+ - `BALANCED`: Balance between accuracy and power usage.
+ - `LOW_POWER`: Lower power usage, faster, less accurate.
+ - `ULTRA_LOW_POWER`: Lowest power usage, fastest, least accurate.
+
+- **address** (*Optional*, int): Manually specify the I²C address of the sensor.
+ Defaults to `0x44`. Supported addresses are `0x44` through `0x47`.
+
+- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the sensor.
+ Defaults to `60s`.
+
+
+
+## `hdc302x.heater_on` Action
+
+This [action](/automations/actions#all-actions) enables the integrated heater on the sensor with the given ID.
+The heater can be used to remove condensation from the humidity sensor or to verify sensor functionality.
+
+> [!WARNING]
+> **Temperature and humidity readings will be inaccurate while the heater is active.** The heater can raise the die
+> temperature up to 80°C above ambient (depending on supply voltage and power level).
+>
+> **If water has condensed on the sensor, care must be taken to avoid exceeding 100°C.** Raising the temperature too
+> quickly past 100°C can cause water droplets to burst and damage the polymer in the sensor cavity. The temperature
+> rise to 100°C from ambient should take at least 5 to 10 seconds.
+>
+> Heater power depends on VDD -- higher supply voltages produce more heating. Take care when using higher power
+> levels at 5V.
+>
+> The heater evaporates condensate but **does not remove dissolved contaminants** on open cavity sensors
+> (HDC3020, HDC3021). Contaminant residue may impact humidity measurements and cause drift. The HDC3022's
+> IP67 PTFE filter provides protection from dissolved contaminants during evaporation.
+
+```yaml
+on_...:
+ then:
+ - hdc302x.heater_on:
+ id: my_hdc302x
+ power: QUARTER
+ duration: 5s
+```
+
+- **id** (**Required**, [ID](/guides/configuration-types#id)): The ID of the HDC302x sensor.
+- **power** (*Optional*): The heater power level. Higher power removes condensation faster
+ but increases die temperature. Defaults to `QUARTER`.
+ - `QUARTER`: Lowest power, safest option.
+ - `HALF`
+ - `FULL`: Maximum power. Use with caution -- see warning above.
+ - A raw integer value between `0` and `16383` may also be used for fine-grained control
+ of the 14-bit heater current control. See Table 7-15 in the [datasheet](https://www.ti.com/lit/ds/symlink/hdc3020.pdf).
+- **duration** (*Optional*, [Time](/guides/configuration-types#time)): Duration to run the heater.
+ Set to `0s` to keep the heater on until manually disabled with `hdc302x.heater_off`. Defaults to `5s`.
+
+
+
+## `hdc302x.heater_off` Action
+
+This [action](/automations/actions#all-actions) disables the integrated heater on the sensor with the given ID.
+After turning off the heater, allow several minutes for the sensor to cool down before expecting accurate readings.
+
+```yaml
+on_...:
+ then:
+ - hdc302x.heater_off: my_hdc302x
+```
+
+## Heater Usage
+
+In condensing environments, moisture can form on the sensor when the ambient temperature drops below the
+dew point, preventing accurate humidity readings. The integrated heater can be used to evaporate this condensation.
+
+> [!WARNING]
+> Read the [heater safety notes above](#hdc302x-heater_on_action) before using the heater. Condensation
+> removal timings and power requirements vary depending on your board layout and supply voltage.
+>
+> See section 7.3.7 in the [datasheet](https://www.ti.com/lit/ds/symlink/hdc3020.pdf), and section 3.6 in the
+> [HDC3x Silicon Users Guide](https://www.ti.com/lit/pdf/snau265) for detailed guidance.
+
+To remove condensation, enable the heater with `duration: 0s` to keep it running, monitor the humidity reading,
+and disable the heater once the reading drops near `0%` (indicating the condensation has been removed) or after
+a maximum of 5 minutes. After disabling the heater, allow several minutes for the sensor to cool before expecting
+accurate readings.
+
+```yaml
+sensor:
+ - platform: hdc302x
+ id: my_hdc302x
+ temperature:
+ name: "Temperature"
+ humidity:
+ name: "Humidity"
+ id: hdc302x_humidity
+ on_value_range:
+ - above: 95.0
+ then:
+ - script.execute: hdc302x_condensation_removal
+ update_interval: 10s
+
+script:
+ - id: hdc302x_condensation_removal
+ mode: single
+ then:
+ - hdc302x.heater_on:
+ id: my_hdc302x
+ power: QUARTER
+ duration: 0s
+ - wait_until:
+ condition:
+ sensor.in_range:
+ id: hdc302x_humidity
+ below: 1.0
+ timeout: 5min
+ - hdc302x.heater_off: my_hdc302x
+```
+
+## See Also
+
+- [Sensor Filters](/components/sensor/#sensor-filters)
+- [Absolute Humidity](/components/sensor/absolute_humidity/)
+- [DHT Temperature+Humidity Sensor](/components/sensor/dht/)
+- [DHT12 Temperature+Humidity Sensor](/components/sensor/dht12/)
+- [HTU21D | Si7021 | SHT21 Temperature & Humidity Sensor](/components/sensor/htu21d/)
+- [SHT3X-D Temperature+Humidity Sensor](/components/sensor/sht3xd/)
+- [HDC1080 Temperature+Humidity Sensor](/components/sensor/hdc1080/)
+- [HDC2010 High Precision Temperature and Humidity Sensor](/components/sensor/hdc2010/)
+-
diff --git a/src/content/docs/components/sensor/images/hdc302x-full.png b/src/content/docs/components/sensor/images/hdc302x-full.png
new file mode 100644
index 0000000000..c6edcb3750
Binary files /dev/null and b/src/content/docs/components/sensor/images/hdc302x-full.png differ
diff --git a/src/content/docs/components/sensor/images/jst6pin.png b/src/content/docs/components/sensor/images/jst6pin.png
index 859b977657..5dd9f72e78 100644
Binary files a/src/content/docs/components/sensor/images/jst6pin.png and b/src/content/docs/components/sensor/images/jst6pin.png differ
diff --git a/src/content/docs/components/sensor/lps22.mdx b/src/content/docs/components/sensor/lps22.mdx
index aa6339e344..d2a7693d42 100644
--- a/src/content/docs/components/sensor/lps22.mdx
+++ b/src/content/docs/components/sensor/lps22.mdx
@@ -6,8 +6,9 @@ title: "LPS22 Barometric Pressure Sensor"
import { Image } from 'astro:assets';
import APIRef from '@components/APIRef.astro';
-The `lps22` sensor platform allows you to use your LPS22HB or LPS22HH pressure sensor
-([datasheet](https://www.st.com/resource/en/application_note/an4672-lps22hblps25hb-digital-pressure-sensors-hardware-guidelines-for-system-integration-stmicroelectronics.pdf)) with ESPHome.
+The `lps22` sensor platform allows you to use your [LPS22HB](https://www.st.com/resource/en/datasheet/lps22hb.pdf),
+[LPS22HH](https://www.st.com/resource/en/datasheet/lps22hh.pdf) and [LPS22DF](https://www.st.com/resource/en/datasheet/lps22df.pdf)
+pressure sensors with ESPHome.
The [I²C Bus](/components/i2c) is required to be set up in your configuration for this sensor to work.
diff --git a/src/content/docs/components/sensor/sen5x.mdx b/src/content/docs/components/sensor/sen5x.mdx
index dc4e754224..f1781a380b 100644
--- a/src/content/docs/components/sensor/sen5x.mdx
+++ b/src/content/docs/components/sensor/sen5x.mdx
@@ -208,6 +208,7 @@ on_...:
- [Air Quality Index (AQI)](/components/sensor/aqi/)
- [Sensor Filters](/components/sensor#sensor-filters)
+- [Sen6x Series Environmental sensor](/components/sensor/sen6x/)
- [Absolute Humidity](/components/sensor/absolute_humidity/)
- [SDS011 Particulate Matter Sensor](/components/sensor/sds011/)
- [PMSX003 Particulate Matter Sensor](/components/sensor/pmsx003/)
diff --git a/src/content/docs/components/sensor/sen6x.mdx b/src/content/docs/components/sensor/sen6x.mdx
new file mode 100644
index 0000000000..da3578e78b
--- /dev/null
+++ b/src/content/docs/components/sensor/sen6x.mdx
@@ -0,0 +1,149 @@
+---
+description: "Instructions for setting up SEN6x Series Environmental Sensor for PM, RH/T, VOC, NOx, CO2 and HCHO measurements."
+title: "SEN6x Series Environmental Sensor"
+---
+
+import APIRef from '@components/APIRef.astro';
+
+The `sen6x` sensor platform allows you to use your Sensirion
+[SEN62](https://sensirion.com/products/catalog/SEN62/),
+[SEN63C](https://sensirion.com/products/catalog/SEN63C/),
+[SEN65](https://sensirion.com/products/catalog/SEN65/),
+[SEN66](https://sensirion.com/products/catalog/SEN66/),
+[SEN68](https://sensirion.com/products/catalog/SEN68/) and
+[SEN69C](https://sensirion.com/products/catalog/SEN69C/) Environmental sensor
+([datasheet](https://sensirion.com/media/documents/FAFC548D/693FBB15/PS_DS_SEN6x.pdf))
+sensors with ESPHome.
+
+The [I²C Bus](/components/i2c) is required to be set up in your configuration for this sensor to work.
+
+
+
+| Sensor | PM | RH/T | VOC | NOx | CO₂ | HCHO |
+|--------|:--:|:----:|:---:|:---:|:---:|:----:|
+| SEN62 | ✓ | ✓ | | | | |
+| SEN63C | ✓ | ✓ | | | ✓ | |
+| SEN65 | ✓ | ✓ | ✓ | ✓ | | |
+| SEN66 | ✓ | ✓ | ✓ | ✓ | ✓ | |
+| SEN68 | ✓ | ✓ | ✓ | ✓ | | ✓ |
+| SEN69C | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+```yaml
+# Example configuration entry
+sensor:
+ - platform: sen6x
+ type: SEN69C
+ pm_1_0:
+ name: PM <1µm Weight concentration
+ pm_2_5:
+ name: PM <2.5µm Weight concentration
+ pm_4_0:
+ name: PM <4µm Weight concentration
+ pm_10_0:
+ name: PM <10µm Weight concentration
+ temperature:
+ name: Temperature
+ humidity:
+ name: Humidity
+ voc:
+ name: VOC
+ nox:
+ name: NOx
+ co2:
+ name: Carbon Dioxide
+ formaldehyde:
+ name: Formaldehyde
+```
+
+## Configuration variables
+
+- **type** (*Optional*): The type of sensor. If not specified, sensor type will be auto-detected. If specified,
+ the value will override auto-detection. In case of mismatch, a warning will be provided in the log.
+
+ - SEN62
+ - SEN63C
+ - SEN65
+ - SEN66
+ - SEN68
+ - SEN69C
+
+- **pm_1_0** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 1μm.
+ Readings in µg/m³.
+
+ - All options from [Sensor](/components/sensor).
+
+- **pm_2_5** (*Optional*): The information for the **Weight Concentration** sensor for fine particles up to 2.5μm.
+ Readings in µg/m³.
+
+ - All options from [Sensor](/components/sensor).
+
+- **pm_4_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 4μm.
+ Readings in µg/m³.
+
+ - All options from [Sensor](/components/sensor).
+
+- **pm_10_0** (*Optional*): The information for the **Weight Concentration** sensor for coarse particles up to 10μm.
+ Readings in µg/m³.
+
+ - All options from [Sensor](/components/sensor).
+
+- **temperature** (*Optional*): Temperature.
+
+ - All options from [Sensor](/components/sensor).
+
+- **humidity** (*Optional*): Relative Humidity.
+
+ - All options from [Sensor](/components/sensor).
+
+- **voc** (*Optional*): VOC Index. Note: only available with SEN65, SEN66, SEN68 or SEN69C. The sensor will be
+ ignored on unsupported models.
+
+ - All options from [Sensor](/components/sensor).
+
+- **nox** (*Optional*): NOx Index. Note: only available with SEN65, SEN66, SEN68 or SEN69C. The sensor will be
+ ignored on unsupported models.
+
+ - All options from [Sensor](/components/sensor).
+
+- **co2** (*Optional*): The **carbon dioxide** concentration in ppm. Note: only available with SEN63C, SEN66 or
+ SEN69C. The sensor will be ignored on unsupported models.
+
+ - All options from [Sensor](/components/sensor).
+
+- **formaldehyde** (*Optional*): The Formaldehyde (HCHO) concentration in ppb. Note: only available with SEN68 or
+ SEN69C. The sensor will be ignored on unsupported models.
+
+ - All options from [Sensor](/components/sensor).
+
+- **address** (*Optional*, int): Manually specify the I²C address of the sensor.
+ Defaults to `0x6B`.
+
+- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the sensor.
+ Defaults to `60s`.
+
+> [!NOTE]
+> The sensor needs about a minute "warm-up". The VOC and NOx gas index algorithm needs a
+> number of samples before the values stabilize.
+
+## Wiring
+
+The sensor has a JST GHR-06V-S 6 pin type connector, with a 1.25mm pitch. The cable needs this connector:
+
+
+
+Pins 2 and 5 (GND) and pins 1 and 6 (VDD) are connected internally.
+
+For better stability, the SDA and SCL lines require suitable pull-up resistors.
+
+## See Also
+
+- [Sensor Filters](/components/sensor#sensor-filters)
+- [Sen5x Series Environmental sensor](/components/sensor/sen5x/)
+- [Absolute Humidity](/components/sensor/absolute_humidity/)
+- [SDS011 Particulate Matter Sensor](/components/sensor/sds011/)
+- [PMSX003 Particulate Matter Sensor](/components/sensor/pmsx003/)
+- [CCS811 eCO_2 and Volatile Organic Compound Sensor](/components/sensor/ccs811/)
+- [SCD4X CO₂, Temperature and Relative Humidity Sensor](/components/sensor/scd4x/)
+- [SPS30 Particulate Matter Sensor](/components/sensor/sps30/)
+- [SGP40 Volatile Organic Compound Sensor and SGP41 VOC and NOx Sensor](/components/sensor/sgp4x/)
+-
diff --git a/src/content/docs/components/text_sensor/version.mdx b/src/content/docs/components/text_sensor/version.mdx
index c4c3711f9d..0bb0baa0db 100644
--- a/src/content/docs/components/text_sensor/version.mdx
+++ b/src/content/docs/components/text_sensor/version.mdx
@@ -22,9 +22,10 @@ text_sensor:
## Configuration variables
- **hide_timestamp** (*Optional*, boolean): Allows you to hide the compilation timestamp from the version string. Defaults to `false`.
+- **hide_hash** (*Optional*, boolean): Allows you to hide the config hash from the version string. Defaults to `false`.
- All other options from [Text Sensor](/components/text_sensor#config-text_sensor).
-## Disabling the compilation timestamp
+## Disabling timestamp and hash
```yaml
# Example configuration entry
@@ -32,11 +33,10 @@ text_sensor:
- platform: version
name: "ESPHome Version"
hide_timestamp: true
+ hide_hash: true
```
-This will, for example, change the output of the sensor from:
-
-`2024.6.0-dev May 30 2024, 09:07:35` to just `2024.6.0-dev`
+This will shorten the version string to be just like: `2026.1.0`
## See Also
diff --git a/src/content/docs/components/touchscreen/gt911.mdx b/src/content/docs/components/touchscreen/gt911.mdx
index 342cee47d0..7020d87ee0 100644
--- a/src/content/docs/components/touchscreen/gt911.mdx
+++ b/src/content/docs/components/touchscreen/gt911.mdx
@@ -10,7 +10,7 @@ import APIRef from '@components/APIRef.astro';
The `gt911` touchscreen platform allows using the touch screen controllers based on the gt911 chip with ESPHome.
The [I²C](/components/i2c) is required to be set up in your configuration for this touchscreen to work.
-This controller is used in the Espressif ESP32-S3-BOX-3 and the m5paper;
+This controller is used in the Espressif ESP32-S3-BOX-3 and the m5paper as well as some Waveshare-ESP32-S3-Touch devices;
-## Base Touchscreen Configuration
+## Base Touchscreen Configurations
```yaml
-# Example configuration entry
+# Example configuration entry for board with interrupt line run directly to ESP GPIO
touchscreen:
platform: gt911
id: my_touchscreen
interrupt_pin: GPIOXX
```
+```yaml
+# Example configuration entry for board with interrupt line run through IO Expander
+touchscreen:
+ platform: gt911
+ id: my_touchscreen
+ interrupt_pin:
+ waveshare_io_ch32v003: wave_io_hub
+ number: 2
+```
+
### Configuration variables
- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually set the ID of this touchscreen.
-- **interrupt_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The touch detection pin.
+- **interrupt_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The touch detection pin if run to an on-MCU pin.
+If the touchscreen interrupt signal is wired through an IO Expander rather than directly to an ESP GPIO this will allow for configuration of touchscreen address
+at boot but will not be used for interrupts and the driver will fall back to polling operation.
- **reset_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The reset pin.
- All other options from [Touchscreen](/components/touchscreen#config-touchscreen).
diff --git a/src/content/docs/components/wifi.mdx b/src/content/docs/components/wifi.mdx
index 44dfe6183d..4ec5b49c09 100644
--- a/src/content/docs/components/wifi.mdx
+++ b/src/content/docs/components/wifi.mdx
@@ -128,6 +128,10 @@ wifi:
- **enable_btm** (*Optional*, bool): Only on `esp32`. Enable 802.11v BSS Transition Management support.
- **enable_rrm** (*Optional*, bool): Only on `esp32`. Enable 802.11k Radio Resource Management support.
+- **band_mode** (*Optional*, string): Only on `esp32-c5`. Controls which WiFi frequency band the device uses.
+ Possible values are `AUTO` (use both 2.4 GHz and 5 GHz), `2.4GHZ` (2.4 GHz only), and `5GHZ` (5 GHz only).
+ If not specified, it defaults to `AUTO`.
+
- **post_connect_roaming** (*Optional*, bool): Enable basic post-connect
roaming for stationary devices. After connecting to a non-hidden network,
the device will periodically check for better access points with the same
diff --git a/src/content/docs/guides/cli.mdx b/src/content/docs/guides/cli.mdx
index cc27f22eae..eec53c5e79 100644
--- a/src/content/docs/guides/cli.mdx
+++ b/src/content/docs/guides/cli.mdx
@@ -189,11 +189,6 @@ node).
The `esphome wizard ` command starts the ESPHome configuration creation wizard.
-### `mqtt-fingerprint` Command
-
-The `esphome mqtt-fingerprint ` command shows the MQTT SSL fingerprints of the remote used
-for SSL MQTT connections. See [SSL Fingerprints](/components/mqtt#mqtt-ssl_fingerprints).
-
### `version` Command
The `esphome version` command shows the current ESPHome version and exits.
diff --git a/src/content/docs/guides/security_best_practices.mdx b/src/content/docs/guides/security_best_practices.mdx
index 02985dc86e..e98a229c37 100644
--- a/src/content/docs/guides/security_best_practices.mdx
+++ b/src/content/docs/guides/security_best_practices.mdx
@@ -420,9 +420,6 @@ mqtt:
broker: !secret mqtt_broker
username: !secret mqtt_username
password: !secret mqtt_password
- # For ESP8266: Use TLS with SSL fingerprints
- # ssl_fingerprints:
- # - "SHA1_FINGERPRINT_HERE"
# For ESP32 with esp-idf: Use TLS with certificate authority
# certificate_authority: ca_cert.pem