# 2e10-buggyproject/buggysoftware architecture

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

- Interactive diagram: https://gitdiagram.com/2e10-buggyproject/buggysoftware
- Repository: https://github.com/2e10-buggyproject/buggysoftware

## Overview

##### Main Components
- Autonomous Buggy Controller: Use the Gold code (e.g., GoldBuggyVFinal.ino) as the core firmware running on a microcontroller.
- Sensor Suite:
– Line-following sensors (likely IR sensors) to detect and follow track lines.
– Ultrasound sensor for obstacle detection (if still used, inherited by previous challenges).
– Wheel encoders for measuring distance travelled.
– HuskyLens vision sensor for detecting and interpreting April tags.
- Decision & Control Unit:
– Input Processing Module: Interfaces with all sensors, reads raw data.
– Tag Recognition Module: Processes the vision sensor data to identify April tags and decode instructions (such as turning left/right, adjusting speed, etc.).
– Navigation & Behavior Module: Implements logic (e.g., state machine or decision tree) that translates sensor inputs and tag instructions into motor control commands.
- Actuator Control:
– Motor Driver Circuit: Actually interfaces with the buggy’s motors to control movement based on the commands.
– PID Speed Controller: (Inherited from Silver challenge but might also be integrated here) to adjust motor speeds accurately per the challenge instruction, especially after speed-related April tags.
- Communication & Telemetry (if applicable):
– Although the Bronze version required a PC-based GUI to send GO/STOP commands and display telemetry, for Gold the primary focus is on autonomous decision-making. If telemetry is still provided, include a bi-directional link to a PC module or logging interface.

##### Relationships and Data Flow
- Sensor Data Flow: Each sensor gathers measurements and passes data to the Input Processing Module.
– The HuskyLens sends processed images and tag-related data to the Tag Recognition Module.
– IR sensors, ultrasound, and wheel encoders feed information directly into the Navigation & Behavior Module.
- Control Flow: The Navigation & Behavior Module determines the desired action (e.g., “turn left”, “speed up”, “reduce speed”) and sends commands downstream to the Motor Driver and (if applicable) to the PID Controller.

##### Important Architectural Patterns
- Modular decomposition: Clearly separate sensor interfacing, decision-making, and motor control.
- Closed-loop control: Emphasize the feedback from wheel encoders (and possibly other sensors) to the PID Controller.
- Real-time processing: Ensure that sensor inputs (especially the vision sensor for April tag detection) and decision logic operate in a timely fashion.

##### Relevant Technologies and Frameworks
- Programming language/firmware: Arduino-style sketches (.ino files in the Gold folder).
- Sensor libraries: Libraries for interfacing with IR sensors, US sensor and especially the HuskyLens (for April tags).
- PID libraries: Likely used for speed regulation imported from the Silver challenge revisions.
- (Optional) Communication libraries if telemetry or PC interfacing remains relevant beyond Bronze.

- At the microcontroller level, detail the sequence:
1. Sensor data acquisition (show branches for each sensor).
2. Data parsing and filtering (especially from HuskyLens, converting visual input to April tag instructions).
3. Decision-making logic:
- For “Turn Left” or “Turn Right”: a conditional decision block triggered by the recognized tag.
- For “Speed Limit” or “Accelerate”: a PID control block that adapts motor commands.
4. Actuation & motor control:
- Motor Driver receiving commands, with visual feedback controls (from wheel encoders).
- Timing or synchronization elements if necessary (e.g., real-time sensor polling loops and state machine transitions).

##### Final Touches
- Block is clearly labeled and describes its function.
- Notes/comments around any critical interfaces—such as the exact wiring between the HuskyLens sensor and the microcontroller if known.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Autonomous Buggy Controller"
        Firmware["Autonomous Buggy Controller (GoldBuggyVFinal.ino)"]:::firmware
        %% Sensor Suite
        subgraph "Sensor Suite"
            IR["Line-Following IR Sensors"]:::sensor
            US["Ultrasound Sensor"]:::sensor
            WE["Wheel Encoders"]:::sensor
            HL["HuskyLens Vision Sensor (April Tag Reader)"]:::sensor
        end
        %% Control Unit
        subgraph "Control Unit"
            IP["Input Processing Module"]:::control
            TR["Tag Recognition Module"]:::control
            NB["Navigation & Behavior Module"]:::control
            PID["PID Speed Controller"]:::control
        end
        %% Actuator Unit
        subgraph "Actuator Unit"
            MD["Motor Driver Circuit"]:::actuator
        end
    end

    %% Documentation Node
    Documentation["Gold Challenge Documentation & Notes"]:::doc

    %% Data Flow from Sensors to Control Unit
    IR -->|"SensorData"| IP
    US -->|"SensorData"| IP
    WE -->|"SensorData"| IP
    HL -->|"AprilTagData"| TR

    %% Control Data Flow
    IP -->|"ProcessedData"| NB
    TR -->|"TagFlag"| NB
    NB -->|"SpeedCommand"| PID
    NB -->|"MotorCommands"| MD
    PID -->|"AdjustedSpeed"| MD

    %% Feedback from Actuator (Wheel Encoders for Closed-Loop)
    WE -.->|"Feedback"| PID

    %% Click Events
    click Firmware "https://github.com/2e10-buggyproject/buggysoftware/blob/main/Gold/GoldBuggyVFinal.ino"
    click IP "https://github.com/2e10-buggyproject/buggysoftware/blob/main/Gold/GoldBuggyVFinal.ino"
    click TR "https://github.com/2e10-buggyproject/buggysoftware/blob/main/Gold/GoldBuggyVFinal.ino"
    click NB "https://github.com/2e10-buggyproject/buggysoftware/blob/main/Gold/GoldBuggyVFinal.ino"
    click Documentation "https://github.com/2e10-buggyproject/buggysoftware/blob/main/Gold/README.md"

    %% Styles
    classDef sensor fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef control fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef actuator fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef firmware fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef doc fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
