# erol001/mobile-robotics-project architecture

> Architecture diagram of the GitHub repository erol001/mobile-robotics-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erol001/mobile-robotics-project
- Repository: https://github.com/erol001/mobile-robotics-project

## Overview

This repository implements camera-guided navigation for a Thymio robot: camera frames yield a metric map, robot pose, obstacles, and goal; planning and waypoint following produce motion commands, with proximity-based avoidance and robot I/O closing the loop. `main.py` is the runtime orchestrator. The sampled source supports the service and vision internals shown; some main-loop calls and peripheral UI wiring are omitted because the excerpts are partial.

Main entry points: [`main.py`](https://github.com/erol001/mobile-robotics-project/blob/master/main.py) (Runtime loop), [`services/vision_service.py`](https://github.com/erol001/mobile-robotics-project/blob/master/services/vision_service.py) (Vision service), [`services/planner_service.py`](https://github.com/erol001/mobile-robotics-project/blob/master/services/planner_service.py) (Planner service), [`functions/vision/camera.py`](https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/camera.py) (Camera and map warp)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Runtime loop<br/>[main.py]"]
  node_hud["Display and trace<br/>[hud.py]"]
  node_trace["Run trace<br/>[trace.py]"]
end

subgraph group_perception["Camera perception"]
  node_vision_service["Vision service<br/>[vision_service.py]"]
  node_camera["Camera and map warp<br/>[camera.py]"]
  node_tags["AprilTag mapping<br/>[apriltags.py]"]
  node_pose["Robot pose<br/>[pose.py]"]
  node_obstacles["Obstacle geometry<br/>[obstacles.py]"]
  node_goal["Goal detection<br/>[goal.py]"]
end

subgraph group_navigation["Navigation and control"]
  node_planner_service["Planner service<br/>[planner_service.py]"]
  node_planner["Visibility graph and A*<br/>[planner.py]"]
  node_ekf["Pose estimator<br/>[ekf_service.py]"]
  node_controller["Waypoint controller<br/>[control_service.py]"]
  node_avoidance["Local avoidance"]
end

subgraph group_robot["Robot and monitoring"]
  node_thymio["Thymio interface<br/>[thymio_io.py]"]
  node_kidnap["Kidnap monitor<br/>[kidnap_service.py]"]
end

node_operator(("Operator"))

node_operator -->|"starts run"| node_main
node_main -->|"reads frames"| node_vision_service
node_vision_service -->|"warps frames"| node_camera
node_camera -->|"detects tags"| node_tags
node_vision_service -->|"estimates pose"| node_pose
node_vision_service -->|"extracts obstacles"| node_obstacles
node_vision_service -->|"detects goal"| node_goal
node_vision_service -->|"returns perception"| node_main
node_main -->|"updates estimate"| node_ekf
node_main -->|"requests plan"| node_planner_service
node_planner_service -->|"builds graph and searches"| node_planner
node_planner_service -->|"returns path"| node_main
node_main -->|"computes motion"| node_controller
node_main -.->|"blends avoidance"| node_avoidance
node_main -->|"reads sensors and sends motors"| node_thymio
node_main -->|"checks proximity"| node_kidnap
node_main -->|"renders status"| node_hud
node_main -->|"records run"| node_trace

click node_main "https://github.com/erol001/mobile-robotics-project/blob/master/main.py"
click node_vision_service "https://github.com/erol001/mobile-robotics-project/blob/master/services/vision_service.py"
click node_camera "https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/camera.py"
click node_tags "https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/apriltags.py"
click node_pose "https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/pose.py"
click node_obstacles "https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/obstacles.py"
click node_goal "https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/goal.py"
click node_planner_service "https://github.com/erol001/mobile-robotics-project/blob/master/services/planner_service.py"
click node_planner "https://github.com/erol001/mobile-robotics-project/blob/master/functions/planner.py"
click node_ekf "https://github.com/erol001/mobile-robotics-project/blob/master/services/ekf_service.py"
click node_controller "https://github.com/erol001/mobile-robotics-project/blob/master/services/control_service.py"
click node_avoidance "https://github.com/erol001/mobile-robotics-project/blob/master/services/local_avoidance_service.py"
click node_thymio "https://github.com/erol001/mobile-robotics-project/blob/master/functions/thymio_io.py"
click node_kidnap "https://github.com/erol001/mobile-robotics-project/blob/master/services/kidnap_service.py"
click node_hud "https://github.com/erol001/mobile-robotics-project/blob/master/functions/hud.py"
click node_trace "https://github.com/erol001/mobile-robotics-project/blob/master/functions/trace.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_hud,node_trace toneBlue
class node_vision_service,node_camera,node_tags,node_pose,node_obstacles,node_goal toneAmber
class node_planner_service,node_planner,node_ekf,node_controller,node_avoidance toneMint
class node_thymio,node_kidnap toneRose
class node_operator toneIndigo
```

## Components

### Runtime orchestration

- [Runtime loop](https://github.com/erol001/mobile-robotics-project/blob/master/main.py): `main.py`
- [Display and trace](https://github.com/erol001/mobile-robotics-project/blob/master/functions/hud.py): `functions/hud.py`
- [Run trace](https://github.com/erol001/mobile-robotics-project/blob/master/functions/trace.py): `functions/trace.py`

### Camera perception

- [Vision service](https://github.com/erol001/mobile-robotics-project/blob/master/services/vision_service.py): `services/vision_service.py`
- [Camera and map warp](https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/camera.py): `functions/vision/camera.py`
- [AprilTag mapping](https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/apriltags.py): `functions/vision/apriltags.py`
- [Robot pose](https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/pose.py): `functions/vision/pose.py`
- [Obstacle geometry](https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/obstacles.py): `functions/vision/obstacles.py`
- [Goal detection](https://github.com/erol001/mobile-robotics-project/blob/master/functions/vision/goal.py): `functions/vision/goal.py`

### Navigation and control

- [Planner service](https://github.com/erol001/mobile-robotics-project/blob/master/services/planner_service.py): `services/planner_service.py`
- [Visibility graph and A*](https://github.com/erol001/mobile-robotics-project/blob/master/functions/planner.py): `functions/planner.py`
- [Pose estimator](https://github.com/erol001/mobile-robotics-project/blob/master/services/ekf_service.py): `services/ekf_service.py`
- [Waypoint controller](https://github.com/erol001/mobile-robotics-project/blob/master/services/control_service.py): `services/control_service.py`
- [Local avoidance](https://github.com/erol001/mobile-robotics-project/blob/master/services/local_avoidance_service.py): `services/local_avoidance_service.py`

### Robot and monitoring

- [Thymio interface](https://github.com/erol001/mobile-robotics-project/blob/master/functions/thymio_io.py): `functions/thymio_io.py`
- [Kidnap monitor](https://github.com/erol001/mobile-robotics-project/blob/master/services/kidnap_service.py): `services/kidnap_service.py`

### Other components

- **Operator**

## Connections

- Operator → Runtime loop: starts run
- Runtime loop → Vision service: reads frames
- Vision service → Camera and map warp: warps frames
- Camera and map warp → AprilTag mapping: detects tags
- Vision service → Robot pose: estimates pose
- Vision service → Obstacle geometry: extracts obstacles
- Vision service → Goal detection: detects goal
- Vision service → Runtime loop: returns perception
- Runtime loop → Pose estimator: updates estimate
- Runtime loop → Planner service: requests plan
- Planner service → Visibility graph and A*: builds graph and searches
- Planner service → Runtime loop: returns path
- Runtime loop → Waypoint controller: computes motion
- Runtime loop → Local avoidance: blends avoidance
- Runtime loop → Thymio interface: reads sensors and sends motors
- Runtime loop → Kidnap monitor: checks proximity
- Runtime loop → Display and trace: renders status
- Runtime loop → Run trace: records run