A modular suite for hub management, telemetry, and a modern web GUI for Hyperloop team operations. This repository contains the cloud services, Raspberry Pi hub server, web client, and related utilities used to run, test, and develop the system.
Quick links
- Cloud API: cloud-services
- Hub agent & server: rpi-hub-server
- Browser UI: web-client
- Uplink manager (cellular hub): wifi-fallback-relay
Anyone is welcome to view the live GUI at: https://gui.cornellhyperloop.com/
Repository layout
cloud-services/— FastAPI backend for authentication, websockets, hub coordination, and telemetry storage.rpi-hub-server/— Edge service that runs on every Raspberry Pi hub (same code, per-Pi config profile): USB serial boards (Arduino Uno R3/R4, Mega, Nano, STM32F407G-DISC1), flashing, and the cloud uplink. Includes a simulated-board mode for development without hardware.web-client/— React + TypeScript single-page app (Vite) for live telemetry, device control, and charting.wifi-fallback-relay/— Uplink manager for the one hub with a cellular HAT: prefers Wi-Fi, falls back to cellular, and reports the active link.
The system is split into three primary tiers:
- Cloud / API: central FastAPI application exposing REST endpoints and WebSocket hubs for realtime telemetry and command routing.
- Edge / Hub: Raspberry Pi agent that manages local serial devices, performs device tasks, and streams telemetry back to the cloud.
- Client: A TypeScript React app (Vite) that connects to the cloud WebSocket endpoints for realtime dashboards and control.
A short video of the GUI being used to operate our team's minipod is attached here.
- Backend:
FastAPI(>=0.115.0) +uvicornfor ASGI serving. WebSocket hubs use thewebsocketspackage and integrate with Pydantic models for typed messages. - Auth: NetID allowlist plus one shared team password (bcrypt), JWT sessions, and a view-only mode; hubs authenticate with per-hub device tokens (see
cloud-services/src/auth/). - Data models:
pydantic/pydantic-settingsfor config and runtime validation. - Edge:
pyserialfor serial connections, arduino-cli and OpenOCD for flashing,psutilfor health metrics; components are wired inrpi-hub-server/src/runtime.py. - Contract:
cloud-services/contracts/openapi.json(REST + WebSocket messages) is generated from the cloud models; the web client's types are generated from it (npm run gen:types). - Frontend: React 19 + TypeScript, built with Vite; key libs include
rechartsfor charts andzustandfor state.
Prerequisites: Python 3.11+, Node 18+ (or matching versions used by your environment), Git.
Backend (example)
- Create and activate a Python virtual environment in
cloud-services:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt- Run the cloud API locally (development):
cd cloud-services
set ENV_FILE=.env.development
python -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000Frontend
cd web-client
npm install
npm run devEdge / RPi
- Install dependencies in a venv under
rpi-hub-server. - Without hardware:
HUB_PROFILE=dev-sim python -m src.mainruns simulated boards against a local cloud-services. - On a Pi: follow .claude/rpi-hub-setup.md (profiles
lab-hub/cellular-hub, systemd unit inrpi-hub-server/deploy/systemd/).
The web client also has a browser-only mock: npm run dev:mock in web-client.
- .claude/auth-setup.md: production login (NetID allowlist + team password), hub device tokens, rotation.
- .claude/rpi-hub-setup.md: setting up a Raspberry Pi hub, board checks, and the cellular hub's Wi-Fi/cellular failover.
- Python:
pytestandpytest-asyncioincloud-services/tests,rpi-hub-server/testsandwifi-fallback-relay/tests; CI runs all three. - Frontend: TypeScript type checks, ESLint, a production build, and a check that
src/types/api.gen.tsmatches the cloud contract.
Project visuals and diagrams used above live in res/readme/:
This project is licensed under the MIT License — see LICENSE.md for details.