# rokasbarasa1/esp32-self-balancing-robot architecture

> Architecture diagram of the GitHub repository rokasbarasa1/esp32-self-balancing-robot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rokasbarasa1/esp32-self-balancing-robot
- Repository: https://github.com/rokasbarasa1/esp32-self-balancing-robot

## Overview

This repository implements firmware for an ESP32 self-balancing robot. The main loop reads inertial and magnetic sensors, estimates orientation, applies pitch/yaw and wheel-speed PID control, and drives the motors; a compatible remote can provide movement and yaw commands over nRF24L01. The graph also preserves encoder, SPI, and calibration capabilities. Edges follow the main-loop excerpt, SOURCE INDEX references, or README; unsampled modules are not assumed to participate in the loop.

Main entry points: [`src/main.c`](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/src/main.c) (Control loop), [`lib/nrf24l01/nrf24l01.c`](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/nrf24l01/nrf24l01.c) (nRF24 radio), [`lib/pid/pid.c`](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/pid/pid.c) (PID control), [`lib/mpu6050/mpu6050.c`](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/mpu6050/mpu6050.c) (IMU and fusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Balance control"]
  node_main["Control loop<br/>[main.c]"]
  node_pid["PID control<br/>[pid.c]"]
end

subgraph group_sensing["Sensors and motion"]
  node_mpu["IMU and fusion<br/>[mpu6050.c]"]
  node_mag["Magnetometer<br/>[qmc5883l.c]"]
  node_encoder["Optical encoders<br/>[optical_encoder.c]"]
  node_adxl["ADXL345 driver<br/>[adxl345.c]"]
end

subgraph group_hardware["Hardware interfaces"]
  node_motors["Motor driver<br/>[TB6612.c]"]
  node_radio["nRF24 radio<br/>[nrf24l01.c]"]
  node_spi["SPI interface<br/>[spi.c]"]
  node_esp01["ESP-01 interface<br/>[esp_01.c]"]
end

subgraph group_support["Utilities and calibration"]
  node_coordinates["NED coordinates<br/>[ned_coordinates.c]"]
  node_calibration["Magnetometer calibration<br/>[calibration.md]"]
end

node_operator(("Robot operator"))
node_remote(("Remote controller"))

node_operator -.->|"starts robot"| node_main
node_main -->|"reads IMU"| node_mpu
node_main -->|"reads heading"| node_mag
node_main -->|"samples encoders"| node_encoder
node_main -->|"computes control"| node_pid
node_main -->|"sets motor power"| node_motors
node_main -->|"receives commands"| node_radio
node_remote -.->|"sends commands"| node_radio
node_radio -->|"uses SPI"| node_spi
node_main -->|"uses coordinates"| node_coordinates
node_operator -->|"follows procedure"| node_calibration

click node_main "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/src/main.c"
click node_pid "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/pid/pid.c"
click node_motors "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/TB6612/TB6612.c"
click node_mpu "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/mpu6050/mpu6050.c"
click node_mag "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/qmc5883l/qmc5883l.c"
click node_encoder "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/optical_encoder/optical_encoder.c"
click node_adxl "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/adxl345/adxl345.c"
click node_radio "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/nrf24l01/nrf24l01.c"
click node_spi "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/util/spi/spi.c"
click node_esp01 "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/esp_01/esp_01.c"
click node_coordinates "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/util/ned_coordinates/ned_coordinates.c"
click node_calibration "https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/qmc5883l/calibration/calibration.md"

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 toneBlue
class node_mpu,node_mag,node_encoder,node_adxl toneAmber
class node_motors,node_radio,node_spi,node_esp01 toneMint
class node_coordinates,node_calibration toneRose
class node_operator,node_remote toneIndigo
```

## Components

### Balance control

- [Control loop](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/src/main.c): `src/main.c`
- [PID control](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/pid/pid.c): `lib/pid/pid.c`

### Sensors and motion

- [IMU and fusion](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/mpu6050/mpu6050.c): `lib/mpu6050/mpu6050.c`
- [Magnetometer](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/qmc5883l/qmc5883l.c): `lib/qmc5883l/qmc5883l.c`
- [Optical encoders](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/optical_encoder/optical_encoder.c): `lib/optical_encoder/optical_encoder.c`
- [ADXL345 driver](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/adxl345/adxl345.c): `lib/adxl345/adxl345.c`

### Hardware interfaces

- [Motor driver](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/TB6612/TB6612.c): `lib/TB6612/TB6612.c`
- [nRF24 radio](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/nrf24l01/nrf24l01.c): `lib/nrf24l01/nrf24l01.c`
- [SPI interface](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/util/spi/spi.c): `lib/util/spi/spi.c`
- [ESP-01 interface](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/esp_01/esp_01.c): `lib/esp_01/esp_01.c`

### Utilities and calibration

- [NED coordinates](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/util/ned_coordinates/ned_coordinates.c): `lib/util/ned_coordinates/ned_coordinates.c`
- [Magnetometer calibration](https://github.com/rokasbarasa1/esp32-self-balancing-robot/blob/master/lib/qmc5883l/calibration/calibration.md): `lib/qmc5883l/calibration/calibration.md`

### Other components

- **Robot operator**
- **Remote controller**

## Connections

- Robot operator → Control loop: starts robot (evidence: `README.md`)
- Control loop → IMU and fusion: reads IMU (evidence: `src/main.c`)
- Control loop → Magnetometer: reads heading (evidence: `src/main.c`)
- Control loop → Optical encoders: samples encoders (evidence: `src/main.c`)
- Control loop → PID control: computes control (evidence: `src/main.c`)
- Control loop → Motor driver: sets motor power (evidence: `src/main.c`)
- Control loop → nRF24 radio: receives commands (evidence: `src/main.c`)
- Remote controller → nRF24 radio: sends commands (evidence: `README.md`)
- nRF24 radio → SPI interface: uses SPI
- Control loop → NED coordinates: uses coordinates (evidence: `src/main.c`)
- Robot operator → Magnetometer calibration: follows procedure (evidence: `README.md`)
