# axiomantic/esphome-satellite architecture

> Architecture diagram of the GitHub repository axiomantic/esphome-satellite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/axiomantic/esphome-satellite
- Repository: https://github.com/axiomantic/esphome-satellite
- Video tour (about a minute): https://gitdiagram.com/axiomantic/esphome-satellite/video

## Overview

esphome-satellite is ESPHome firmware and a Home Assistant integration for voice satellites. The main device workflow captures microphone audio, coordinates voice-assistant state and audio feedback, and uses speaker hardware for playback; the README highlights protections against self-hearing and idle stop-word triggers, plus recovery on pipeline or connection errors. The Home Assistant integration adds conversation, STT, and configurable addressing gatekeepers. Sampled firmware excerpts show microphone buffering and audio output behavior, but not the full state machine or all firmware-to-server wiring; those links are omitted where evidence is unavailable.

Main entry points: [`custom_components/esphome_satellite/client_factory.py`](https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/client_factory.py) (Gatekeeper factory), [`components/i2s_audio/speaker/i2s_audio_speaker.cpp`](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/i2s_audio_speaker.cpp) (I2S speaker), [`components/i2s_audio/microphone/i2s_audio_microphone.cpp`](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/microphone/i2s_audio_microphone.cpp) (I2S microphone), [`src/pcm_sound_player.h`](https://github.com/axiomantic/esphome-satellite/blob/main/src/pcm_sound_player.h) (PCM sound player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_supervisor["Voice Supervision"]
  node_va["Voice assistant"]
  node_pcm_player["PCM sound player<br/>[pcm_sound_player.h]"]
  node_sound_data["Built-in sound themes<br/>[sound_data.h]"]
end

subgraph group_audio["Audio I/O"]
  node_mic_source["Microphone source"]
  node_mic_base["Microphone interface<br/>[microphone.h]"]
  node_i2s_mic["I2S microphone"]
  node_i2s_core["I2S audio core<br/>[i2s_audio.h]"]
  node_resampler["Speaker resampler"]
  node_speaker["I2S speaker"]
  node_standard_speaker["Standard I2S output"]
  node_spdif["SPDIF output"]
  node_spdif_encoder["SPDIF encoder<br/>[spdif_encoder.cpp]"]
end

subgraph group_ha["Home Assistant"]
  node_conversation["Conversation handling<br/>[conversation.py]"]
  node_stt["Speech-to-text<br/>[stt.py]"]
  node_factory["Gatekeeper factory<br/>[client_factory.py]"]
  node_llm["LLM gatekeeper<br/>[llm_client.py]"]
  node_systemone["System One client"]
end

subgraph group_hardware["Board Hardware"]
  node_hardware["XVF3800 hardware<br/>[xvf3800_hardware.h]"]
  node_dac["AIC3104 DAC<br/>[aic3104.cpp]"]
end

node_user(("Voice user"))
node_ha_user(("Home Assistant user"))
node_inference(("Inference endpoint"))

node_user -->|"speaks to"| node_i2s_mic
node_i2s_mic -->|"implements"| node_mic_base
node_mic_source -->|"reads from"| node_mic_base
node_va -->|"buffers audio from"| node_mic_source
node_i2s_mic -->|"uses"| node_i2s_core
node_resampler -->|"writes to"| node_speaker
node_standard_speaker -->|"implements output"| node_speaker
node_spdif -->|"uses interface"| node_speaker
node_spdif -->|"uses encoder"| node_spdif_encoder
node_speaker -.->|"accepts resampled stream"| node_resampler
node_pcm_player -->|"looks up sounds"| node_sound_data
node_pcm_player -->|"uses board audio"| node_hardware
node_dac -.->|"supports board audio"| node_hardware
node_ha_user -->|"starts conversation"| node_conversation
node_conversation -->|"creates gatekeeper"| node_factory
node_stt -->|"creates gatekeeper"| node_factory
node_factory -->|"selects client"| node_llm
node_factory -->|"selects client"| node_systemone
node_llm -->|"posts classification"| node_inference
node_systemone -->|"posts inference request"| node_inference

click node_va "https://github.com/axiomantic/esphome-satellite/blob/main/components/voice_assistant/voice_assistant.cpp"
click node_mic_source "https://github.com/axiomantic/esphome-satellite/blob/main/components/microphone/microphone_source.cpp"
click node_mic_base "https://github.com/axiomantic/esphome-satellite/blob/main/components/microphone/microphone.h"
click node_i2s_mic "https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/microphone/i2s_audio_microphone.cpp"
click node_i2s_core "https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/i2s_audio.h"
click node_resampler "https://github.com/axiomantic/esphome-satellite/blob/main/components/resampler/speaker/resampler_speaker.cpp"
click node_speaker "https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/i2s_audio_speaker.cpp"
click node_standard_speaker "https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/i2s_audio_speaker_standard.cpp"
click node_spdif "https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/i2s_audio_spdif.cpp"
click node_spdif_encoder "https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/spdif_encoder.cpp"
click node_pcm_player "https://github.com/axiomantic/esphome-satellite/blob/main/src/pcm_sound_player.h"
click node_sound_data "https://github.com/axiomantic/esphome-satellite/blob/main/src/sound_data.h"
click node_hardware "https://github.com/axiomantic/esphome-satellite/blob/main/src/xvf3800_hardware.h"
click node_dac "https://github.com/axiomantic/esphome-satellite/blob/main/components/aic3104/aic3104.cpp"
click node_conversation "https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/conversation.py"
click node_stt "https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/stt.py"
click node_factory "https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/client_factory.py"
click node_llm "https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/llm_client.py"
click node_systemone "https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/systemone_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_va,node_pcm_player,node_sound_data,node_user,node_ha_user toneBlue
class node_mic_source,node_mic_base,node_i2s_mic,node_i2s_core,node_resampler,node_speaker,node_standard_speaker,node_spdif,node_spdif_encoder toneAmber
class node_conversation,node_stt,node_factory,node_llm,node_systemone toneMint
class node_hardware,node_dac toneRose
class node_inference toneIndigo
```

## Components

### Voice Supervision

- [Voice assistant](https://github.com/axiomantic/esphome-satellite/blob/main/components/voice_assistant/voice_assistant.cpp): `components/voice_assistant/voice_assistant.cpp`
- [PCM sound player](https://github.com/axiomantic/esphome-satellite/blob/main/src/pcm_sound_player.h): `src/pcm_sound_player.h`
- [Built-in sound themes](https://github.com/axiomantic/esphome-satellite/blob/main/src/sound_data.h): `src/sound_data.h`

### Audio I/O

- [Microphone source](https://github.com/axiomantic/esphome-satellite/blob/main/components/microphone/microphone_source.cpp): `components/microphone/microphone_source.cpp`
- [Microphone interface](https://github.com/axiomantic/esphome-satellite/blob/main/components/microphone/microphone.h): `components/microphone/microphone.h`
- [I2S microphone](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/microphone/i2s_audio_microphone.cpp): `components/i2s_audio/microphone/i2s_audio_microphone.cpp`
- [I2S audio core](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/i2s_audio.h): `components/i2s_audio/i2s_audio.h`
- [Speaker resampler](https://github.com/axiomantic/esphome-satellite/blob/main/components/resampler/speaker/resampler_speaker.cpp): `components/resampler/speaker/resampler_speaker.cpp`
- [I2S speaker](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/i2s_audio_speaker.cpp): `components/i2s_audio/speaker/i2s_audio_speaker.cpp`
- [Standard I2S output](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/i2s_audio_speaker_standard.cpp): `components/i2s_audio/speaker/i2s_audio_speaker_standard.cpp`
- [SPDIF output](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/i2s_audio_spdif.cpp): `components/i2s_audio/speaker/i2s_audio_spdif.cpp`
- [SPDIF encoder](https://github.com/axiomantic/esphome-satellite/blob/main/components/i2s_audio/speaker/spdif_encoder.cpp): `components/i2s_audio/speaker/spdif_encoder.cpp`

### Home Assistant

- [Conversation handling](https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/conversation.py): `custom_components/esphome_satellite/conversation.py`
- [Speech-to-text](https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/stt.py): `custom_components/esphome_satellite/stt.py`
- [Gatekeeper factory](https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/client_factory.py): `custom_components/esphome_satellite/client_factory.py`
- [LLM gatekeeper](https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/llm_client.py): `custom_components/esphome_satellite/llm_client.py`
- [System One client](https://github.com/axiomantic/esphome-satellite/blob/main/custom_components/esphome_satellite/systemone_client.py): `custom_components/esphome_satellite/systemone_client.py`

### Board Hardware

- [XVF3800 hardware](https://github.com/axiomantic/esphome-satellite/blob/main/src/xvf3800_hardware.h): `src/xvf3800_hardware.h`
- [AIC3104 DAC](https://github.com/axiomantic/esphome-satellite/blob/main/components/aic3104/aic3104.cpp): `components/aic3104/aic3104.cpp`

### Other components

- **Voice user**
- **Home Assistant user**
- **Inference endpoint**

## Connections

- Voice user → I2S microphone: speaks to
- I2S microphone → Microphone interface: implements
- Microphone source → Microphone interface: reads from
- Voice assistant → Microphone source: buffers audio from (evidence: `components/voice_assistant/voice_assistant.cpp`)
- I2S microphone → I2S audio core: uses
- Speaker resampler → I2S speaker: writes to (evidence: `components/resampler/speaker/resampler_speaker.cpp`)
- Standard I2S output → I2S speaker: implements output
- SPDIF output → I2S speaker: uses interface
- SPDIF output → SPDIF encoder: uses encoder
- I2S speaker → Speaker resampler: accepts resampled stream
- PCM sound player → Built-in sound themes: looks up sounds (evidence: `src/pcm_sound_player.h`)
- PCM sound player → XVF3800 hardware: uses board audio (evidence: `src/pcm_sound_player.h`)
- AIC3104 DAC → XVF3800 hardware: supports board audio
- Home Assistant user → Conversation handling: starts conversation
- Conversation handling → Gatekeeper factory: creates gatekeeper (evidence: `custom_components/esphome_satellite/conversation.py`)
- Speech-to-text → Gatekeeper factory: creates gatekeeper (evidence: `custom_components/esphome_satellite/stt.py`)
- Gatekeeper factory → LLM gatekeeper: selects client (evidence: `custom_components/esphome_satellite/client_factory.py`)
- Gatekeeper factory → System One client: selects client (evidence: `custom_components/esphome_satellite/client_factory.py`)
- LLM gatekeeper → Inference endpoint: posts classification (evidence: `custom_components/esphome_satellite/llm_client.py`)
- System One client → Inference endpoint: posts inference request (evidence: `custom_components/esphome_satellite/systemone_client.py`)
