Documentation

These pages cover installation, protocols, routing, media and diagnostics beyond the project overview in the top-level README.

Pick your path

Need	Document
Learn the complete everyday workflow	User guide
Use redirects and advanced automations	Automation cookbook
Review the current release	What is new in 2026.9.0
Choose a board and maintained YAML	Deployment guide
Complete the shortest supported setup	Quick start
Upgrade without breaking automations	Breaking changes
Configure ESP and HA options	Configuration reference
Diagnose calls and media	Testing and debug
Resolve a specific failure	Troubleshooting

Published release notes live with their immutable artifacts on GitHub: 2026.9.0, 2026.8.2-dev, 2026.8.1-dev, 2026.8.0, 2026.7.1 and 2026.7.0. The repository keeps only the current upgrade contract.

Architecture and protocols

Topic	Document
Component and lifecycle ownership	Architecture
Canonical end-to-end paths	Call flows
SIP, SDP and RTP endpoint contract	ESP VoIP profile
Retired proprietary protocol boundary	Intercom protocol
Phonebook rows and media capabilities	Phonebook protocol
Name, extension, group and trunk resolution	Dial-plan resolver
ESP entities published to HA	ESP entity surface

Features

Topic	Document
Home Assistant actions and side effects	Services
Contextual routing recipes	Automation cookbook
Ring and conference groups	Groups
Provider registration and external routing	SIP trunk
Browser and P4 video codec paths	SIP video

Qualification

The test matrix separates deterministic protocol checks from real ESP timing, browser media and hardware-in-the-loop evidence. Espressif components records component versions, local modifications and licensing boundaries.

Per-component docs

Each ESPHome component ships its own README with the full option list, YAML snippets and component-specific notes:

• voip_stack, the ESP SIP phone component.
• esp_video_camera, the ESP32-P4 Espressif V4L2 camera surface used by the native camera entity and SIP video sources.
• esp_jpeg_video_source, esp_h264_video_source and p4_video_renderer, the compile-gated P4 SIP video TX and RX paths.
• esp_audio_stack, the coordinated full-duplex audio backend for shared codec buses, dual I2S MEMS/amp boards that need software reference handling, Espressif rate/layout conversion, AEC reference capture, PSRAM placement and post-processor mic output. On AEC/AFE profiles, its standard ESPHome microphone facade is the cleaned stream consumed by MWW, Voice Assistant and VoIP while media/TTS keeps playing through the speaker.
• Full-experience media now uses ESPHome's source-based speaker_source path: HA media, announcements, local files and optional Sendspin streams feed one media player before the mixer arbitrates with VoIP and Voice Assistant. The local speaker fork remains documented for custom YAMLs that still use platform: speaker.
• runtime_controller, a generic YAML-programmed reducer used by maintained full-experience profiles to derive LED, LVGL/display, audio ducking, ringtone and timer policies from one state snapshot. It is control-plane only and does not process audio samples.
• esp_aec, standalone ESP-SR echo cancellation.
• esp_afe, the full Espressif AFE pipeline (AEC + NS + VAD + AGC, optional dual-mic Speech Enhancement).
• internal shared audio primitives used privately by the local media/voice component forks and by the split audio-stack repository.
• voip_simulator, an internal test/simulation component used by the virtual device harness. It is not a production YAML component.