# anesbenmerzoug/ball-and-beam architecture

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

- Interactive diagram: https://gitdiagram.com/anesbenmerzoug/ball-and-beam
- Repository: https://github.com/anesbenmerzoug/ball-and-beam

## Overview

This repository implements an embedded ball-and-beam controller with a browser dashboard, plus a separate simulation. The principal workflow is to measure ball position, apply filtering and a selected manual or PID controller, and actuate the beam; the dashboard configures the controller and requests telemetry through the device web API. The excerpts show the web handlers’ shared-state interactions and the frontend’s component wiring, but not the firmware control-loop calls or the HTTP client implementation, so those links are marked unverified.

Main entry points: [`ball-and-beam-main/src/bin/main.rs`](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/bin/main.rs) (Firmware runtime), [`ball-and-beam-main/src/web/app.rs`](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/web/app.rs) (Web API), [`frontend/src/main.js`](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/main.js) (Dashboard app), [`ball-and-beam-main/src/shared.rs`](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/shared.rs) (Shared signals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Embedded device"]
  node_runtime["Firmware runtime<br/>[main.rs]"]
  node_sensor["VL6180 sensor<br/>[vl6180.rs]"]
  node_sensorbase["Sensor interface<br/>[base.rs]"]
  node_servo["Servo actuation<br/>[servo.rs]"]
  node_shared[("Shared signals<br/>[shared.rs]")]
  node_web["Web API<br/>[app.rs]"]
  node_network["Network service<br/>[network.rs]"]
end

subgraph group_control["Control libraries"]
  node_filterbase["Filter interface<br/>[base.rs]"]
  node_filters["Position filters<br/>[median.rs]"]
  node_movingavg["Moving average<br/>[moving_average.rs]"]
  node_outlier["Outlier filter<br/>[outlier.rs]"]
  node_controllerbase["Controller interface<br/>[base.rs]"]
  node_manual["Manual controller<br/>[manual.rs]"]
  node_pid["PID controller<br/>[pid.rs]"]
  node_wrapper["Controller wrapper<br/>[wrapper.rs]"]
end

subgraph group_dashboard["Web dashboard"]
  node_frontend["Dashboard app<br/>[main.js]"]
  node_api["API client<br/>[api.js]"]
  node_config["Controller settings"]
  node_pidui["PID controls<br/>[pid.js]"]
  node_slider["Slider parameter<br/>[sliderParameter.js]"]
  node_chart["Telemetry chart<br/>[dataChart.js]"]
end

subgraph group_simulation["Simulation"]
  node_simulation["System simulation<br/>[simulation.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_frontend
node_frontend -->|"uses"| node_api
node_frontend -->|"renders"| node_config
node_frontend -->|"renders"| node_chart
node_config -->|"renders"| node_pidui
node_pidui -->|"renders"| node_slider
node_api -.->|"sends API requests"| node_web
node_web -->|"reads telemetry"| node_shared
node_web -->|"signals parameter updates"| node_shared
node_web -->|"sets run flag"| node_shared
node_runtime -.->|"samples position"| node_sensor
node_runtime -.->|"filters measurements"| node_filters
node_runtime -.->|"dispatches control"| node_wrapper
node_runtime -.->|"commands angle"| node_servo
node_runtime -.->|"publishes state"| node_shared
node_network -.->|"serves app"| node_web
node_filters -->|"implements"| node_filterbase
node_movingavg -->|"implements"| node_filterbase
node_outlier -->|"implements"| node_filterbase
node_manual -->|"implements"| node_controllerbase
node_pid -->|"implements"| node_controllerbase
node_wrapper -->|"wraps"| node_manual
node_wrapper -->|"wraps"| node_pid
node_simulation -.->|"models system"| node_operator

click node_runtime "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/bin/main.rs"
click node_sensor "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/distance_sensor/vl6180.rs"
click node_sensorbase "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/distance_sensor/base.rs"
click node_servo "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/servo.rs"
click node_shared "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/shared.rs"
click node_web "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/web/app.rs"
click node_network "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/web/network.rs"
click node_filterbase "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/base.rs"
click node_filters "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/median.rs"
click node_movingavg "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/moving_average.rs"
click node_outlier "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/outlier.rs"
click node_controllerbase "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/base.rs"
click node_manual "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/manual.rs"
click node_pid "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/pid.rs"
click node_wrapper "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/wrapper.rs"
click node_frontend "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/main.js"
click node_api "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/api.js"
click node_config "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/controllerConfig.js"
click node_pidui "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/controllers/pid.js"
click node_slider "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/controllers/parameters/sliderParameter.js"
click node_chart "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/dataChart.js"
click node_simulation "https://github.com/anesbenmerzoug/ball-and-beam/blob/main/simulation/simulation.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_runtime,node_sensor,node_sensorbase,node_servo,node_shared,node_web,node_network toneBlue
class node_filterbase,node_filters,node_movingavg,node_outlier,node_controllerbase,node_manual,node_pid,node_wrapper toneAmber
class node_frontend,node_api,node_config,node_pidui,node_slider,node_chart toneMint
class node_simulation toneRose
class node_operator toneIndigo
```

## Components

### Embedded device

- [Firmware runtime](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/bin/main.rs): `ball-and-beam-main/src/bin/main.rs`
- [VL6180 sensor](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/distance_sensor/vl6180.rs): `ball-and-beam-main/src/distance_sensor/vl6180.rs`
- [Sensor interface](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/distance_sensor/base.rs): `ball-and-beam-main/src/distance_sensor/base.rs`
- [Servo actuation](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/servo.rs): `ball-and-beam-main/src/servo.rs`
- [Shared signals](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/shared.rs): `ball-and-beam-main/src/shared.rs`
- [Web API](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/web/app.rs): `ball-and-beam-main/src/web/app.rs`
- [Network service](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-main/src/web/network.rs): `ball-and-beam-main/src/web/network.rs`

### Control libraries

- [Filter interface](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/base.rs): `ball-and-beam-filters/src/base.rs`
- [Position filters](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/median.rs): `ball-and-beam-filters/src/median.rs`
- [Moving average](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/moving_average.rs): `ball-and-beam-filters/src/moving_average.rs`
- [Outlier filter](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-filters/src/outlier.rs): `ball-and-beam-filters/src/outlier.rs`
- [Controller interface](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/base.rs): `ball-and-beam-controllers/src/base.rs`
- [Manual controller](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/manual.rs): `ball-and-beam-controllers/src/manual.rs`
- [PID controller](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/pid.rs): `ball-and-beam-controllers/src/pid.rs`
- [Controller wrapper](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/ball-and-beam-controllers/src/wrapper.rs): `ball-and-beam-controllers/src/wrapper.rs`

### Web dashboard

- [Dashboard app](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/main.js): `frontend/src/main.js`
- [API client](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Controller settings](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/controllerConfig.js): `frontend/src/components/controllerConfig.js`
- [PID controls](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/controllers/pid.js): `frontend/src/components/controllers/pid.js`
- [Slider parameter](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/controllers/parameters/sliderParameter.js): `frontend/src/components/controllers/parameters/sliderParameter.js`
- [Telemetry chart](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/frontend/src/components/dataChart.js): `frontend/src/components/dataChart.js`

### Simulation

- [System simulation](https://github.com/anesbenmerzoug/ball-and-beam/blob/main/simulation/simulation.py): `simulation/simulation.py`

### Other components

- **Operator**

## Connections

- Operator → Dashboard app: uses
- Dashboard app → API client: uses (evidence: `frontend/src/main.js`)
- Dashboard app → Controller settings: renders (evidence: `frontend/src/main.js`)
- Dashboard app → Telemetry chart: renders (evidence: `frontend/src/main.js`)
- Controller settings → PID controls: renders (evidence: `frontend/src/components/controllerConfig.js`)
- PID controls → Slider parameter: renders (evidence: `frontend/src/components/controllers/pid.js`)
- API client → Web API: sends API requests
- Web API → Shared signals: reads telemetry (evidence: `ball-and-beam-main/src/web/app.rs`)
- Web API → Shared signals: signals parameter updates (evidence: `ball-and-beam-main/src/web/app.rs`)
- Web API → Shared signals: sets run flag (evidence: `ball-and-beam-main/src/web/app.rs`)
- Firmware runtime → VL6180 sensor: samples position
- Firmware runtime → Position filters: filters measurements
- Firmware runtime → Controller wrapper: dispatches control
- Firmware runtime → Servo actuation: commands angle
- Firmware runtime → Shared signals: publishes state
- Network service → Web API: serves app
- Position filters → Filter interface: implements (evidence: `ball-and-beam-filters/src/median.rs`)
- Moving average → Filter interface: implements (evidence: `ball-and-beam-filters/src/moving_average.rs`)
- Outlier filter → Filter interface: implements (evidence: `ball-and-beam-filters/src/outlier.rs`)
- Manual controller → Controller interface: implements (evidence: `ball-and-beam-controllers/src/manual.rs`)
- PID controller → Controller interface: implements (evidence: `ball-and-beam-controllers/src/pid.rs`)
- Controller wrapper → Manual controller: wraps (evidence: `ball-and-beam-controllers/src/wrapper.rs`)
- Controller wrapper → PID controller: wraps (evidence: `ball-and-beam-controllers/src/wrapper.rs`)
- System simulation → Operator: models system
