Wheelly Robot Software Architecture

Release: 0.29.0

This document details the definitive 6-layer decoupled architecture for the Wheelly robot project, structured under the root package org.mmarini.wheelly.

---

Architecture Overview

The architecture is designed using a sibling package structure to prevent nested dependency cycles. Each layer represents a distinct level of abstraction, shifting from low-level hardware communication to high-level neural decision-making.

graph TD
    %% Define Layers
    L6[Layer 6: org.mmarini.wheelly.agents]
    L5[Layer 5: org.mmarini.wheelly.gym]
    L4[Layer 4: org.mmarini.wheelly.behaviors]
    L3[Layer 3: org.mmarini.wheelly.perception]
    L2[Layer 2: org.mmarini.wheelly.control]
    L1[Layer 1: org.mmarini.wheelly.robots]

    %% Data Flows    
    L1 -- Raw Telemetry --> L2
    L2 -- Aggregated State --> L3
    L3 -- Aggregated State --> L4
    L3 -- 2D Occupancy Grid --> L4
    L4 -- Aggregated State --> L5
    L4 -- 2D Occupancy Grid --> L5
    L4 -- Behaviour state --> L5
    L5 -- State Tensors & Rewards --> L6

    L6 -- Discrete Action ID --> L5
    L5 -- Behavioural Intention --> L4
    L4 -- Motion / Head Targets --> L3
    L3 -- Motion / Head Targets --> L2
    L2 -- Low-Level Commands --> L1

    %% Styling
    style L1 fill:#f9f,stroke:#333,stroke-width:2px
    style L2 fill:#bbf,stroke:#333,stroke-width:2px
    style L3 fill:#bfb,stroke:#333,stroke-width:2px
    style L4 fill:#fbb,stroke:#333,stroke-width:2px
    style L5 fill:#ffb,stroke:#333,stroke-width:2px
    style L6 fill:#fbc,stroke:#333,stroke-width:2px

---

Detailed Layer Specification

Layer 1: org.mmarini.wheelly.robots

• Responsibility: Low-level hardware interfacing, message modelling, and core simulation.
• Key Components:
  • RobotApi: Core Java interface abstracting hardware interaction (e.g., move(), scan(), getTelemetry()).

Layer 2: org.mmarini.wheelly.control

• Responsibility: Sensor data aggregation, localization tracking, and closed-loop control of macro-states.
• Key Components:
  • RobotController: Coordinates aggregated status delivery and dispatches decomposed kinematic commands.

Layer 3: org.mmarini.wheelly.perception

• Responsibility: Mapping and transformation of spatial sensory readings into a unified environment model.
• Key Components:
  • WorldModeller: Updates the spatial memory of the robot from incoming controller states.

Layer 4: org.mmarini.wheelly.behaviors

• Responsibility: Complex autonomous behaviours, strategic navigation routines, and immediate hazard recovery.

Layer 5: org.mmarini.wheelly.gym

• Responsibility: Implements the Reinforcement Learning (RL) environment interface, handling state tensor wrapping and reward estimation.

Layer 6: org.mmarini.wheelly.agents

• Responsibility: Deep Neural Network inference and Actor-Critic optimization engines.

---

Execution & Dependency Injection

To ensure perfect isolation, layers never instantiate their siblings. Compilation dependencies flow strictly downwards. At execution time, instantiation occurs inside the root controller runner classes