Skip to main content

TuTr Hyperloop System Overview

šŸ“Œ What is this for? (Quick Summary)ā€‹

In Simple Words:
We built an autonomous hyperloop cargo pod to transport shipping containers along a 600-meter track at speeds up to 60 km/h.

This documentation explains how the whole system works:

  1. On the Pod: Sensors measure battery voltage, motor temperatures, and speed, and dual cameras record live video.
  2. On the Raspberry Pi: A small computer on the pod reads these sensors and sends the numbers to the cloud every second.
  3. In the Cloud (AWS): Cloud servers store the sensor history and let operators securely send commands (like Enable Battery, Launch, or Emergency Stop).
  4. On Your Laptop Screen: Web dashboards (both a simple 2D view and an interactive 3D simulation) let operators monitor the pod and watch live video in real time.

1. Executive Summaryā€‹

This handbook is designed to help any incoming software or systems engineer understand the entire TuTr Hyperloop codebase quickly.

Whether you need to fix a camera bug, update a safety limit, or add a new gauge to the web dashboard, this guide gives you the full picture without unnecessary buzzwords.

flowchart TD
    subgraph PodHardware["1. On-Board Pod Hardware"]
        Sensors["Vehicle Sensors\nā€¢ Speed & Acceleration\nā€¢ Battery Voltage & Temps\nā€¢ Inverter & Motor Temps"]
        IPCam["Dual IP Cameras\nā€¢ CAM 1: Forward Track View\nā€¢ CAM 2: Rear View"]
    end

    subgraph EdgeRPi["2. Raspberry Pi 5 Gateway (On the Pod)"]
        GoServer["Go Gateway Server (:20006)\nReads sensor bytes & sends to cloud"]
        Emulator["Trajectory Simulator\nReplays 600m test runs if no real pod"]
        Streamer["Camera Streamer\nSends camera video with low delay"]
    end

    subgraph CloudInfra["3. Cloud Servers (AWS Mumbai)"]
        IoTCore["AWS IoT Core\nReceives Start/Stop commands"]
        InfluxDB["InfluxDB Cloud\nStores all historical sensor charts"]
        Cognito["AWS Cognito\nHandles secure user login"]
        APIGateway["AWS API Gateway + Lambda\nConnects the website to the databases"]
        MediaMTX["MediaMTX Video Server\nStreams video directly to web browsers"]
        DynamoDB["DynamoDB\nSaves run logs & active login sessions"]
    end

    subgraph ClientDashboards["4. Web Dashboards (In Your Browser)"]
        Dash2D["2D Operations Dashboard (dashboard.tutr.tech)\nClean dials, safety buttons, voice alarms"]
        Twin3D["3D Simulation Dashboard\nInteractive 3D track, pod model & camera window"]
    end

    Sensors -->|CAN Bus wires| GoServer
    Emulator -.->|Simulated numbers| GoServer
    IPCam -->|Ethernet cables| Streamer
    Streamer -->|RTSP Video| MediaMTX

    GoServer -->|Internet| IoTCore
    GoServer -->|Internet| InfluxDB

    MediaMTX -->|WebRTC Video| Dash2D
    MediaMTX -->|WebRTC Video| Twin3D

    Cognito -->|Login Token| APIGateway
    APIGateway --> InfluxDB
    APIGateway --> DynamoDB
    APIGateway --> IoTCore

    Dash2D <-->|Fetch stats & send commands| APIGateway
    Twin3D <-->|Fetch stats & send commands| APIGateway

2. Where Does the Code Live? (Repository Map)ā€‹

Everything in our workspace is organized into three clean folders:

Folder PathWhat It Does & Technologies Used
Client Dashboard/ThreeJsForDemoPurpose3D Simulation Dashboard: An interactive 3D view of the 600m track where the pod glides smoothly based on real sensor numbers. Built with React, Three.js, and WebRTC live camera video.
Client Dashboard/Dashboard2D Operations Dashboard: The main control panel deployed at https://dashboard.tutr.tech. Has live dials, audio alerts that speak warnings out loud, safety buttons, and 33 automated tests.
Edge Device/RPi-PackageEdge Device Software: The code that runs on the Raspberry Pi inside the pod. Written in Go (for high speed) and Python (for camera streaming and simulation). Includes 23 automated tests.
TuTrDocs-mainThis Documentation Site: Built with Docusaurus and protected by our engineering login (tutr / Tutr@tech1).

3. The 4 Main Parts of the Systemā€‹

3.1 The Raspberry Pi on the Pod (RPi-Package)ā€‹

  • go_server: A fast Go program listening on port 20006. It receives binary sensor packets from the pod's CAN bus, decodes them, and uploads them to the cloud.
  • emulator: When testing on your laptop or in the lab without the real hyperloop track, this Python script replays a real 126-second, 600-meter test run at speeds up to 60 km/h.
  • stream_service: Takes the camera video, optimizes it so it doesn't freeze, and sends it to our cloud video server. If a camera is unplugged, it automatically shows a colorful test pattern so you know the stream is still alive.

3.2 The Cloud Backend (AWS)ā€‹

  • API Gateway (npig3gpgck) & Lambda: A single URL (POST https://npig3gpgck.execute-api.ap-south-1.amazonaws.com/api) handles all requests from the web dashboards.
  • Cognito Login: Secure user accounts with 3 permission levels:
    • Admin & Engineer: Allowed to turn on the high-voltage battery and click Launch.
    • Manager: Read-only access (can watch live numbers and video, but cannot press physical buttons).
  • The "Bouncer" Rule: If an operator logs in on their laptop, and someone else opens the dashboard with the same account on a tablet, the older tab is automatically logged out to prevent two people from pressing conflicting buttons.

3.3 The Live Video Server (MediaMTX)ā€‹

  • Hosted at cam.tutr.tech. It takes raw RTSP video from the pod and turns it into WebRTC, the same ultra-fast video protocol used by Google Meet and Zoom. This keeps video latency under 1 second so operators can see what is happening immediately.

3.4 The Web Dashboardsā€‹

  • Closed-Loop Safety: When an operator clicks Enable Battery, the system doesn't just assume it worked. It waits for the voltage sensor to physically read above 48 Volts before enabling the Launch button.
  • Automatic Thermal Shutdown: If the battery hits 80Ā°C or the motor inverter hits 90Ā°C, the screen flashes yellow and speaks a voice warning. If either hits 100Ā°C, the system cuts power immediately and locks the controls for 1 hour to protect the equipment.
  • Smooth 3D Motion: The 3D view uses mathematical smoothing (Hermite spline) so the 3D pod model moves like butter at 60 FPS even if the cloud numbers only arrive once a second.

4. Suggested Reading Orderā€‹

If you are new to the team, read the docs in this order:

  1. End-to-End Architecture: Understand how data flows from track to cloud.
  2. Edge Device & Raspberry Pi: Learn what runs on the vehicle itself.
  3. API Reference: See how the frontend asks the cloud for live stats.
  4. Client Dashboards: Explore the 2D panel and the 3D visualizer.
  5. Troubleshooting & Past Incidents: Learn the hard-won lessons from real bugs we solved.