# nboliv/sumorobots architecture

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

- Interactive diagram: https://gitdiagram.com/nboliv/sumorobots
- Repository: https://github.com/nboliv/sumorobots

## Overview

##### Project Type and Purpose
- This is an embedded systems/firmware project intended for programming autonomous sumo robots.
- The README indicates that the repository holds the firmware used for different robot prototypes (e.g., Bernadete and others) across annual competitions.
- The repository includes code for actual robot control logic (e.g., motor control, decisions based on sensor inputs), strategy algorithms, and a common library providing essential functionalities for sumo robots.

##### Analysis of the File Structure
- At the top level, you have various source files (*.c and *.h) and auxiliary files (*.bak, *.lst, *.hex, etc.). These auxiliary files (like the .hex file) point to compiled firmware images intended for the microcontroller.
- The files are grouped by their purpose:
- bernadete3kg_2017_beta related files: Likely the firmware implementation for the Bernadete robot version presented in 2017.
- strategies.* files: Likely contain algorithms or decision-making logic critical to the robot's operation during a match.
- sumo3kg_library.* files: A library module that houses shared functionalities such as sensor reading, motor control routines, communication protocols, or other utilities.
- test.* files: Test harness or module aimed at verifying individual components or overall firmware functionality.
- Auxiliary branches (like .pjt, .cof, .sym, .err, .lst) are supportive assets for project configuration, debugging, and post-compilation analysis.

a. Main Components:
- Hardware Platform: The target microcontroller and robot hardware (sensors, motors, etc.).
- Firmware Application: The central firmware that contains the robot control logic.
- Strategies Module: Contains the autonomous decision-making and tactical algorithms.
- Sumo3kg Library: Encapsulates common functionalities (hardware abstraction for sensor and actuator control, communication protocols, etc.).
- Testing Module: For validating functionalities either in simulation or actual unit/integration tests.
- Build/Deployment Artifacts: Represented by compiled outputs and configuration files (e.g., .hex file for flashing the device).

b. Relationships & Interactions:
- The Hardware Platform interfaces directly with the Firmware Application via a Hardware Abstraction Layer (HAL) embedded within the Sumo3kg Library.
- The Firmware Application serves as the orchestrator, calling core functions from the Sumo3kg Library and incorporating decision-making from the Strategies Module.
- Strategies Module feeds tactical commands into the Firmware Application, adjusting responses based on sensor inputs.
- The Test Module interacts with both the Sumo3kg Library and isolated parts of the Firmware Application to ensure reliability.
- Build/Deployment artifacts result from compiling the Firmware Application and related modules, which in turn drive the Hardware Platform.

c. Architectural Patterns & Design Principles:
- Modularity: The clear separation into modules such as strategies, libraries, and tests shows a modular design enabling isolation and reusability.
- Layered Architecture: The structure can be viewed as layers – from hardware interaction (at the bottom) to high-level control logic.
- Emphasis on maintainability: Backup (.bak) files and error/debug outputs indicate iterative development and debugging practices.

d. Underlying Technologies & Artifacts:
- C Programming: All main source codes (C and header files) indicate low-level, performance-oriented firmware development.
- Microcontroller Toolchain: The presence of .hex, .lst, and .sym files reflects the use of a firmware build process targeting embedded hardware.
- Project Configuration: Files like the .pjt and configuration outputs assist in organizing the build and deployment process.

##### Elements
- Clear labels for:
- Hardware Platform (sensors, actuators, microcontroller)
- Firmware Application / Main Control Loop (bernadedte3kg firmware)
- Strategies Module
- Sumo3kg Library (HAL, common utilities)
- Testing Module
- Build/Deployment Artifacts
- Data flow from hardware (inputs) to firmware, then to strategies and back out to hardware (outputs).
- Dependencies showing that the firmware calls functions from the library.
- Embedded hardware components versus software modules.
- Development/test artifacts versus production firmware.

##### Final Recommendations
- Be as detailed as possible – the goal is to capture every essential component and their interactions.
- Avoid overcomplicating: separating the project into its constituent modules and clearly highlighting their interactions is more beneficial than trying to cover every single backup or configuration file.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Platform
    subgraph "Hardware Platform"
        H1["Sensors & Actuators"]:::hardware
        H2["Microcontroller"]:::hardware
    end

    %% Firmware Application
    subgraph "Firmware Application"
        FAM["bernatede3kg firmware"]:::firmware
    end

    %% Sumo3kg Library
    subgraph "Sumo3kg Library"
        LIB["Sumo3kg Library (HAL & Utilities)"]:::library
    end

    %% Strategies Module
    subgraph "Strategies Module"
        STR["Strategies Module"]:::strategies
    end

    %% Testing Module
    subgraph "Testing Module"
        TEST["Testing Module"]:::testing
    end

    %% Build/Deployment Artifacts
    subgraph "Build/Deployment Artifacts"
        BUILD["Build Artifacts (.hex, .lst, .sym, .pjt, etc.)"]:::build
    end

    %% Relationships - Hardware to Library (HAL)
    H1 -->|"sensorData"| LIB
    H2 -->|"controlInterface"| LIB

    %% Library to Firmware Application (HAL commands)
    LIB -->|"HALcommands"| FAM

    %% Strategies Module provides decisions to Firmware Application
    STR -->|"tacticalDecisions"| FAM

    %% Firmware Application drives Hardware Platform outputs
    FAM -->|"controlCommands"| H1
    FAM -->|"controlCommands"| H2

    %% Testing Module validates Firmware Application and Library
    TEST -->|"validateFirmware"| FAM
    TEST -->|"validateLibrary"| LIB

    %% Compilation/Build process from modules to Build Artifacts
    FAM -->|"compile"| BUILD
    STR -->|"compile"| BUILD
    LIB -->|"compile"| BUILD

    %% Click Events
    click FAM "https://github.com/nboliv/sumorobots/blob/master/bernadete3kg_2017_beta.c"
    click STR "https://github.com/nboliv/sumorobots/blob/master/strategies.c"
    click LIB "https://github.com/nboliv/sumorobots/blob/master/sumo3kg_library.c"
    click TEST "https://github.com/nboliv/sumorobots/blob/master/test.c"
    click BUILD "https://github.com/nboliv/sumorobots/blob/master/bernadete3kg_2017_beta.hex"

    %% Styles
    classDef hardware fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef firmware fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef library fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef strategies fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef testing fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
