Skip to content

Installation Guide

Jump to bottom
Marc Sanchis edited this page Jun 5, 2025 · 1 revision

Installation Guide

Complete step-by-step installation guide for the Hyperloop UPV Control Station across all supported platforms.

🎯 Overview

This guide provides detailed installation instructions for:

  • Production deployments - Ready-to-run releases
  • Development environments - Full source code setup
  • Testing setups - Simulation and validation environments

🚀 Quick Installation (Recommended)

For Operators (Production Use)

  1. Download Latest Release

    • Visit GitHub Releases
    • Download the package for your operating system:
      • windows-vX.X.X.zip - Windows systems
      • linux-vX.X.X.zip - Linux systems
      • macos-intel-vX.X.X.zip - Intel Mac systems
      • macos-arm64-vX.X.X.zip - Apple Silicon Mac systems

  2. Extract and Run

    # Extract the package
unzip [downloaded-package].zip
cd [extracted-folder]

# Run the control station
./backend &                    # Start backend
open ethernet-view/index.html  # Open ethernet view
open control-station/index.html # Open control station

For Developers (Source Code)

See Quick Start Guide for the fastest development setup.

📋 System Requirements

Minimum Requirements

Component Specification
CPU Dual-core 2.0 GHz
Memory 4 GB RAM
Storage 2 GB available space
Network Ethernet adapter
OS Windows 10+, macOS 10.15+, Ubuntu 18.04+

Recommended Requirements

Component Specification
CPU Quad-core 3.0 GHz
Memory 8 GB RAM
Storage 10 GB available space (SSD preferred)
Network Gigabit Ethernet
OS Windows 11, macOS 12+, Ubuntu 22.04+

Special Requirements

For Development

  • Go 1.21+ - Backend development
  • Node.js 18+ - Frontend development
  • Git - Version control

For Network Operations

  • libpcap - Packet capture (Linux/macOS)
  • WinPcap/Npcap - Packet capture (Windows)
  • Administrative privileges - For network interface access

🖥️ Platform-Specific Installation

Windows Installation

Method 1: Using Releases (Recommended)

# Download and extract release
Invoke-WebRequest -Uri "https://github.com/HyperloopUPV-H8/software/releases/latest/download/windows-latest.zip" -OutFile "hyperloop-control.zip"
Expand-Archive -Path "hyperloop-control.zip" -DestinationPath "C:\HyperloopUPV"

# Run the application
cd "C:\HyperloopUPV"
.\backend.exe

Method 2: From Source

# Install prerequisites
# - Install Go from https://golang.org/doc/install
# - Install Node.js from https://nodejs.org/
# - Install Git from https://git-scm.com/

# Clone and setup
git clone https://github.com/HyperloopUPV-H8/software.git
cd software

# Enable script execution
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Setup and run
.\scripts\dev.ps1 setup
.\scripts\dev.ps1 all

Windows-Specific Setup

  1. Install Npcap (for packet capture):

    • Download from npcap.com
    • Install with "Install in WinPcap API-compatible Mode"

  2. Firewall Configuration:

    # Allow backend through Windows Firewall
New-NetFirewallRule -DisplayName "Hyperloop Backend" -Direction Inbound -Port 8080 -Protocol TCP -Action Allow

  3. Network Adapter Setup:

    • Set static IP: 192.168.0.9/24
    • Configure in Network Settings > Change adapter options

macOS Installation

Method 1: Using Releases (Recommended)

# Download and extract release
curl -L https://github.com/HyperloopUPV-H8/software/releases/latest/download/macos-latest.zip -o hyperloop-control.zip
unzip hyperloop-control.zip
cd hyperloop-control

# Run the application
./backend

Method 2: Using Homebrew and Source

# Install prerequisites
brew install go node git libpcap

# Clone and setup
git clone https://github.com/HyperloopUPV-H8/software.git
cd software

# Setup and run
chmod +x scripts/dev.sh
./scripts/dev.sh setup
./scripts/dev.sh all

macOS-Specific Setup

  1. Grant Network Permissions:

    # Backend needs sudo for packet capture
sudo ./backend
# Or run with limited privileges (recommended)

  2. Network Configuration:

    # Set static IP
sudo networksetup -setmanual "Ethernet" 192.168.0.9 255.255.255.0 192.168.0.1

Linux Installation (Ubuntu/Debian)

Method 1: Using Releases (Recommended)

# Download and extract release
wget https://github.com/HyperloopUPV-H8/software/releases/latest/download/linux-latest.zip
unzip linux-latest.zip
cd linux-control

# Run the application
./backend

Method 2: From Source

# Install prerequisites
sudo apt update
sudo apt install -y golang-go nodejs npm git libpcap-dev

# Clone and setup
git clone https://github.com/HyperloopUPV-H8/software.git
cd software

# Setup and run
chmod +x scripts/dev.sh
./scripts/dev.sh setup
./scripts/dev.sh all

Linux-Specific Setup

  1. Network Capabilities:

    # Grant network capabilities to backend (avoid running as root)
sudo setcap cap_net_raw,cap_net_admin=eip ./backend

  2. Static IP Configuration:

    # Using netplan (Ubuntu 18.04+)
sudo nano /etc/netplan/01-network-manager-all.yaml

# Add configuration:
network:
  version: 2
  ethernets:
    enp0s3:  # Replace with your interface
      dhcp4: false
      addresses:
        - 192.168.0.9/24
      gateway4: 192.168.0.1
      nameservers:
        addresses: [8.8.8.8, 8.8.4.4]

# Apply configuration
sudo netplan apply

🐳 Docker Installation

Using Docker Compose (Recommended)

# docker-compose.yml
version: '3.8'

services:
  backend:
    image: hyperloop-upv/control-station-backend:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    network_mode: host  # Required for packet capture
    cap_add:
      - NET_RAW
      - NET_ADMIN

  frontend:
    image: hyperloop-upv/control-station-frontend:latest
    ports:
      - "5173:5173"
      - "5174:5174"
    depends_on:
      - backend
# Run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Manual Docker Installation

# Pull images
docker pull hyperloop-upv/control-station-backend:latest
docker pull hyperloop-upv/control-station-frontend:latest

# Run backend
docker run -d \
  --name hyperloop-backend \
  --network host \
  --cap-add NET_RAW \
  --cap-add NET_ADMIN \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/logs:/app/logs \
  hyperloop-upv/control-station-backend:latest

# Run frontend
docker run -d \
  --name hyperloop-frontend \
  -p 5173:5173 \
  -p 5174:5174 \
  hyperloop-upv/control-station-frontend:latest

⚙️ Configuration Setup

1. Backend Configuration

Create or edit config.toml:

[network]
# Your machine's IP address (must match ADJ specification)
backend_ip = "192.168.0.9"
backend_port = 8080

# Enable network propagation of faults
[transport]
propagate_fault = true

# Enable specific boards
[vehicle.boards]
VCU = true    # Vehicle Control Unit
PCU = true    # Propulsion Control Unit  
TCU = true    # Thermal Control Unit
LCU = true    # Levitation Control Unit
BCU = true    # Brake Control Unit
BLCU = true   # Boot Loader Control Unit

# ADJ (board specification) configuration
[adj]
# Git branch to use for board specifications
# Leave blank to use local ADJ files
branch = "main"

# Automatically update ADJ from git
auto_update = true

# Test mode (use mock data)
test = false

# HTTP server configurations
[server.control-station]
addr = "0.0.0.0:8080"
endpoints.pod_data = "/api/pod-data"
endpoints.order_data = "/api/order-data"
endpoints.connections = "/ws"
endpoints.files = "/static"
static_path = "../control-station/dist"

[server.ethernet-view]
addr = "0.0.0.0:8081"
endpoints.pod_data = "/api/pod-data"
endpoints.order_data = "/api/order-data" 
endpoints.connections = "/ws"
endpoints.files = "/static"
static_path = "../ethernet-view/dist"

2. Network Configuration

IP Address Setup

Your computer must be configured with the IP address specified in the ADJ (typically 192.168.0.9):

Windows:

  1. Open Network & Internet Settings
  2. Change adapter options
  3. Right-click Ethernet adapter → Properties
  4. Select Internet Protocol Version 4 (TCP/IPv4)
  5. Set static IP: 192.168.0.9, Subnet: 255.255.255.0

macOS:

sudo networksetup -setmanual "Ethernet" 192.168.0.9 255.255.255.0 192.168.0.1

Linux:

# Using nmcli
sudo nmcli con mod "Wired connection 1" ipv4.addresses 192.168.0.9/24
sudo nmcli con mod "Wired connection 1" ipv4.gateway 192.168.0.1
sudo nmcli con mod "Wired connection 1" ipv4.method manual
sudo nmcli con up "Wired connection 1"

3. ADJ Board Specifications

The ADJ system defines board configurations. Key files:

  • adj/boards/[BOARD_NAME]/board.json - Board definition
  • adj/boards/[BOARD_NAME]/packets/ - Packet specifications
  • adj/boards/[BOARD_NAME]/orders/ - Command definitions

Example board configuration:

{
  "name": "VCU",
  "id": 1,
  "address": "192.168.1.101",
  "packets": [
    {
      "id": 256,
      "name": "speed_data",
      "measurements": ["speed", "acceleration"]
    }
  ],
  "orders": [
    {
      "id": 512, 
      "name": "emergency_brake",
      "fields": ["brake_force"]
    }
  ]
}

✅ Verification and Testing

1. System Health Check

# Check backend status
curl -s http://localhost:8080/health || echo "Backend not responding"

# Check frontend accessibility
curl -s http://localhost:5173 > /dev/null && echo "Control Station accessible" || echo "Control Station not accessible"
curl -s http://localhost:5174 > /dev/null && echo "Ethernet View accessible" || echo "Ethernet View not accessible"

# Check network connectivity
ping -c 1 192.168.1.101 && echo "Vehicle network reachable" || echo "Vehicle network unreachable"

2. Interface Verification

Open these URLs in your browser:

3. Network Interface Check

# Verify network interface configuration
ip addr show  # Linux
ifconfig      # macOS
ipconfig /all # Windows

# Test packet capture (requires admin/root)
tcpdump -i eth0 -c 5  # Linux/macOS

🚨 Troubleshooting Installation

Common Issues

Backend Won't Start

# Check if ports are in use
netstat -an | grep -E ':8080|:5173|:5174'

# Check Go installation
go version

# Check for missing dependencies
ldd ./backend  # Linux
otool -L ./backend  # macOS

Frontend Build Failures

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version
node --version  # Should be 18+

Network Interface Issues

# Linux: Check interface names
ip link show

# Check if libpcap is installed
ldconfig -p | grep pcap  # Linux
brew list libpcap        # macOS

Permission Errors

# Linux: Grant network capabilities
sudo setcap cap_net_raw,cap_net_admin=eip ./backend

# macOS: Run with sudo (not recommended for production)
sudo ./backend

# Windows: Run as Administrator

Advanced Troubleshooting

Debug Mode

# Enable debug logging
DEVELOPMENT=true LOG_LEVEL=debug ./backend

# Check logs
tail -f logs/backend.log

Network Diagnostics

# Test TFTP connectivity (BLCU operations)
telnet 192.168.1.101 69

# Monitor network traffic
tcpdump -i eth0 -n host 192.168.1.101

🔧 Advanced Installation Options

Custom Build from Source

# Clone repository
git clone https://github.com/HyperloopUPV-H8/software.git
cd software

# Build backend
cd backend
go mod tidy
go build -o backend cmd/main.go cmd/config.go cmd/pid.go cmd/trace.go

# Build frontend
cd ../common-front
npm install && npm run build

cd ../control-station  
npm install && npm run build

cd ../ethernet-view
npm install && npm run build

Cross-Compilation

# Build for different platforms
GOOS=windows GOARCH=amd64 go build -o backend-windows.exe cmd/main.go
GOOS=linux GOARCH=amd64 go build -o backend-linux cmd/main.go
GOOS=darwin GOARCH=amd64 go build -o backend-macos cmd/main.go
GOOS=darwin GOARCH=arm64 go build -o backend-macos-m1 cmd/main.go

Service Installation

Linux Systemd Service

# Create service file
sudo nano /etc/systemd/system/hyperloop-backend.service

[Unit]
Description=Hyperloop UPV Backend
After=network.target

[Service]
Type=simple
User=hyperloop
WorkingDirectory=/opt/hyperloop
ExecStart=/opt/hyperloop/backend
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable hyperloop-backend
sudo systemctl start hyperloop-backend

Windows Service

# Using NSSM (Non-Sucking Service Manager)
nssm install "Hyperloop Backend" "C:\HyperloopUPV\backend.exe"
nssm set "Hyperloop Backend" AppDirectory "C:\HyperloopUPV"
nssm start "Hyperloop Backend"

🔗 Next Steps

After successful installation:

  1. First-Time Setup - Complete initial configuration
  2. Configuration Guide - Advanced configuration options
  3. Operator Manual - Learn to operate the system
  4. System Architecture - Understand the system design

🎉 Installation Complete!

Your Hyperloop UPV Control Station is now ready for operation. For additional help, check the Common Issues page or contact support through GitHub Issues.

Clone this wiki locally