ABU Robocon 2026 — Team Vulcans

Software stack for the R2 autonomous robot competing in ABU Robocon 2026.

---

Overview

This repository contains the perception, navigation, decision-making, and deployment software for Team Vulcans' entry in ABU Robocon 2026. The competition arena is divided into three zones, each requiring distinct capabilities:

Zone	Task	Approach
Zone 1	Weapon assembly (staff + spearhead) with R1–R2 collaboration	OpenCV detection, visual servoing, no-contact assembly verification
Zone 2	Forest traversal on a 4×3 grid with 20/40/60 mm step blocks	Time-aware hybrid A*, belief-map perception, pneumatic step climbing
Zone 3	Tic-tac-toe KFS placement on a 3×3 shared rack	PPO-trained RL agent, OpenCV rack scanning, elevator/conveyor control

The codebase spans algorithm prototyping (MATLAB), simulation validation (NVIDIA Isaac Sim), RL training (PyTorch + Gymnasium), and robot deployment inference.

---

Repository Structure

Robocon26/
├── Deployment/                         # ★ R2 runtime "brain" (NEW unified tree)
│   ├── common/                         #   shared HAL + perception + alignment
│   │   ├── config.py protocol.py serial_link.py kinematics.py drive.py
│   │   ├── gripper.py pneumatics.py sensors.py imu.py odometry.py
│   │   ├── perception.py alignment.py match.py robot.py
│   ├── zone1/                          #   weapon assembly pipeline + FSM
│   │   ├── spearhead_perception.py assembly_fsm.py zone1.py config.py
│   ├── zone2/                          #   forest traversal + step climbing
│   │   ├── astar_planner.py            #     proven time-aware hybrid A* (relocated)
│   │   ├── perception.py               #     grid belief (manual / camera / default)
│   │   ├── step_climber.py             #     NEW 2-piston (tilted front + back) up/down
│   │   ├── planner_bridge.py zone2.py config.py
│   ├── firmware/esp32/                 #   r2_drive + r2_sensor + r2_manip (3 boards) + r1_manual
│   │   └── IO_CONTRACT.md              #     board↔pin↔command↔telemetry map (for embedded)
│   ├── tests/                          #   hardware-free SIM unit/integration tests
│   └── README.md                       #   full deployment layout + how to run
│
├── Zone1/                              # Weapon assembly assets (firmware → Deployment/firmware)
│   ├── Spearhead_Detection_test/       #   ROS2 YOLO-seg detection package
│   └── *.ino                           #   original R1/R2 sketches (kept as reference)
│
├── Zone2/                              # Research & training assets (NOT runtime)
│   ├── Navigation/                     #   A* prototype (Python/MATLAB) + Isaac Sim
│   └── Detection/                      #   YOLO KFS training + Jetson WebRTC server
│
├── Zone3/                              # Tic-tac-toe strategy & placement
│   ├── RL/
│   │   ├── agents/                   #   MaskedActorCritic, PPO trainer, Opponent pool
│   │   ├── env/                      #   Gymnasium env (22D obs, 10 Discrete actions)
│   │   ├── game/                     #   Board logic, vertical/diagonal win rules
│   │   ├── training/                 #   Curriculum scheduler & main train loop
│   │   ├── inference/                #   Zone3Controller for real-time robot deployment
│   │   ├── viz/                      #   Interactive Matplotlib UI for testing
│   │   └── README.md                 #   Detailed Zone 3 RL documentation
│   └── .gitignore                    #   Excludes checkpoints/ and logs/
│
├── requirements.txt                    # All Python dependencies
├── R2_GSM_Refined.md                   # Global State Machine specification (all zones)
├── R2_FSM_Refined.md                   # Finite State Machine specification (sub-states, protocols, I/O)
├── ABU Robocon 2026 Rulebook V.0.pdf   # Official competition rulebook
├── .gitignore
├── LICENSE                             # MIT License
└── README.md

---

Zone 2 — Navigation & Step Climbing

Time-Aware Hybrid A*

The core planner (time_aware_hybrid_astar.py) navigates R2 through a 4×3 grid of elevated blocks to collect KFS pieces and exit efficiently.

Key features:

• Belief-map perception — camera frames feed an OpenCV + ML pipeline that classifies each cell as R2 | R1 | FAKE | EMPTY | UNKNOWN
• Terrain-aware costs — step-up/step-down transitions are penalized proportionally to height difference (20/40/60 mm blocks)
• Dynamic priority weights — α (collection priority) and β (exit priority) shift based on current carry count
• Round-trip optimization — each candidate KFS is scored by α·cost_to_KFS + β·cost_to_exit to avoid stranding
• R1 interaction handling — soft penalty in COLLECT mode, wait/reroute in EXIT mode
• Team mirroring — grid is flipped for RED vs BLUE team

Isaac Sim Simulation

The simulation environment validates the full pipeline before hardware deployment:

Script	Purpose
integration.py	End-to-end orchestrator — step climbing, A* navigation, vision, decision loop
navigation.py	A* pathfinding with Isaac Sim robot articulation control
robot_stepclimbing.py	Pneumatic cylinder sequences (front/middle/back) for step-up and step-down
STAR_kfs_camera_infer.py	MobileNetV3 inference on simulated camera feed for KFS detection

Step Climbing

R2 uses three pneumatic cylinders (front, middle, back) for step traversal. The climb sequence is sensor-gated, not timer-based:

• Climb up: Extend middle+back → drive forward → front contacts higher surface → retract middle → advance → retract back
• Climb down: Drive till front hangs → extend front → advance → extend middle → advance → handle back (CG-dependent via IMU)

---

Zone 3 — Tic-Tac-Toe RL Agent

Architecture

A high-performance PPO agent utilizing Action Masking and Curriculum Learning (Random → Heuristic → Self-Play) to master Tic-Tac-Toe placement and sabotage.

• Masked Discrete PPO: Ensures the agent only explores legal moves.
• Team-Agnostic Observation: A 22D normalized vector allowing play as RED or BLUE without retraining.
• Integrated Visualization: Real-time Matplotlib interface for human-vs-AI strategic validation.

Observation (22D)              Masked Actor-Critic             Action (Discrete 11)
─────────────────         ─────────────────────────         ────────────────────
rack_matrix (9)  ──┐      ┌─ Shared Layers (256x256) ┐     0-8: Place at (R,C)
game_stats (6)   ──┼──▶   │         ReLU             ├──▶  9:   Tactical Sabotage
threat_info (2)  ──┤      │    ┌────┴────┐           │     10:  Wait (Pass Turn)
column_state (3) ──┤      │  Actor    Critic         │     (Invalid moves are
time/weapon (2)  ──┘      │ (11 Logits) (1D V)       │      masked out before
                          └──────────────────────────┘

Game Rules Encoded

Rule	Implementation
Placement order	Global row-based: Bottom must have ≥1 piece for Middle to open; Middle ≥1 for Top.
R2 Restrictions	Agent (R2) is strictly limited to Middle (Row 1) and Top (Row 2) placements.
Scoring	Bottom = 30 pts, Middle = 40 pts, Top = 80 pts.
Kung Fu Master	3-in-a-row (Vertical or Diagonal ONLY) = 500 bonus & Instant Win.
Weapons	1 per team, 90% success rate, removes any opponent piece. Used strategically.

Deployment & Monitoring

Zone3Controller provide the production-ready API for the Jetson:

from Zone3.RL.inference.controller import Zone3Controller

controller = Zone3Controller(checkpoint_path="model.pt", team="RED")
action = controller.decide(rack_matrix, time_remaining=60.0)
# Returns: {"action": "PLACE", "row": 2, "col": 1, "confidence": 0.98}

• Metrics: JSON summaries of win rates are saved every 1,000 episodes in logs/.
• Episode Logs: Full textual replays of checkpoint episodes are dumped for strategy analysis.

---

Zone 1 — Weapon Assembly

Zone 1 requires R1 and R2 to collaboratively assemble a weapon (staff rod + spearhead) without the robots touching each other. One component is at the team's starting area, the other at the center of the arena (shared).

Status: Detection and assembly logic is planned (see R2_GSM_Refined.md and R2_FSM_Refined.md for the full state machine specification). Implementation is pending.

Planned approach:

• OpenCV + ML for component detection (staff = elongated contour, spearhead = pointed shape)
• Visual servoing for fine alignment during assembly
• Ultrasonic sensors for no-contact enforcement between robots
• ML-based assembly verification (geometric + classifier)

---

System Architecture (R2)

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PERCEPTION  │     │   DECISION   │     │  ACTUATION   │
│  (Jetson)    │────▶│   (Jetson)   │────▶│   (STM32)    │
│              │     │              │     │              │
│ Camera(s)    │     │ A* Planner   │     │ Motor PWM    │
│ OpenCV + ML  │     │ RL Model     │     │ Pneumatics   │
│ Encoders     │     │ State Mgr    │     │ Grippers     │
│ IMU          │     │              │     │ Elevator     │
│ IR/Ultrasonic│     │              │     │ Conveyor     │
└──────────────┘     └──────────────┘     └──────────────┘
        ▲                    │                    │
        └────────────────────┴────────────────────┘
                     UART Feedback Loop

Bus	Connection	Purpose
UART	Jetson ↔ STM32	Command packets + telemetry (binary, checksummed)
USB/CSI	Camera → Jetson	Video frames (640×480 @ 15-30 fps)
I2C	IMU → STM32	6-axis orientation at 100 Hz
GPIO/ADC	Sensors → STM32	Encoders, IR, limit switches, pressure
PWM/Relay	STM32 → Actuators	Motors, solenoid valves, servos

Full I/O specifications, serial protocol, sensor thresholds, and deployment checklists are documented in:

• R2_GSM_Refined.md — Global State Machine (high-level zone states)
• R2_FSM_Refined.md — Finite State Machine (sub-states, pseudocode, actuator tables)

---

Getting Started

Zone 3 RL Training

cd Zone3/RL
# Training with curriculum scheduler
python -m Zone3.RL.training.train --episodes 100000 --verbose

# Play against the trained AI
python -m Zone3.RL.viz.play_against_ai --checkpoint checkpoints/zone3_final.pt

Zone 2 Isaac Sim

Requires NVIDIA Isaac Sim (2023.1+).

1. Open Isaac Sim and load Zone2/Navigation/IsaacSimulation/isaac/AreanaLayout_2026.usd
2. Run scripts from Zone2/Navigation/IsaacSimulation/scripts/ within the Isaac Sim script editor

Zone 2 A* (Standalone)

python Zone2/Navigation/time_aware_hybrid_astar.py

R2 Deployment (Zone 1 & Zone 2)

# Setup (from Robocon26/ root)
python -m venv .venv
.venv\Scripts\Activate.ps1          # Windows PowerShell
pip install -r requirements.txt

# Hardware-free dry run: keep SIM=True in Deployment/common/config.py
python -m Deployment.zone1.zone1    # weapon assembly pipeline
python -m Deployment.zone2.zone2    # forest traversal + step climbing

# Unit / integration tests (all SIM, no hardware)
python -m pytest Deployment/tests -v

On the real robot: set SIM=False and SERIAL_PORT in Deployment/common/config.py, flash Deployment/firmware/esp32/r2_main, then run the same commands. See Deployment/README.md for the full layout, the serial protocol, and the per-zone config map.

Perception is pluggable (camera-ML / IR / manual) per zone — switch via PERCEPTION_SOURCE in the zone config; no logic changes needed.

---

Implementation Status

Component	Status	Notes
Zone 2 A* planner	✅ Complete	Neighboring pickup, discovery bonus, cost-based 3rd carry, exit-cell priority
R2 Deployment tree	✅ Rebuilt	Unified Deployment/ (common HAL + zone1 + zone2 + firmware + tests); 3 ESP32 boards (drive / sensor / manip) on 3 USB links + Jetson Orin Nano brain, logical-subsystem routing
Zone 2 deployment	✅ Reworked	A* bridge + NEW 2-piston step climber + pluggable grid perception; SIM-verified end-to-end
Zone 2 Isaac Sim integration	✅ Implemented	Step climbing + navigation + vision pipeline
Zone 2 MobileNetV3 KFS detection	✅ Implemented	Trained model, simulated camera inference
Zone 3 RL environment	✅ Overhauled	New discrete 10 action space with masking
Zone 3 PPO training	✅ Overhauled	Curriculum-based: Random -> Heuristic -> Self-Play
Zone 3 deployment inference	✅ Complete	Zone3Controller implemented for hardware integration
Zone 1 weapon assembly	✅ Pipeline built	SEARCH→ALIGN→PICK→TURN→PRESENT→WAIT→RELEASE→EXIT FSM; camera/IR perception toggle; SIM-verified
R2 GSM/FSM specification	✅ Complete	Full I/O, protocols, sensor tables
Real robot firmware integration	🔄 In progress	Sim → hardware transfer ongoing

---

Documentation

Document	Description
R2_GSM_Refined.md	Global State Machine — zone-level states, transitions, data flows
R2_FSM_Refined.md	Finite State Machine — 20+ sub-states, serial protocol, sensor/actuator tables
ABU Robocon 2026 Rulebook V.0.pdf	Official competition rulebook

---

GGs

ABU Robocon 2026 is a wrap. Thanks to everyone on Team Vulcans who put time into this stack — perception, navigation, RL, firmware, and everything in between. See you at the next one.

---

License

This project is licensed under the MIT License — see LICENSE for details.