# rodrigoacc10/ultrasonic_radar architecture

> Architecture diagram of the GitHub repository rodrigoacc10/ultrasonic_radar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rodrigoacc10/ultrasonic_radar
- Repository: https://github.com/rodrigoacc10/ultrasonic_radar

## Overview

##### Project Type and Purpose
- This is a combined embedded‐firmware + PC tool project (“Arduino Radar”).
- The embedded side runs on an Arduino (PlatformIO/C++), controls a servo and LCD, reads ultrasonic sensor data, and streams measurements over serial.
- The PC side is a set of Python scripts that open a serial port, parse distance vs. angle data, and render a live radar‐style plot.

##### File Structure Analysis
Top‐level directories and files:
- platformio.ini – PlatformIO board/build config
- src/
– main.cpp (application entry: loop reading sensor, rotating servo, drawing on LCD, writing serial)
– lcd.cpp (LCD driver glue code)
- / – C++ headers for your application modules (lcd.h, etc.)
- lib/ – Third-party libraries:
– Servo (servo driver abstractions for AVR/megaAVR)
– SPI (low-level SPI master)
– Ucglib (graphics library + device drivers)
- script/ – PC‐side Python scripts (radar_serial_plot*.py) for serial plotting
- test/ – Unit tests for lcd, servo, main logic
- doc/ – Requirements, SDDs, test docs, Python script design

##### Key Architectural Insights from README
- Firmware is built and uploaded via PlatformIO in VS Code.
- Firmware controls hardware (servo, ultrasonic sensor, LCD) and emits data to USB‐serial (CH340).
- Python scripts use pySerial and matplotlib (or similar) to render live plots.

a. Main Components
- Hardware Layer
– Ultrasonic range sensor
– DC Servo motor
– SPI‐driven LCD display
– CH340 USB‐serial interface
- Firmware Layer (Embedded MCU)
– Hardware Abstraction & Drivers: Servo, SPI, Ucglib
– Application Logic: Sweep control, distance acquisition, display update, serial output
- PC Side
– Serial Acquisition Module (Python + pySerial)
– Plotting Module (matplotlib or similar)
- Development Toolchain
– PlatformIO/VS Code
– Arduino Core libraries
b. Component Interactions
– MCU ↔ Sensor (digital trigger/echo)
– MCU ↔ Servo via Servo library (PWM timers)
– MCU ↔ LCD via SPI & Ucglib
– MCU → PC via USB-serial (streaming angle + distance)
– PC Scripts → Plotter GUI
c. Architectural Patterns & Principles
– Layering:
- HAL (SPI, Servo)
- Graphics library (Ucglib)
- Application logic
– Separation of concerns: firmware vs. PC tools vs. tests
– Modularization: each library in lib/, each feature in its own source file
d. Key Technologies/Frameworks
– PlatformIO build system
– C++17 (Arduino style)
– Ucglib for graphics
– Servo library for motor control
– pySerial + matplotlib (or PyQtGraph)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Toolchain
    Toolchain["PlatformIO & VS Code"]:::toolchain
    Config["platformio.ini"]:::config
    Toolchain -->|uses| Config
    click Config "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/platformio.ini"

    %% Main Diagram
    subgraph "Embedded Side" 
        direction TB
        subgraph "Hardware Layer"
            direction TB
            Sensor["Ultrasonic Sensor"]:::hardware
            ServoMotor["DC Servo Motor"]:::hardware
            LCDDisplay["SPI-Driven LCD Display"]:::hardware
            USBSerial["CH340 USB-Serial"]:::hardware
        end

        subgraph "MCU (Arduino)" 
            direction TB

            subgraph "HAL & Drivers"
                direction TB
                ServoLib["Servo Library (C/C++)"]:::firmware
                SPILib["SPI Library (C/C++)"]:::firmware
                UcglibLib["Ucglib Graphics (C/C++)"]:::firmware
            end

            subgraph "Application Logic"
                direction TB
                MainApp["main.cpp (sweep/read/display/serial)"]:::firmware
                LCDGlue["lcd.cpp"]:::firmware
                LCDHeader["lcd.h"]:::firmware
            end

            SerialOut["Serial Output (UART)"]:::firmware
        end

        %% Click Events for Firmware
        click MainApp "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/src/main.cpp"
        click LCDGlue "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/src/lcd.cpp"
        click LCDHeader "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/include/lcd.h"

        %% Click Events for HAL & Drivers
        click ServoLib "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/lib/Servo/Servo.h"
        click SPILib "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/lib/SPI/SPI.h"
        click SPILib "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/lib/SPI/SPI.cpp"
        click UcglibLib "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/lib/Ucglib/Ucglib.h"
        click UcglibLib "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/lib/Ucglib/Ucglib.cpp"
        click UcglibLib "https://github.com/rodrigoacc10/ultrasonic_radar/tree/main/lib/Ucglib/clib/"

        %% Hardware to MCU
        Sensor -->|"digital trigger/echo"| MainApp
        ServoMotor -->|"PWM"| ServoLib
        ServoLib -->|"control"| MainApp
        LCDDisplay -->|"SPI"| SPILib
        SPILib -->|"drivers"| UcglibLib
        UcglibLib -->|"graphics API"| LCDGlue
        MainApp -->|"updates"| LCDGlue
        MainApp -->|"writes"| SerialOut
        SerialOut -->|"USB"| USBSerial

    end

    %% PC Side
    subgraph "PC Side" 
        direction TB
        SerialReader["Serial Acquisition Module"]:::pc
        Plotter["Plotting Module"]:::pc
    end

    USBSerial -->|"serial data"| SerialReader
    SerialReader -->|"parsed data"| Plotter

    %% Click Events for PC Scripts
    click SerialReader "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/script/radar_serial_plot.py"
    click SerialReader "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/script/radar_serial_plot_csv.py"
    click SerialReader "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/script/radar_serial_plot_grid.py"
    click SerialReader "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/script/README.md"

    %% Tests
    subgraph "Unit Tests" 
        direction TB
        TestLCD["test_lcd.cpp"]:::test
        TestMain["test_main.cpp"]:::test
        TestServo["test_servo.cpp"]:::test
        TestTestReadme["test/README"]:::test
    end

    TestLCD --> MainApp
    TestMain --> MainApp
    TestServo --> ServoLib

    click TestLCD "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/test/test_lcd/test_lcd.cpp"
    click TestMain "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/test/test_main/test_main.cpp"
    click TestServo "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/test/test_servo/test_servo.cpp"
    click TestTestReadme "https://github.com/rodrigoacc10/ultrasonic_radar/tree/main/test/README"

    %% Documentation
    subgraph "Documentation" 
        direction TB
        DocPy["py_scripts_design.md"]:::docs
        DocLCD["lcd_sdd.md"]:::docs
        DocMain["main_sdd.md"]:::docs
        DocSerial["serial_sdd.md"]:::docs
        DocReq["radar_sim_req.md"]:::docs
        DocTst["radar_sim_tst.md"]:::docs
    end

    click DocPy "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/doc/python/py_scripts_design.md"
    click DocLCD "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/doc/sdd/lcd_sdd.md"
    click DocMain "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/doc/sdd/main_sdd.md"
    click DocSerial "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/doc/sdd/serial_sdd.md"
    click DocReq "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/doc/req/radar_sim_req.md"
    click DocTst "https://github.com/rodrigoacc10/ultrasonic_radar/blob/main/doc/tst/radar_sim_tst.md"

    %% Styles
    classDef hardware fill:#f9d5a2,stroke:#e38e1c,color:#000
    classDef firmware fill:#d0e1f9,stroke:#2a6f9e,color:#000
    classDef pc fill:#d4f9d0,stroke:#3e8e3e,color:#000
    classDef toolchain fill:#fff2b2,stroke:#d1a100,color:#000
    classDef config fill:#fff2b2,stroke:#d1a100,color:#000
    classDef test fill:#f9c2d0,stroke:#c9003f,color:#000
    classDef docs fill:#e2e2e2,stroke:#888,color:#000
```
