# tomquist/esphome-b2500 architecture

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

- Interactive diagram: https://gitdiagram.com/tomquist/esphome-b2500
- Repository: https://github.com/tomquist/esphome-b2500

## Overview

This repository combines a browser-based B2500 configuration and firmware workflow with the ESPHome component that runs on the resulting ESP32 firmware. The user edits and validates settings, previews or exports YAML, then can request a remote build, follow its status, decrypt the result and install it or download a ZIP. On-device, the component communicates with B2500 hardware over Bluetooth, decodes device messages into state, and exposes sensor entities and controls. The README documents legacy and native component configurations and MQTT topics; excerpts do not establish all build-service or component call wiring, so those links are limited.

Main entry points: [`components/b2500/b2500_base.cpp`](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_base.cpp) (Bluetooth component), [`src/App.tsx`](https://github.com/tomquist/esphome-b2500/blob/main/src/App.tsx) (App workflow), [`src/components/BuildModal.tsx`](https://github.com/tomquist/esphome-b2500/blob/main/src/components/BuildModal.tsx) (Build dialog), [`components/b2500/b2500_state.cpp`](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_state.cpp) (Device state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Configuration web app"]
  node_app["App workflow<br/>[App.tsx]"]
  node_forms["Config forms<br/>[ConfigForm.tsx]"]
  node_storage["Storage settings<br/>[StorageForm.tsx]"]
  node_configlogic["Config validation<br/>[index.ts]"]
  node_templates["YAML templates<br/>[templates.ts]"]
  node_yamlpreview["YAML preview"]
end

subgraph group_build["Firmware build and install"]
  node_buildmodal["Build dialog<br/>[BuildModal.tsx]"]
  node_crypto["Config encryption<br/>[crypto.ts]"]
  node_buildstatus["Build status polling<br/>[buildStatus.ts]"]
  node_bundle["Firmware archive<br/>[firmwareBundle.ts]"]
  node_archivecrypto["Archive decryption<br/>[archiveCrypto.ts]"]
  node_manifest["Firmware manifest<br/>[manifest.ts]"]
  node_installer["Web serial installer"]
end

subgraph group_device["ESPHome device runtime"]
  node_b2500config["Component configuration<br/>[__init__.py]"]
  node_base["Bluetooth component<br/>[b2500_base.cpp]"]
  node_protocol["Packet codec<br/>[b2500_codec.cpp]"]
  node_state["Device state<br/>[b2500_state.cpp]"]
  node_versions["Protocol generations<br/>[b2500_v1.cpp]"]
end

subgraph group_entities["Device entities and controls"]
  node_sensors["Power sensors<br/>[b2500_sensor.cpp]"]
  node_binary["Status sensors"]
  node_text["Device info sensors"]
  node_controls["Controls and automations<br/>[__init__.py]"]
end

node_user(("Browser user"))
node_buildservice["Build and artifact service"]
node_battery(("B2500 battery"))
node_mqtt["MQTT broker"]
node_esp(("ESP32 device"))

node_user -->|"edits config"| node_app
node_app -->|"renders"| node_forms
node_forms -->|"configures storage"| node_storage
node_app -->|"validates"| node_configlogic
node_app -->|"generates YAML"| node_templates
node_app -->|"shows YAML"| node_yamlpreview
node_app -->|"opens build"| node_buildmodal
node_buildmodal -->|"encrypts config"| node_crypto
node_buildmodal -->|"submits build"| node_buildservice
node_buildservice -.->|"publishes status"| node_buildstatus
node_buildmodal -->|"polls status"| node_buildstatus
node_buildmodal -->|"fetches archive"| node_bundle
node_bundle -->|"decrypts archive"| node_archivecrypto
node_bundle -->|"reads manifest"| node_manifest
node_buildmodal -->|"offers install"| node_installer
node_installer -->|"flashes firmware"| node_esp
node_esp -->|"loads component"| node_b2500config
node_b2500config -->|"configures runtime"| node_base
node_base -->|"selects protocol"| node_versions
node_base -->|"encodes packets"| node_protocol
node_base -->|"updates state"| node_state
node_battery -->|"Bluetooth messages"| node_base
node_sensors -->|"reads state"| node_state
node_binary -->|"reads state"| node_state
node_text -->|"reads state"| node_state
node_controls -->|"registers actions"| node_base
node_base -->|"sends commands"| node_battery
node_sensors -.->|"publishes readings"| node_mqtt
node_binary -.->|"publishes status"| node_mqtt
node_text -.->|"publishes info"| node_mqtt

click node_app "https://github.com/tomquist/esphome-b2500/blob/main/src/App.tsx"
click node_forms "https://github.com/tomquist/esphome-b2500/blob/main/src/components/ConfigForm.tsx"
click node_storage "https://github.com/tomquist/esphome-b2500/blob/main/src/components/StorageForm.tsx"
click node_configlogic "https://github.com/tomquist/esphome-b2500/blob/main/src/utils/index.ts"
click node_templates "https://github.com/tomquist/esphome-b2500/blob/main/src/templates.ts"
click node_yamlpreview "https://github.com/tomquist/esphome-b2500/blob/main/src/components/SyntaxHighlighterComponent.tsx"
click node_buildmodal "https://github.com/tomquist/esphome-b2500/blob/main/src/components/BuildModal.tsx"
click node_crypto "https://github.com/tomquist/esphome-b2500/blob/main/src/crypto.ts"
click node_buildstatus "https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/buildStatus.ts"
click node_bundle "https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/firmwareBundle.ts"
click node_archivecrypto "https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/archiveCrypto.ts"
click node_manifest "https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/manifest.ts"
click node_installer "https://github.com/tomquist/esphome-b2500/blob/main/src/components/EspWebInstallButton.tsx"
click node_b2500config "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/__init__.py"
click node_base "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_base.cpp"
click node_protocol "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_codec.cpp"
click node_state "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_state.cpp"
click node_versions "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_v1.cpp"
click node_sensors "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/sensor/b2500_sensor.cpp"
click node_binary "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/binary_sensor/b2500_binary_sensor_base.cpp"
click node_text "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/text_sensor/b2500_text_sensor.cpp"
click node_controls "https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/__init__.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_app,node_forms,node_storage,node_configlogic,node_templates,node_yamlpreview,node_user toneBlue
class node_buildmodal,node_crypto,node_buildstatus,node_bundle,node_archivecrypto,node_manifest,node_installer toneAmber
class node_b2500config,node_base,node_protocol,node_state,node_versions toneMint
class node_sensors,node_binary,node_text,node_controls toneRose
class node_buildservice,node_battery,node_mqtt,node_esp toneIndigo
```

## Components

### Configuration web app

- [App workflow](https://github.com/tomquist/esphome-b2500/blob/main/src/App.tsx): `src/App.tsx`
- [Config forms](https://github.com/tomquist/esphome-b2500/blob/main/src/components/ConfigForm.tsx): `src/components/ConfigForm.tsx`
- [Storage settings](https://github.com/tomquist/esphome-b2500/blob/main/src/components/StorageForm.tsx): `src/components/StorageForm.tsx`
- [Config validation](https://github.com/tomquist/esphome-b2500/blob/main/src/utils/index.ts): `src/utils/index.ts`
- [YAML templates](https://github.com/tomquist/esphome-b2500/blob/main/src/templates.ts): `src/templates.ts`
- [YAML preview](https://github.com/tomquist/esphome-b2500/blob/main/src/components/SyntaxHighlighterComponent.tsx): `src/components/SyntaxHighlighterComponent.tsx`

### Firmware build and install

- [Build dialog](https://github.com/tomquist/esphome-b2500/blob/main/src/components/BuildModal.tsx): `src/components/BuildModal.tsx`
- [Config encryption](https://github.com/tomquist/esphome-b2500/blob/main/src/crypto.ts): `src/crypto.ts`
- [Build status polling](https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/buildStatus.ts): `src/firmware/buildStatus.ts`
- [Firmware archive](https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/firmwareBundle.ts): `src/firmware/firmwareBundle.ts`
- [Archive decryption](https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/archiveCrypto.ts): `src/firmware/archiveCrypto.ts`
- [Firmware manifest](https://github.com/tomquist/esphome-b2500/blob/main/src/firmware/manifest.ts): `src/firmware/manifest.ts`
- [Web serial installer](https://github.com/tomquist/esphome-b2500/blob/main/src/components/EspWebInstallButton.tsx): `src/components/EspWebInstallButton.tsx`

### ESPHome device runtime

- [Component configuration](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/__init__.py): `components/b2500/__init__.py`
- [Bluetooth component](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_base.cpp): `components/b2500/b2500_base.cpp`
- [Packet codec](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_codec.cpp): `components/b2500/b2500_codec.cpp`
- [Device state](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_state.cpp): `components/b2500/b2500_state.cpp`
- [Protocol generations](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/b2500_v1.cpp): `components/b2500/b2500_v1.cpp`

### Device entities and controls

- [Power sensors](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/sensor/b2500_sensor.cpp): `components/b2500/sensor/b2500_sensor.cpp`
- [Status sensors](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/binary_sensor/b2500_binary_sensor_base.cpp): `components/b2500/binary_sensor/b2500_binary_sensor_base.cpp`
- [Device info sensors](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/text_sensor/b2500_text_sensor.cpp): `components/b2500/text_sensor/b2500_text_sensor.cpp`
- [Controls and automations](https://github.com/tomquist/esphome-b2500/blob/main/components/b2500/__init__.py): `components/b2500/__init__.py`

### Other components

- **Browser user**
- **Build and artifact service**
- **B2500 battery**
- **MQTT broker**
- **ESP32 device**

## Connections

- Browser user → App workflow: edits config
- App workflow → Config forms: renders
- Config forms → Storage settings: configures storage
- App workflow → Config validation: validates
- App workflow → YAML templates: generates YAML
- App workflow → YAML preview: shows YAML
- App workflow → Build dialog: opens build
- Build dialog → Config encryption: encrypts config
- Build dialog → Build and artifact service: submits build
- Build and artifact service → Build status polling: publishes status
- Build dialog → Build status polling: polls status
- Build dialog → Firmware archive: fetches archive
- Firmware archive → Archive decryption: decrypts archive
- Firmware archive → Firmware manifest: reads manifest
- Build dialog → Web serial installer: offers install
- Web serial installer → ESP32 device: flashes firmware
- ESP32 device → Component configuration: loads component
- Component configuration → Bluetooth component: configures runtime
- Bluetooth component → Protocol generations: selects protocol
- Bluetooth component → Packet codec: encodes packets
- Bluetooth component → Device state: updates state
- B2500 battery → Bluetooth component: Bluetooth messages
- Power sensors → Device state: reads state
- Status sensors → Device state: reads state
- Device info sensors → Device state: reads state
- Controls and automations → Bluetooth component: registers actions
- Bluetooth component → B2500 battery: sends commands
- Power sensors → MQTT broker: publishes readings
- Status sensors → MQTT broker: publishes status
- Device info sensors → MQTT broker: publishes info