# jkaflik/openmowernext architecture

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

- Interactive diagram: https://gitdiagram.com/jkaflik/openmowernext
- Repository: https://github.com/jkaflik/openmowernext

## Overview

##### Project type and purpose
- OpenMowerNext is a robotics application / middleware stack built on ROS 2 (Jazzy) for an open‑source lawn mower robot. It provides node packages for localization, mapping, control, simulation, hardware drivers (GPS, IMU, VESC motor controllers), action servers, services, and tooling (map recorder, map server) to run on real hardware or in Gazebo.

##### File structure
- Top‑level directories:
- src/ – ROS 2 packages (action, lib, map_recorder, map_server, sim)
- launch/ – Python launch files to compose the system
- config/ – parameter files (behavior trees, nav2, controllers, hardware YAMLs)
- description/ – URDF/XACRO robot model, sensors, controllers
- worlds/ – Gazebo world definitions
- maps/ – recorded maps
- docs/ – architecture write‑ups, VitePress site
- .devcontainer/, Dockerfile, docker‑compose.yaml – dev & container setup
- Notice ROS 2 design: each package defines nodes, messages (.msg), actions (.action), services (.srv), and test scripts.

##### README for additional insights
- This is a ROS 2 migration of an existing ROS 1 project, aiming to teach robot development and eventually add advanced features (pairing, obstacle avoidance).
- Documentation site includes deeper architectural descriptions (e.g., localization, map recorder, map server, firmware integration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Interface Layer
    subgraph "Hardware Interface" 
        direction TB
        MRA["micro-ROS Agent"]:::hardware
        UBLOX["ublox_f9p & NTRIP Client"]:::hardware
        VESC["VESC Motor Controller Driver"]:::hardware
    end

    %% Perception & Localization
    subgraph "Perception & Localization"
        direction TB
        IMU["IMU Sensor & EKF (robot_localization)"]:::perception
    end

    %% Mapping Layer
    subgraph "Mapping"
        direction TB
        REC["Boundary Recorder"]:::mapping
        SERVER["GeoJSON Map Server"]:::mapping
    end

    %% Navigation Layer
    subgraph "Navigation"
        direction TB
        NAV2["Nav2 Stack"]:::planning
        TWIST["twist_mux"]:::planning
    end

    %% High-Level Behavior
    subgraph "High-Level Behaviors & Actions"
        direction TB
        BT["Behavior Tree Orchestration"]:::planning
        ACT["Action Servers"]:::planning
    end

    %% Simulation & Visualization
    subgraph "Simulation & Visualization"
        direction TB
        SIM["Simulation Node & Gazebo"]:::simulation
        VIS["Foxglove / RViz"]:::simulation
    end

    %% DevOps & Deployment
    subgraph "DevOps / Deployment"
        direction TB
        DOCKER["Container & Env Setup"]:::devops
        LAUNCH["Launch Orchestration"]:::devops
    end

    %% Data Flows
    MRA -->|"DDS Bridge"| UBLOX
    MRA -->|"DDS Bridge"| VESC
    UBLOX -->|"/gps_topic"| IMU
    IMU -->|"/imu & /odom"| NAV2
    NAV2 -->|"cmd_vel"| VESC
    REC -->|"/boundary_geojson"| SERVER
    SERVER -->|"/map_service"| NAV2
    NAV2 -->|"/path"| BT
    BT -->|"/dock_action, area_boundary_action"| ACT
    SIM -->|"/tf, sensor data"| NAV2
    LAUNCH -->|launch configs| MRA & UBLOX & VESC & IMU & REC & SERVER & NAV2 & TWIST & BT & ACT & SIM & VIS

    %% Click Events - Hardware Interface
    click MRA "https://github.com/jkaflik/openmowernext/tree/main/src/lib/micro_ros_agent"
    click MRA "https://github.com/jkaflik/openmowernext/blob/main/launch/micro_ros_agent.launch.py"
    click UBLOX "https://github.com/jkaflik/openmowernext/tree/main/src/lib/ublox_f9p"
    click UBLOX "https://github.com/jkaflik/openmowernext/tree/main/src/lib/ntrip_client"
    click UBLOX "https://github.com/jkaflik/openmowernext/blob/main/config/gps.yaml"
    click UBLOX "https://github.com/jkaflik/openmowernext/blob/main/launch/gps.launch.py"
    click VESC "https://github.com/jkaflik/openmowernext/tree/main/src/lib/vesc"
    click VESC "https://github.com/jkaflik/openmowernext/blob/main/config/hardware/vesc.yaml"

    %% Click Events - Perception & Localization
    click IMU "https://github.com/jkaflik/openmowernext/blob/main/description/imu.xacro"
    click IMU "https://github.com/jkaflik/openmowernext/blob/main/config/robot_localization.yaml"
    click IMU "https://github.com/jkaflik/openmowernext/blob/main/launch/localization.launch.py"

    %% Click Events - Mapping
    click REC "https://github.com/jkaflik/openmowernext/blob/main/src/map_recorder/map_recorder_node.cpp"
    click REC "https://github.com/jkaflik/openmowernext/blob/main/src/map_recorder/map_recorder_node.hpp"
    click REC "https://github.com/jkaflik/openmowernext/blob/main/src/map_recorder/utils.hpp"
    click REC "https://github.com/jkaflik/openmowernext/blob/main/launch/openmower.launch.py"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/map_server_node.cpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/map_server_node.hpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/geo_json_map.cpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/geo_json_map.hpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/node_main.cpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/polygon_iterator.hpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/polygon_utils.hpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/some_gaussian_filter.hpp"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/test/load_geojson_map.test.py"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/src/map_server/test/test_map.geojson"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/launch/openmower.launch.py"
    click SERVER "https://github.com/jkaflik/openmowernext/blob/main/maps/world.yaml"

    %% Click Events - Navigation
    click NAV2 "https://github.com/jkaflik/openmowernext/blob/main/launch/nav2.launch.py"
    click NAV2 "https://github.com/jkaflik/openmowernext/blob/main/config/nav2_params.yaml"
    click NAV2 "https://github.com/jkaflik/openmowernext/blob/main/config/behavior_tree.xml"
    click NAV2 "https://github.com/jkaflik/openmowernext/blob/main/config/twist_mux.yaml"
    click NAV2 "https://github.com/jkaflik/openmowernext/blob/main/config/controllers.yaml"

    %% Click Events - High-Level Behaviors & Actions
    click BT "https://github.com/jkaflik/openmowernext/blob/main/config/behavior_tree.xml"
    click ACT "https://github.com/jkaflik/openmowernext/blob/main/src/action/DockNearest.action"
    click ACT "https://github.com/jkaflik/openmowernext/blob/main/src/action/DockTo.action"
    click ACT "https://github.com/jkaflik/openmowernext/blob/main/src/action/RecordAreaBoundary.action"
    click ACT "https://github.com/jkaflik/openmowernext/blob/main/src/action/RecordDockingStation.action"

    %% Click Events - Simulation & Visualization
    click SIM "https://github.com/jkaflik/openmowernext/blob/main/worlds/empty.sdf"
    click SIM "https://github.com/jkaflik/openmowernext/blob/main/launch/sim.launch.py"
    click SIM "https://github.com/jkaflik/openmowernext/blob/main/src/sim/sim_node.cpp"
    click SIM "https://github.com/jkaflik/openmowernext/blob/main/src/sim/sim_node.hpp"
    click SIM "https://github.com/jkaflik/openmowernext/blob/main/src/sim/node_main.cpp"
    click SIM "https://github.com/jkaflik/openmowernext/blob/main/description/robot.urdf.xacro"
    click SIM "https://github.com/jkaflik/openmowernext/blob/main/description/gazebo_control.xacro"
    click VIS "https://github.com/jkaflik/openmowernext/blob/main/foxglove/default.json"
    click VIS "https://github.com/jkaflik/openmowernext/blob/main/config/view_bot.rviz"

    %% Click Events - DevOps & Deployment
    click DOCKER "https://github.com/jkaflik/openmowernext/tree/main/Dockerfile"
    click DOCKER "https://github.com/jkaflik/openmowernext/blob/main/docker-compose.yaml"
    click DOCKER "https://github.com/jkaflik/openmowernext/tree/main/.devcontainer/"
    click DOCKER "https://github.com/jkaflik/openmowernext/blob/main/utils/docker-entrypoint.sh"
    click DOCKER "https://github.com/jkaflik/openmowernext/blob/main/utils/install-custom-deps.sh"
    click DOCKER "https://github.com/jkaflik/openmowernext/blob/main/utils/envs.sh"
    click DOCKER "https://github.com/jkaflik/openmowernext/tree/main/.github/workflows/"

    click LAUNCH "https://github.com/jkaflik/openmowernext/blob/main/launch/openmower.launch.py"
    click LAUNCH "https://github.com/jkaflik/openmowernext/blob/main/launch/rsp.launch.py"
    click LAUNCH "https://github.com/jkaflik/openmowernext/blob/main/launch/joystick.launch.py"

    %% Styles
    classDef hardware fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef perception fill:#A9DFBF,stroke:#196F3D,color:#1B2631;
    classDef mapping fill:#F5B041,stroke:#B9770E,color:#1B2631;
    classDef planning fill:#D2B4DE,stroke:#7D3C98,color:#1B2631;
    classDef simulation fill:#D5D8DC,stroke:#566573,color:#1B2631;
    classDef devops fill:#F2F3F4,stroke:#909497,color:#1B2631;
```
