# ravensystem/esp-homekit-devices architecture

> Architecture diagram of the GitHub repository ravensystem/esp-homekit-devices, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravensystem/esp-homekit-devices
- Repository: https://github.com/ravensystem/esp-homekit-devices

## Overview

HAA is embedded firmware that gives ESP32/ESP8266 devices native Apple HomeKit support and configurable accessory behavior. The user-facing path is device setup and configuration, then HomeKit accessory interaction; separate installer firmware supports device installation and updating. The README also describes broad HomeKit service support and companion-app management. Source excerpts are sparse, so the graph distinguishes documented capabilities from directly evidenced calls and leaves uncertain wiring unconnected.

Main entry points: [`HAA/HAA_Main/main/main.c`](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Main/main/main.c) (Accessory services), [`libs/homekit-rsf/src/server.c`](https://github.com/ravensystem/esp-homekit-devices/blob/master/libs/homekit-rsf/src/server.c) (HomeKit server), [`HAA/HAA_Installer/main/main.c`](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Installer/main/main.c) (Installer firmware), [`libs/homekit-rsf/src/storage.c`](https://github.com/ravensystem/esp-homekit-devices/blob/master/libs/homekit-rsf/src/storage.c) (Pairing storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["HAA Firmware"]
  node_config["Accessory configuration<br/>[main.c]"]
  node_services["Accessory services<br/>[main.c]"]
end

subgraph group_homekit["HomeKit Runtime"]
  node_hkserver["HomeKit server<br/>[server.c]"]
  node_pairing[("Pairing storage<br/>[storage.c]")]
end

subgraph group_install["Installation"]
  node_installer["Installer firmware<br/>[main.c]"]
  node_setup["Setup mode<br/>[setup.c]"]
  node_ota["Firmware update<br/>[ota.c]"]
  node_mgosinstaller["Migration installer<br/>[main.c]"]
end

subgraph group_deviceio["Device I/O"]
  node_effects["Light effects<br/>[lightbulb_fx.c]"]
  node_drivers["Hardware drivers"]
end

node_user(("Device owner"))
node_homeapp(("Apple Home"))

node_user -.->|"starts setup"| node_installer
node_installer -->|"initializes Wi-Fi"| node_setup
node_installer -.->|"supports updates"| node_ota
node_user -.->|"customizes device"| node_config
node_config -.->|"configures services"| node_services
node_services -.->|"exposes accessory"| node_hkserver
node_hkserver -.->|"serves HomeKit"| node_homeapp
node_hkserver -->|"uses pairing data"| node_pairing
node_services -.->|"controls effects"| node_effects
node_services -.->|"controls hardware"| node_drivers
node_user -.->|"starts migration"| node_mgosinstaller

click node_config "https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Main/main/main.c"
click node_services "https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Main/main/main.c"
click node_effects "https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Main/main/lightbulb_fx.c"
click node_drivers "https://github.com/ravensystem/esp-homekit-devices/tree/master/libs"
click node_hkserver "https://github.com/ravensystem/esp-homekit-devices/blob/master/libs/homekit-rsf/src/server.c"
click node_pairing "https://github.com/ravensystem/esp-homekit-devices/blob/master/libs/homekit-rsf/src/storage.c"
click node_installer "https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Installer/main/main.c"
click node_setup "https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Installer/main/setup.c"
click node_ota "https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Installer/main/ota.c"
click node_mgosinstaller "https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_mgos32_Installer/main/main.c"

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_config,node_services toneBlue
class node_hkserver,node_pairing toneAmber
class node_installer,node_setup,node_ota,node_mgosinstaller toneMint
class node_effects,node_drivers toneRose
class node_user,node_homeapp toneIndigo
```

## Components

### HAA Firmware

- [Accessory configuration](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Main/main/main.c): `HAA/HAA_Main/main/main.c`
- [Accessory services](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Main/main/main.c): `HAA/HAA_Main/main/main.c`

### HomeKit Runtime

- [HomeKit server](https://github.com/ravensystem/esp-homekit-devices/blob/master/libs/homekit-rsf/src/server.c): `libs/homekit-rsf/src/server.c`
- [Pairing storage](https://github.com/ravensystem/esp-homekit-devices/blob/master/libs/homekit-rsf/src/storage.c): `libs/homekit-rsf/src/storage.c`

### Installation

- [Installer firmware](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Installer/main/main.c): `HAA/HAA_Installer/main/main.c`
- [Setup mode](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Installer/main/setup.c): `HAA/HAA_Installer/main/setup.c`
- [Firmware update](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Installer/main/ota.c): `HAA/HAA_Installer/main/ota.c`
- [Migration installer](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_mgos32_Installer/main/main.c): `HAA/HAA_mgos32_Installer/main/main.c`

### Device I/O

- [Light effects](https://github.com/ravensystem/esp-homekit-devices/blob/master/HAA/HAA_Main/main/lightbulb_fx.c): `HAA/HAA_Main/main/lightbulb_fx.c`
- [Hardware drivers](https://github.com/ravensystem/esp-homekit-devices/tree/master/libs): `libs`

### Other components

- **Device owner**
- **Apple Home**

## Connections

- Device owner → Installer firmware: starts setup
- Installer firmware → Setup mode: initializes Wi-Fi (evidence: `HAA/HAA_Installer/main/main.c`)
- Installer firmware → Firmware update: supports updates
- Device owner → Accessory configuration: customizes device
- Accessory configuration → Accessory services: configures services
- Accessory services → HomeKit server: exposes accessory
- HomeKit server → Apple Home: serves HomeKit
- HomeKit server → Pairing storage: uses pairing data (evidence: `libs/homekit-rsf/src/server.c`)
- Accessory services → Light effects: controls effects
- Accessory services → Hardware drivers: controls hardware
- Device owner → Migration installer: starts migration
