System Architecture
The platform has two independent layers connected via WebSocket (ROSBridge on port 9090) and a latency API on port 8085.
Connection Modes
Every control page has a 3-mode selector. The frontend behavior changes, the backend is swapped.
Latency Measurement
Two measurement points: client round-trip (browser) and backend command-to-execute (ROS2 node).
ROS2 Topic Interface
The contract between frontend and backend — all communication goes through these topics.
Control Strategies
Four navigation algorithms available on the Auto Control page. Each computes linear and angular velocity from the error between robot pose and target.
PID Controller
Algorithm Comparison
Obstacle Avoidance Methods
Tunable Parameters
All parameters are adjustable in real-time via sliders on the Auto Control page. Changes take effect immediately.
Controller Gains
How aggressively the robot drives toward the target. Higher = faster approach but may overshoot.
How aggressively the robot turns to face the target. Higher = sharper turns.
Proportional gain — reacts to current error magnitude.
Integral gain — accumulates past errors to eliminate steady-state offset. Too high causes overshoot.
Derivative gain — predicts future error from rate of change. Dampens oscillation.
Clamps the integral accumulator to prevent windup when the robot is stuck.
How far ahead on the path the robot aims. Short = tight tracking but jittery. Long = smooth curves but cuts corners.
Speed gain — scales velocity with distance to lookahead point.
Distance threshold to consider the robot "arrived" at the target. Smaller = more precise but takes longer to settle.
Angle error threshold to switch from "turn in place" to "drive forward" phase.
Safety Zones
Avoidance Algorithm Behaviour
Each obstacle generates a repulsive force inversely proportional to distance². Forces are summed to create a "push" vector that blends with the desired velocity. Smooth and reactive but can get stuck in local minima between two equal obstacles.
Evaluates velocity candidates within the robot's acceleration limits. Scores each by clearance (distance to nearest obstacle), heading (alignment to goal), and speed. Picks the best-scoring velocity. Good for tight spaces.
Builds a polar histogram of obstacle density around the robot. Finds the widest gap (lowest density sector) and steers toward it. Reliable in cluttered environments with many small obstacles.
Simplest method — halts the robot completely when any obstacle enters the critical zone. Reduces speed in the warning zone. No path re-planning. Use as a safety fallback layer.
Speed Presets
| Preset | Linear (m/s) | Angular (rad/s) | Use Case |
|---|---|---|---|
| Slow | 0.3 | 1.0 | Tight spaces, precision navigation |
| Normal | 1.0 | 2.0 | General purpose |
| Fast | 2.5 | 3.5 | Open areas, quick traversal |
Pages
/manualJoystick + keyboard teleoperation with live latency HUD. Speed/turn sliders with presets, dead zone, emergency stop.
/controlAutonomous navigation with 4 controllers (P, PID, Pure Pursuit, State Machine), 4 avoidance methods, environment density toggle (Clear/Scarce/Medium/Dense), live performance charts, real-time parameter tuning.
/slam-navigationOccupancy grid mapping with SLAM Toolbox, Cartographer, or client-side simulation. Auto-explore, manual control, map export.
/figure-eight-navFigure-eight lemniscate path with pure pursuit controller. Cross-track error, lap counting, data export.
/latencyCommand-to-execution timing from backend API. Shows avg, P95, jitter, std dev, min/max. CSV export.
/analyticsAggregated performance data from control runs. Singleton state persists across pages. CSV/JSON export.
/material-handlingWarehouse pick-and-place simulation with shelves, zones, task queue, gripper control.
/ros2-testROSBridge connection test, topic subscribe/publish, live telemetry (odom + scan), quick velocity commands with feedback.
/guideArchitecture diagrams, control strategy block diagrams, parameter reference, safety zones, deployment guides.
Deployment
cd frontend && pnpm devpnpm build && node .output/server/index.mjscd backend && ./start.sh startsudo ./install.sh systemdsudo ./install.sh systemd --hardwaredocker compose up --buildTest Suite
cd frontend && pnpm test:run169 tests · ~3s