🤖 Robotics Fleet Control MVP

A production-ready platform for college robotics teams to manage, monitor, and remotely deploy programs to robot fleets.

Built with Node.js, React, Python, PostgreSQL, and Redis - runs on Raspberry Pi hardware or in simulation mode.

---

Why This Platform

College robotics teams currently rely on ad-hoc methods (SSH, USB drives, manual logging) to manage their robots. Fleet Control provides:

• One dashboard for all robots across multiple teams
• Remote deploy - upload a .py program and push it to any robot in seconds
• Live telemetry - battery, status, sensor data via WebSocket
• Experiment records - timestamped runs, exit codes, stdout/stderr
• Simulation mode - develop and test without physical hardware

Features

• ✅ JWT auth with refresh tokens (in-memory token storage, not localStorage)
• ✅ Robot registration & heartbeat (REST + WebSocket)
• ✅ Dashboard with real-time robot status
• ✅ Remote deploy: upload .py → select robots → deploy
• ✅ Python agent (Raspberry Pi + simulation mode)
• ✅ Live log viewer via WebSocket
• ✅ Remote commands: Restart, Stop, Calibrate
• ✅ Experiment records with exit codes and outcomes
• ✅ Rate limiting, input validation, sandboxed execution

Tech Stack

Layer	Technology
Frontend	React 18, Vite, Tailwind CSS
Backend	Node.js 20, TypeScript, Express
Real-time	socket.io (WebSocket + polling fallback)
Database	PostgreSQL 16 + Prisma ORM
Cache/Queue	Redis 7
Auth	JWT access tokens + refresh tokens
Agent	Python 3.11 (asyncio, stdlib only)
Container	Docker + docker-compose
CI/CD	GitHub Actions

Quick Start (Dashboard Orchestrator)

The easiest way to self-host the central dashboard is using Docker.

# Download the orchestrator configuration
wget https://github.com/Seramicx/Robotics-Fleet-Control-MVP/releases/latest/download/docker-compose-production.yml -O docker-compose.yml

# Check configuration inside the file, then boot the dashboard!
docker compose up -d

Services will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000
• Demo login: demo@team.test / demopass123

Install Agent on Raspberry Pi

No need to clone the entire repository. Just download the lightweight agent.

# On your Raspberry Pi, download the latest agent release
wget https://github.com/Seramicx/Robotics-Fleet-Control-MVP/releases/latest/download/fleet-agent-v1.0.0.zip
unzip fleet-agent-v1.0.0.zip -d fleet-agent && cd fleet-agent

# Install dependencies
pip3 install -r requirements.txt

# Create your configuration file
cp agent_config.yaml my_config.yaml
# (Open my_config.yaml and set your server_url, robot_id, and auth_token)

# Run manually (hardware mode)
python3 robot_agent.py --config my_config.yaml

# Run as background service on startup
sudo cp robot_agent.service /etc/systemd/system/
sudo systemctl enable robot_agent
sudo systemctl start robot_agent

Running Tests

# Backend tests
cd tests && npm ci && npm test

# Agent tests
pip install -r agent/requirements.txt pytest
pytest agent/tests/ -v

# All via Makefile
make test

Adding a Pilot Team

1. Register via POST /api/auth/register or the /login UI → "Don't have an account? Register"
2. Run the agent on team hardware with their robot_id and auth_token
3. Robots appear in dashboard automatically on first heartbeat

License

Apache 2.0 - see LICENSE