# scottbez1/faderbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/scottbez1/faderbuddy
- Repository: https://github.com/scottbez1/faderbuddy

## Overview

FaderBuddy is a motorized-fader control board whose ATtiny firmware handles real-time movement and exposes control over I²C. Hosts can read position, command movement, and configure layered haptics; the documented ESPHome integration synchronizes positions with Home Assistant and exposes automation triggers. The repository also includes a browser-based MCP2221 interface and production programming/testing tools. Firmware excerpts confirm calibration storage and initialization; unsampled source limits detail on some host and manufacturing interactions.

Main entry points: [`firmware/src/main.cpp`](https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/main.cpp) (Control firmware), [`esphome/components/fader_buddy/fader_buddy.cpp`](https://github.com/scottbez1/faderbuddy/blob/master/esphome/components/fader_buddy/fader_buddy.cpp) (ESPHome component), [`production_tools/programAndTest/src/main.cpp`](https://github.com/scottbez1/faderbuddy/blob/master/production_tools/programAndTest/src/main.cpp) (Program and test station), [`software/mcp2221-webhid/src/main.js`](https://github.com/scottbez1/faderbuddy/blob/master/software/mcp2221-webhid/src/main.js) (Browser interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Board firmware"]
  node_main_fw["Control firmware<br/>[main.cpp]"]
  node_motor_cal["Motor calibration<br/>[motor_cal.cpp]"]
  node_motor_control["Motor control<br/>[motor_control.h]"]
  node_i2c_contract["I²C register map<br/>[i2c_data.h]"]
end

subgraph group_hosts["Host interfaces"]
  node_esphome["ESPHome component<br/>[fader_buddy.cpp]"]
  node_esphome_config["ESPHome configuration<br/>[__init__.py]"]
  node_web_ui["Browser interface<br/>[main.js]"]
  node_web_client["FaderBuddy client<br/>[faderBuddy.js]"]
end

subgraph group_service["Firmware service"]
  node_bootloader["I²C bootloader<br/>[bootloader.c]"]
  node_boot_protocol["Boot protocol"]
  node_fw_tools["Firmware tools"]
end

subgraph group_manufacturing["Production testing"]
  node_production["Program and test station<br/>[main.cpp]"]
  node_station_i2c["Station I²C interface"]
  node_station_bl["Station bootloader interface"]
end

node_host(("Host controller"))
node_fader(("Motor fader board"))
node_ha(("Home Assistant"))
node_mcp["MCP2221 adapter"]
node_operator(("Production operator"))

node_host -->|"commands over I²C"| node_main_fw
node_main_fw -->|"drives and reads"| node_fader
node_main_fw -->|"applies calibration"| node_motor_cal
node_main_fw -->|"controls motion"| node_motor_control
node_main_fw -->|"implements registers"| node_i2c_contract
node_esphome_config -->|"configures"| node_esphome
node_esphome -->|"reads and commands"| node_fader
node_esphome -->|"syncs entities"| node_ha
node_web_ui -->|"calls"| node_web_client
node_web_ui -->|"connects through"| node_mcp
node_web_client -->|"reads and commands"| node_fader
node_fw_tools -.->|"programs firmware"| node_bootloader
node_bootloader -->|"uses commands"| node_boot_protocol
node_operator -->|"operates"| node_production
node_production -->|"uses"| node_station_i2c
node_production -->|"uses"| node_station_bl
node_station_i2c -->|"communicates over I²C"| node_fader
node_station_bl -->|"communicates with bootloader"| node_fader

click node_main_fw "https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/main.cpp"
click node_motor_cal "https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/motor_cal.cpp"
click node_motor_control "https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/motor_control.h"
click node_i2c_contract "https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/shared/i2c_data.h"
click node_bootloader "https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/bootloader/bootloader.c"
click node_boot_protocol "https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/shared/bootloader_protocol.h"
click node_fw_tools "https://github.com/scottbez1/faderbuddy/tree/master/firmware/tools"
click node_esphome "https://github.com/scottbez1/faderbuddy/blob/master/esphome/components/fader_buddy/fader_buddy.cpp"
click node_esphome_config "https://github.com/scottbez1/faderbuddy/blob/master/esphome/components/fader_buddy/__init__.py"
click node_web_ui "https://github.com/scottbez1/faderbuddy/blob/master/software/mcp2221-webhid/src/main.js"
click node_web_client "https://github.com/scottbez1/faderbuddy/blob/master/software/mcp2221-webhid/src/faderBuddy.js"
click node_production "https://github.com/scottbez1/faderbuddy/blob/master/production_tools/programAndTest/src/main.cpp"
click node_station_i2c "https://github.com/scottbez1/faderbuddy/blob/master/production_tools/programAndTest/src/fader_buddy_i2c.cpp"
click node_station_bl "https://github.com/scottbez1/faderbuddy/blob/master/production_tools/programAndTest/src/fader_buddy_bootloader.cpp"

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_main_fw,node_motor_cal,node_motor_control,node_i2c_contract toneBlue
class node_esphome,node_esphome_config,node_web_ui,node_web_client toneAmber
class node_bootloader,node_boot_protocol,node_fw_tools toneMint
class node_production,node_station_i2c,node_station_bl toneRose
class node_host,node_fader,node_ha,node_mcp,node_operator toneIndigo
```

## Components

### Board firmware

- [Control firmware](https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Motor calibration](https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/motor_cal.cpp): `firmware/src/motor_cal.cpp`
- [Motor control](https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/motor_control.h): `firmware/src/motor_control.h`
- [I²C register map](https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/shared/i2c_data.h): `firmware/src/shared/i2c_data.h`

### Host interfaces

- [ESPHome component](https://github.com/scottbez1/faderbuddy/blob/master/esphome/components/fader_buddy/fader_buddy.cpp): `esphome/components/fader_buddy/fader_buddy.cpp`
- [ESPHome configuration](https://github.com/scottbez1/faderbuddy/blob/master/esphome/components/fader_buddy/__init__.py): `esphome/components/fader_buddy/__init__.py`
- [Browser interface](https://github.com/scottbez1/faderbuddy/blob/master/software/mcp2221-webhid/src/main.js): `software/mcp2221-webhid/src/main.js`
- [FaderBuddy client](https://github.com/scottbez1/faderbuddy/blob/master/software/mcp2221-webhid/src/faderBuddy.js): `software/mcp2221-webhid/src/faderBuddy.js`

### Firmware service

- [I²C bootloader](https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/bootloader/bootloader.c): `firmware/src/bootloader/bootloader.c`
- [Boot protocol](https://github.com/scottbez1/faderbuddy/blob/master/firmware/src/shared/bootloader_protocol.h): `firmware/src/shared/bootloader_protocol.h`
- [Firmware tools](https://github.com/scottbez1/faderbuddy/tree/master/firmware/tools): `firmware/tools`

### Production testing

- [Program and test station](https://github.com/scottbez1/faderbuddy/blob/master/production_tools/programAndTest/src/main.cpp): `production_tools/programAndTest/src/main.cpp`
- [Station I²C interface](https://github.com/scottbez1/faderbuddy/blob/master/production_tools/programAndTest/src/fader_buddy_i2c.cpp): `production_tools/programAndTest/src/fader_buddy_i2c.cpp`
- [Station bootloader interface](https://github.com/scottbez1/faderbuddy/blob/master/production_tools/programAndTest/src/fader_buddy_bootloader.cpp): `production_tools/programAndTest/src/fader_buddy_bootloader.cpp`

### Other components

- **Host controller**
- **Motor fader board**
- **Home Assistant**
- **MCP2221 adapter**
- **Production operator**

## Connections

- Host controller → Control firmware: commands over I²C
- Control firmware → Motor fader board: drives and reads
- Control firmware → Motor calibration: applies calibration
- Control firmware → Motor control: controls motion
- Control firmware → I²C register map: implements registers
- ESPHome configuration → ESPHome component: configures
- ESPHome component → Motor fader board: reads and commands
- ESPHome component → Home Assistant: syncs entities
- Browser interface → FaderBuddy client: calls
- Browser interface → MCP2221 adapter: connects through
- FaderBuddy client → Motor fader board: reads and commands
- Firmware tools → I²C bootloader: programs firmware
- I²C bootloader → Boot protocol: uses commands
- Production operator → Program and test station: operates
- Program and test station → Station I²C interface: uses
- Program and test station → Station bootloader interface: uses
- Station I²C interface → Motor fader board: communicates over I²C
- Station bootloader interface → Motor fader board: communicates with bootloader