Skip to content

18. Wheelly Robot Software Architecture

Jump to bottom
Marco Marini edited this page Oct 16, 2026 · 2 revisions

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
Loading

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

Clone this wiki locally