# teamaguarai/pampas architecture

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

- Interactive diagram: https://gitdiagram.com/teamaguarai/pampas
- Repository: https://github.com/teamaguarai/pampas

## Overview

##### Project type and purpose
- pampas is a C++ embedded-control library for Raspberry Pi that drives an RC car (motor + steering) and reads sensors (wheel pulse, IMU).
- It provides a hardware abstraction layer (HAL), control algorithms (PID, filters), and an API for user code.

##### File structure
- / & src/
- Public headers and implementations for each module:
– Drive (overall motion), PID (controller), Steer, Motor, PulseWidth, Velocimeter, MPU9250 (IMU), I2Cdev, gpio, Conversion, LowPass, operations, Writer, Exception.
- scripts/ & install
- Installation and wiringPi setup scripts for Raspberry Pi.
- testing/
- Unit tests for each module, verifying control loops, sensor reads, error handling, etc.

##### README
- Describes system: Raspberry Pi ↔ sensors (pulse, IMU via I2C) ↔ actuators (motor, steering servo).
- Shows example usage: configure Drive (PID + transfer function + motor pins + velocimeter), then run control loop.
- Points out compilation flags and dependencies: –lpampas –lwiringPi.

##### Components
a. Application Layer (user code)
– main.cpp (or external client), calls pampas::Drive, pampas::Velocimeter, etc.
b. Control Layer
– Drive module: orchestrates control loop
– PID module: computes control output
– Transfer functions & operations: polynomial regression, conversions
c. Sensor Abstraction Layer
– Velocimeter: reads pulse pin via gpio → measures wheel speed
– MPU9250 + I2Cdev: reads IMU over I²C bus
– LowPass: filters sensor noise
d. Actuator Abstraction Layer
– Motor + PulseWidth: generates PWM via gpio to motor driver
– Steer: generates PWM to steering servo
e. HAL & Platform Interfaces
– gpio: wrapper around wiringPi for pin I/O
– wiringPi (external) & I2C bus driver
f. External Hardware
– Raspberry Pi 3 (SOC, CPU, I/O headers)
– ESC / servo / motor assembly
– Hall-effect or IR sensor for wheel speed
– MPU9250 IMU sensor

##### Relationships & Data Flow
- Application Layer → invokes Control Layer (Drive.run())
- Control Layer ↔ Sensor Abstraction:
- starts velocimeter, waits for update → gets speed feedback
- reads IMU data continuously via I2Cdev → feeds into filters
- Control Layer → computes outputs via PID & transfer functions → passes commands to Actuator Layer
- Actuator Layer → uses gpio/PulseWidth to emit PWM signals → drives physical actuators
- Hardware sends back sensor signals → loop continues

##### Architectural patterns & design principles
- Layered architecture: clear separation between user code, control logic, HAL, and hardware
- Hardware Abstraction Layer (gpio, I2Cdev) to isolate platform details
- Single Responsibility: each class (Motor, Velocimeter, PID) has one focus
- Feedback control loop: real-time sensing → compute → actuate → sense

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        App["main.cpp"]:::app
    end

    %% Control Layer
    subgraph "Control Layer"
        direction TB
        Drive["Drive Module"]:::control
        PID["PID Controller"]:::control
        Ops["Transfer Functions & Operations"]:::control
        Conv["Unit Conversion Utilities"]:::control
        Exc["Exception Handling"]:::control
        Wrt["Logging/Output Writer"]:::control
    end

    %% Sensor Abstraction Layer
    subgraph "Sensor Abstraction Layer"
        direction TB
        Vel["Velocimeter (Wheel Pulse)"]:::control
        IMU["MPU9250 (IMU Interface)"]:::control
        I2C["I2Cdev (I²C Bus)"]:::control
        LPF["Low-Pass Filter"]:::control
    end

    %% Actuator Abstraction Layer
    subgraph "Actuator Abstraction Layer"
        direction TB
        Motor["Motor Actuator"]:::control
        PWM["PWM Generator (PulseWidth)"]:::control
        Steer["Steering Actuator"]:::control
    end

    %% HAL / Platform Interfaces
    subgraph "HAL / Platform Interfaces"
        direction TB
        GPIO["GPIO HAL"]:::hal
        WPi["wiringPi (external)"]:::hal
    end

    %% External Hardware
    subgraph "Physical Hardware"
        direction TB
        Pi["Raspberry Pi 3"]:::hardware
        ESC["ESC/Motor Assembly"]:::hardware
        Hall["Hall-Effect Wheel Sensor"]:::hardware
        IMUSensor["MPU9250 Sensor"]:::hardware
        Servo["Steering Servo"]:::hardware
    end

    %% Deployment & Tests
    subgraph "Deployment & Validation"
        direction TB
        Install["install.sh"]:::hal
        WiringPiScript["wiringPi.sh"]:::hal
        Tests["Unit Tests"]:::hal
    end

    %% Relationships
    App -->|"invokes run()"| Drive
    Drive -->|"uses"| PID
    Drive -->|"uses"| Ops
    Drive -->|"uses"| Conv
    Drive -->|"handles errors via"| Exc
    Drive -->|"logs via"| Wrt

    Drive -->|"reads speed"| Vel
    Drive -->|"reads IMU"| IMU
    Drive -->|"filters via"| LPF

    Vel -->|-->| Drive
    IMU -->|-->| Drive
    LPF -->|-->| Drive

    Drive -->|"commands"| Motor
    Drive -->|"commands"| Steer
    Motor -->|"via PWM"| PWM
    Steer -->|"via PWM"| PWM

    Motor -->|"GPIO"| GPIO
    PWM -->|"GPIO"| GPIO
    GPIO -->|-->| ESC
    PWM -->|-->| Servo

    IMU -->|"I2C bus"| I2C
    I2C -->|-->| IMUSensor
    Vel -->|-->| Hall

    Pi -->|hosts| GPIO
    Pi -->|hosts| I2C
    WPi -->|backend for| GPIO

    Install -->|deploys to| Pi
    WiringPiScript -->|setup| WPi
    Tests -->|validate modules| Drive

    %% Click Events
    click Drive "https://github.com/teamaguarai/pampas/blob/main/include/Drive.h"
    click PID "https://github.com/teamaguarai/pampas/blob/main/include/PID.h"
    click Ops "https://github.com/teamaguarai/pampas/blob/main/include/operations.h"
    click Conv "https://github.com/teamaguarai/pampas/blob/main/include/Conversion.h"
    click Exc "https://github.com/teamaguarai/pampas/blob/main/include/Exception.h"
    click Wrt "https://github.com/teamaguarai/pampas/blob/main/include/Writer.h"
    click Vel "https://github.com/teamaguarai/pampas/blob/main/include/Velocimeter.h"
    click IMU "https://github.com/teamaguarai/pampas/blob/main/include/MPU9250.h"
    click I2C "https://github.com/teamaguarai/pampas/blob/main/include/I2Cdev.h"
    click LPF "https://github.com/teamaguarai/pampas/blob/main/include/LowPass.h"
    click GPIO "https://github.com/teamaguarai/pampas/blob/main/include/gpio.h"
    click Motor "https://github.com/teamaguarai/pampas/blob/main/include/Motor.h"
    click PWM "https://github.com/teamaguarai/pampas/blob/main/include/PulseWidth.h"
    click Steer "https://github.com/teamaguarai/pampas/blob/main/include/Steer.h"
    click Install "https://github.com/teamaguarai/pampas/blob/main/scripts/install.sh"
    click WiringPiScript "https://github.com/teamaguarai/pampas/blob/main/scripts/wiringPi.sh"
    click Tests "https://github.com/teamaguarai/pampas/blob/main/testing/*.cpp"

    %% Styles
    classDef app fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef control fill:#FFF3CD,stroke:#333,stroke-width:1px
    classDef hal fill:#D4EDDA,stroke:#333,stroke-width:1px
    classDef hardware fill:#E2E3E5,stroke:#333,stroke-width:1px
```
