# michael-graves/ball-and-plate architecture

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

- Interactive diagram: https://gitdiagram.com/michael-graves/ball-and-plate
- Repository: https://github.com/michael-graves/ball-and-plate

## Overview

Ball-and-Plate is embedded firmware for balancing a ball on a two-axis plate. The main loop schedules touch sampling, PID updates and motor commands; button input selects operating modes, including circular setpoint motion, while UART provides serial output. The documented sensing, feedback-control and servo-actuation stages are represented alongside button and communication capabilities. Source excerpts show the main controller calling peripheral modules; calibration is present but explicitly marked unused. Edges are limited to relationships shown by excerpts or README; unsampled main-loop details are not inferred.

Main entry points: [`main.c`](https://github.com/michael-graves/ball-and-plate/blob/master/main.c) (Runtime Controller), [`button.c`](https://github.com/michael-graves/ball-and-plate/blob/master/button.c) (Button Debounce), [`touch.c`](https://github.com/michael-graves/ball-and-plate/blob/master/touch.c) (Touchscreen ADC), [`servo.c`](https://github.com/michael-graves/ball-and-plate/blob/master/servo.c) (Servo PWM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Loop"]
  node_main["Runtime Controller<br/>[main.c]"]
  node_pid["PID Feedback<br/>[main.c]"]
  node_setpoint["Mode Setpoints<br/>[main.c]"]
  node_systick["SysTick Scheduler<br/>[main.c]"]
end

subgraph group_io["Board I/O"]
  node_touch["Touchscreen ADC<br/>[touch.c]"]
  node_buttons["Button Debounce<br/>[button.c]"]
  node_servos["Servo PWM<br/>[servo.c]"]
  node_uart["Serial Communication<br/>[com.c]"]
end

subgraph group_support["Position Support"]
  node_calibration["Touch Calibration<br/>[touchCalibration.c]"]
end

node_operator(("Operator"))
node_ball(("Ball Position"))

node_main -->|"samples position"| node_touch
node_main -->|"updates control"| node_pid
node_main -->|"sets angles"| node_servos
node_main -->|"initializes callback"| node_buttons
node_main -->|"initializes and sends"| node_uart
node_main -->|"initializes timer"| node_systick
node_buttons -->|"calls mode callback"| node_main
node_systick -->|"sets update flags"| node_main
node_operator -.->|"presses controls"| node_buttons
node_ball -->|"provides position input"| node_touch
node_calibration -.->|"could calibrate"| node_touch
node_servos -->|"tilts platform"| node_ball
node_uart -.->|"serial output"| node_operator

click node_main "https://github.com/michael-graves/ball-and-plate/blob/master/main.c"
click node_pid "https://github.com/michael-graves/ball-and-plate/blob/master/main.c"
click node_setpoint "https://github.com/michael-graves/ball-and-plate/blob/master/main.c"
click node_systick "https://github.com/michael-graves/ball-and-plate/blob/master/main.c"
click node_touch "https://github.com/michael-graves/ball-and-plate/blob/master/touch.c"
click node_buttons "https://github.com/michael-graves/ball-and-plate/blob/master/button.c"
click node_servos "https://github.com/michael-graves/ball-and-plate/blob/master/servo.c"
click node_uart "https://github.com/michael-graves/ball-and-plate/blob/master/com.c"
click node_calibration "https://github.com/michael-graves/ball-and-plate/blob/master/touchCalibration.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_main,node_pid,node_setpoint,node_systick toneBlue
class node_touch,node_buttons,node_servos,node_uart toneAmber
class node_calibration toneMint
class node_operator,node_ball toneIndigo
```

## Components

### Control Loop

- [Runtime Controller](https://github.com/michael-graves/ball-and-plate/blob/master/main.c): `main.c`
- [PID Feedback](https://github.com/michael-graves/ball-and-plate/blob/master/main.c): `main.c`
- [Mode Setpoints](https://github.com/michael-graves/ball-and-plate/blob/master/main.c): `main.c`
- [SysTick Scheduler](https://github.com/michael-graves/ball-and-plate/blob/master/main.c): `main.c`

### Board I/O

- [Touchscreen ADC](https://github.com/michael-graves/ball-and-plate/blob/master/touch.c): `touch.c`
- [Button Debounce](https://github.com/michael-graves/ball-and-plate/blob/master/button.c): `button.c`
- [Servo PWM](https://github.com/michael-graves/ball-and-plate/blob/master/servo.c): `servo.c`
- [Serial Communication](https://github.com/michael-graves/ball-and-plate/blob/master/com.c): `com.c`

### Position Support

- [Touch Calibration](https://github.com/michael-graves/ball-and-plate/blob/master/touchCalibration.c): `touchCalibration.c`

### Other components

- **Operator**
- **Ball Position**

## Connections

- Runtime Controller → Touchscreen ADC: samples position (evidence: `main.c`)
- Runtime Controller → PID Feedback: updates control (evidence: `main.c`)
- Runtime Controller → Servo PWM: sets angles (evidence: `main.c`)
- Runtime Controller → Button Debounce: initializes callback (evidence: `main.c`)
- Runtime Controller → Serial Communication: initializes and sends (evidence: `main.c`)
- Runtime Controller → SysTick Scheduler: initializes timer (evidence: `main.c`)
- Button Debounce → Runtime Controller: calls mode callback (evidence: `button.c`)
- SysTick Scheduler → Runtime Controller: sets update flags (evidence: `main.c`)
- Operator → Button Debounce: presses controls (evidence: `README.md`)
- Ball Position → Touchscreen ADC: provides position input (evidence: `README.md`)
- Touch Calibration → Touchscreen ADC: could calibrate
- Servo PWM → Ball Position: tilts platform (evidence: `README.md`)
- Serial Communication → Operator: serial output