# remrc/self-balancing-cube architecture

> Architecture diagram of the GitHub repository remrc/self-balancing-cube, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/remrc/self-balancing-cube
- Repository: https://github.com/remrc/self-balancing-cube

## Overview

##### Project type and purpose
- This is an embedded real-time control system (“Self-Balancing Cube”) that uses an ESP32 (or optionally an Arduino Nano) to read an IMU (MPU6050), run a balancing algorithm, drive three brushless motors (and encoders in the “esp32_cube_enc” variant), and provide a Bluetooth/serial interface for tuning control parameters and calibration.

##### File structure
- Top-level firmware variants:
- ESP32_cube/ (original ESP32 code)
- esp32_cube_enc/ (new ESP32 code with encoder support)
- arduino_cube/ (Arduino Nano version)
- Shared functional modules in each variant:
– ESP32.h or arduino_cube.h: low-level pin and peripheral definitions
– functions.ino: hardware‐abstraction functions (IMU read, motor drive, Bluetooth comms)
– main .ino file: setup(), loop(), balancing algorithm and serial/Bluetooth interface
- motors_test/: standalone sketch to verify motor wiring, rotation direction, encoders

##### README for additional insights
- Hardware: 3S LiPo battery → 5 V regulator → ESP32/Nano + MPU6050 + buzzer + six MOSFET motor drivers → Nidec 24H brushless motors (+ optional encoders)
- Bluetooth interface for live PID tuning (K1/K2/K3) and calibration (c+ / c– commands)
- Two balancing-point setting procedures (edges and vertex) stored in EEPROM

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Power Subsystem
    subgraph "Power Subsystem"
        Battery["LiPo Battery"]:::hardware
        Regulator["5 V Regulator"]:::hardware
        Buzzer["Buzzer"]:::hardware
    end
    Battery --> Regulator
    Regulator --> Buzzer

    %% Controllers
    Regulator --> Controllers

    subgraph "Controllers"
        direction TB
        subgraph "ESP32 (Original)" 
            direction TB
            ESP32_Main["ESP32_cube.ino"]:::firmware
            ESP32_HAL["ESP32.h"]:::firmware
            ESP32_Func["functions.ino"]:::firmware
        end
        subgraph "ESP32 w/ Encoders"
            direction TB
            ESP32E_Main["esp32_cube_enc.ino"]:::firmware
            ESP32E_HAL["ESP32.h"]:::firmware
            ESP32E_Func["functions.ino"]:::firmware
        end
        subgraph "Arduino Nano"
            direction TB
            Nano_Main["arduino_cube.ino"]:::firmware
            Nano_HAL["arduino_cube.h"]:::firmware
            Nano_Func["functions.ino"]:::firmware
        end
    end

    %% Sensors & Actuators
    IMU["MPU6050 IMU"]:::hardware
    Encoders["Motor Encoders (optional)"]:::hardware
    MOSFET["MOSFET Driver Boards"]:::hardware
    Motors["Brushless Motors"]:::hardware

    %% Communication & Storage
    Bluetooth["Bluetooth Module (UART)"]:::external
    PC["PC/Phone Terminal"]:::external
    EEPROM["EEPROM"]:::hardware

    %% Data & Control Flows (Original ESP32)
    ESP32_Func -->|I²C read/write| IMU
    ESP32_Func -->|"drive PWM"| MOSFET
    MOSFET --> Motors
    ESP32_Func -->|"UART"| Bluetooth
    Bluetooth --> PC
    ESP32_Main --> EEPROM
    EEPROM --> ESP32_Main

    %% Encoder variant loops
    ESP32E_Func -->|I²C read/write| IMU
    ESP32E_Func -->|"drive PWM"| MOSFET
    MOSFET --> Motors
    Motors -->|encoder feedback| ESP32E_Func
    ESP32E_Func -->|"UART"| Bluetooth
    ESP32E_Main --> EEPROM
    EEPROM --> ESP32E_Main

    %% Arduino variant flows
    Nano_Func -->|I²C read/write| IMU
    Nano_Func -->|"drive PWM"| MOSFET
    MOSFET --> Motors
    Nano_Func -->|"UART"| Bluetooth
    Nano_Main --> EEPROM
    EEPROM --> Nano_Main

    %% Offline Motor Test
    MotorsTest["motors_test.ino"]:::note
    MotorsTest --> MOSFET
    MotorsTest --> Motors

    %% Click Events
    click ESP32_Main "https://github.com/remrc/self-balancing-cube/blob/main/ESP32_cube/ESP32_cube.ino"
    click ESP32_HAL "https://github.com/remrc/self-balancing-cube/blob/main/ESP32_cube/ESP32.h"
    click ESP32_Func "https://github.com/remrc/self-balancing-cube/blob/main/ESP32_cube/functions.ino"
    click ESP32E_Main "https://github.com/remrc/self-balancing-cube/blob/main/esp32_cube_enc/esp32_cube_enc.ino"
    click ESP32E_HAL "https://github.com/remrc/self-balancing-cube/blob/main/esp32_cube_enc/ESP32.h"
    click ESP32E_Func "https://github.com/remrc/self-balancing-cube/blob/main/esp32_cube_enc/functions.ino"
    click Nano_Main "https://github.com/remrc/self-balancing-cube/blob/main/arduino_cube/arduino_cube.ino"
    click Nano_HAL "https://github.com/remrc/self-balancing-cube/blob/main/arduino_cube/arduino_cube.h"
    click Nano_Func "https://github.com/remrc/self-balancing-cube/blob/main/arduino_cube/functions.ino"
    click MotorsTest "https://github.com/remrc/self-balancing-cube/blob/main/motors_test/motors_test.ino"
    click Regulator "https://github.com/remrc/self-balancing-cube/blob/main/schematic.pdf"
    click Battery "https://github.com/remrc/self-balancing-cube/blob/main/README.md"
    click Buzzer "https://github.com/remrc/self-balancing-cube/blob/main/schematic.pdf"

    %% Styles
    classDef hardware fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef firmware fill:#aaddff,stroke:#036,stroke-width:1px;
    classDef external fill:#ccffcc,stroke:#070,stroke-width:1px;
    classDef note fill:#ffeeaa,stroke:#aa7700,stroke-width:1px,stroke-dasharray: 5 5;
    class Controllers hardware
```
