# Getting Started

# Prerequistites

<p class="callout danger">MacOS installation steps were not tested, proceed at your own risk!</p>

### Rust

Install Rust via rustup — the official Rust toolchain installer.

**All platforms:**<span style="white-space: pre-wrap;"> go to </span>[https://rustup.rs](https://rustup.rs)<span style="white-space: pre-wrap;"> and follow the instructions, or run:</span>

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

After installation, restart your terminal and verify:

```bash
rustc --version
cargo --version
```

### Bun

<span style="white-space: pre-wrap;">Bun is the JavaScript runtime and package manager used for the frontend. </span>

<p class="callout warning"><span style="white-space: pre-wrap;">Using npm or yarn will </span>**not**<span style="white-space: pre-wrap;"> work with the current setup, there are scripts that specifically call for bun.</span></p>

**Linux / macOS:**

```bash
curl -fsSL https://bun.sh/install | bash
```

**Windows:**<span style="white-space: pre-wrap;"> download the installer from </span>[https://bun.sh](https://bun.sh)

Verify:

```bash
bun --version
```

### Tauri CLI prerequisites

Tauri requires some OS-level dependencies in addition to Rust.

**Linux (Ubuntu/Debian):**

```bash
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev \
  libayatana-appindicator3-dev librsvg2-dev patchelf
```

**Windows:**<span style="white-space: pre-wrap;"> install the </span>[Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)<span style="white-space: pre-wrap;"> and </span>[WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)<span style="white-space: pre-wrap;"> (usually already present on Windows 10/11).</span>

**macOS:**

```bash
xcode-select --install
```

### GStreamer

<span style="white-space: pre-wrap;">GStreamer handles video decoding and streaming. Version </span>**1.22.x**<span style="white-space: pre-wrap;"> is required to match the Rust crate versions (</span>`<span class="editor-theme-code">gstreamer = "0.22"</span>`<span style="white-space: pre-wrap;"> maps to GStreamer 1.22).</span>

**Linux (Ubuntu/Debian):**

```bash
sudo apt install \
  libgstreamer1.0-dev \
  libgstreamer-plugins-base1.0-dev \
  libgstreamer-plugins-bad1.0-dev \
  gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly \
  gstreamer1.0-libav \
  gstreamer1.0-tools
```

Verify:

```bash
gst-launch-1.0 --version
```

**Windows:**

1. <span style="white-space: pre-wrap;">Download the </span>**MSVC 64-bit**<span style="white-space: pre-wrap;"> installer for GStreamer 1.22.x from </span>[https://gstreamer.freedesktop.org/download/](https://gstreamer.freedesktop.org/download/)
2. <span style="white-space: pre-wrap;">Download both the </span>**runtime**<span style="white-space: pre-wrap;"> and </span>**development**<span style="white-space: pre-wrap;"> installers</span>
3. <span style="white-space: pre-wrap;">Install both to the default path: </span>`<span class="editor-theme-code">C:\gstreamer\1.0\msvc_x86_64\</span>`
4. Add the GStreamer bin directory to your system PATH:

```
C:\gstreamer\1.0\msvc_x86_64\bin
```

Verify in a new terminal:

```bash
gst-launch-1.0 --version
```

<p class="callout info"><span style="white-space: pre-wrap;">The </span>`<span class="editor-theme-code">GST_PLUGIN_PATH</span>`<span style="white-space: pre-wrap;"> environment variable is set automatically by the app at runtime (in </span>`<span class="editor-theme-code">lib.rs</span>`), so you do not need to set it manually.</p>

**macOS:**

```bash
brew install gstreamer gst-plugins-base gst-plugins-good \
  gst-plugins-bad gst-plugins-ugly gst-libav
```

---

# Cloning the Repository

<p class="callout warning">**Before**<span style="white-space: pre-wrap;"> cloning the repository, install the following tools on your machine.</span></p>

<span style="white-space: pre-wrap;">The repository contains a Git submodule for the protobuf definitions. You must clone with </span>`<span class="editor-theme-code">--recurse-submodules</span>`<span style="white-space: pre-wrap;"> or the </span>`<span class="editor-theme-code">src-tauri/proto/</span>`<span style="white-space: pre-wrap;"> directory will be empty and the build will fail.</span>

```bash
git clone --recurse-submodules https://github.com/RoboTeamTwente/erc-software-basestation.git
cd erc-software-basestation
```

If you already cloned without the flag, initialise the submodule manually:

```bash
git submodule update --init --recursive
```

### Keeping the submodule up to date

When pulling changes that include submodule updates, always run:

```bash
git pull
git submodule update --recursive
```

If the proto definitions change and your build starts failing with protobuf-related errors, this is almost always the cause.

## Installing Frontend Dependencies

```bash
bun install
```

<span style="white-space: pre-wrap;">This reads </span>`<span class="editor-theme-code">package.json</span>`<span style="white-space: pre-wrap;"> and installs all SvelteKit, Threlte, and other frontend dependencies into </span>`<span class="editor-theme-code">node_modules/</span>`<span style="white-space: pre-wrap;">. Run this once after cloning and again whenever </span>`<span class="editor-theme-code">package.json</span>`<span style="white-space: pre-wrap;"> changes.</span>

# Common Operations

## Running in Development

```bash
bun run tauri dev
```

This command does the following in parallel:

- <span style="white-space: pre-wrap;">Starts the Vite/SvelteKit dev server on </span>`<span class="editor-theme-code">http://localhost:1420</span>`
- Compiles the Rust backend (first run takes several minutes)
- Opens the Tauri application window

<span style="white-space: pre-wrap;">The frontend supports hot module replacement — changes to </span>`<span class="editor-theme-code">.svelte</span>`<span style="white-space: pre-wrap;"> and </span>`<span class="editor-theme-code">.ts</span>`<span style="white-space: pre-wrap;"> files appear immediately without restarting. Rust changes require a recompile, which Tauri handles automatically but takes longer.</span>

<p class="callout info">**First build warning:**<span style="white-space: pre-wrap;"> the initial </span>`<span class="editor-theme-code">cargo build</span>`<span style="white-space: pre-wrap;"> downloads and compiles all Rust dependencies including GStreamer bindings. This can take 5–15 minutes depending on your machine. Subsequent builds are fast due to incremental compilation.</span></p>

### Building for Production

<p class="callout danger">One of Tauri's dependencies, libc (the C standard library), is forward compatible but not backward compatible</p>

The demo laptop has an old verison of linux so you need to use docker to build the app if you want to use it in it.  
The first time you build you have to build docker first:

```bash
sudo docker build -t tauri-ubuntu2204 .
```

For building the app in linux the subsequent times for the demo laptop use the command:

```bash
sudo docker run --rm \
    -v $(pwd):/app \
    -v tauri-cargo-cache:/root/.cargo/registry \
    tauri-ubuntu2204
```

<p class="callout info">You don't have to docker build every time, just the first time and if you change anything in the dockerfile</p>

## Testing Without Rover Hardware

You do not need a physical rover to develop or test the UI. The backend includes a full simulator.

#### Video Feeds

**Fake camera**

`<span class="editor-theme-code">fake_camera_gstreamer/</span>`<span style="white-space: pre-wrap;"> — a GStreamer-based test source that sends H.264 RTP streams on the expected UDP ports (4500, 4501, 4502). It can be run from by running the following command from </span>`<span class="editor-theme-code">erc-software-basestation/fake_camera_gstreamer/</span>`

```bash
cargo run --bin fake_camera_gstreamer
```

**Stream from Webcam**

To test the video feed with your webcam open a terminal and use the following command.

Linux

```bash
gst-launch-1.0 v4l2src ! videoconvert ! x264enc tune=zerolatency bitrate=800 speed-preset=ultrafast ! rtph264pay ! udpsink host=127.0.0.1 port=4500
```

Windows

```bash
gst-launch-1.0 ksvideosrc ! videoconvert ! x264enc tune=zerolatency bitrate=800 speed-preset=ultrafast ! rtph264pay ! udpsink host=127.0.0.1 port=4500
```

#### Dummy data streams (rover telemetry)

<span style="white-space: pre-wrap;">Once the app is running, go to </span>`<span class="editor-theme-code">/settings</span>`<span style="white-space: pre-wrap;"> and use the simulator controls:</span>

- **Start dummy general stream**<span style="white-space: pre-wrap;"> — starts the full multi-stream simulator sending fake IMU, GPS, arm, drive, and sensor data to the app over UDP. Use this to test all telemetry UI at once.</span>
- **Start dummy IMU stream**<span style="white-space: pre-wrap;"> — starts an IMU-only stream with no jitter or packet loss. Use this for isolated IMU component testing.</span>
- **Stop dummy general/IMU stream**<span style="white-space: pre-wrap;"> — stops whichever simulator is running.</span>

The simulator runs inside the Rust backend so it works regardless of whether a rover is connected.

## Connecting to the Rover

<p class="callout danger">**TODO**</p>

The base station listens for incoming UDP packets on the address set on lib.rs, must set static address in laptop settings

# Common Issues

**Build fails with "No valid proto files found under components/"**<span style="white-space: pre-wrap;"> The proto submodule is not initialised. Run </span>`<span class="editor-theme-code">git submodule update --init --recursive</span>`.

**GStreamer errors at startup on Linux**<span style="white-space: pre-wrap;"> Verify the plugin path exists: </span>`<span class="editor-theme-code">/usr/lib/x86_64-linux-gnu/gstreamer-1.0</span>`<span style="white-space: pre-wrap;">. If your system uses a different architecture or distro the path in </span>`<span class="editor-theme-code">lib.rs</span>`<span style="white-space: pre-wrap;"> may need updating.</span>

**GStreamer errors at startup on Windows**<span style="white-space: pre-wrap;"> Verify GStreamer is installed to exactly </span>`<span class="editor-theme-code">C:\gstreamer\1.0\msvc_x86_64\</span>`<span style="white-space: pre-wrap;"> and that the </span>`<span class="editor-theme-code">bin</span>`<span style="white-space: pre-wrap;"> directory is in your PATH.</span>

**Video feeds show "SIGNAL LOST"**<span style="white-space: pre-wrap;"> No camera is sending data on the expected UDP ports. Start </span>`<span class="editor-theme-code">fake_camera_gstreamer</span>`<span style="white-space: pre-wrap;"> or connect the rover to get video.</span>

**White/blank window on launch**<span style="white-space: pre-wrap;"> The SvelteKit dev server may not have started yet. Wait a few seconds and the window should load. If it persists, check the terminal for Vite errors.</span>

**Model shows "Failed to load 3D model"**<span style="white-space: pre-wrap;"> In development, models are loaded from </span>`<span class="editor-theme-code">src-tauri/models/</span>`<span style="white-space: pre-wrap;">. Verify that </span>`<span class="editor-theme-code">chibiRover.glb</span>`<span style="white-space: pre-wrap;"> (or your model file) exists there. In production builds, run </span>`<span class="editor-theme-code">debug_resource_dir</span>`<span style="white-space: pre-wrap;"> from the Settings page to check where Tauri is looking.</span>

**"\[Error\] Unhandled Promise Rejection: ReferenceError: Cannot access uninitialized variable."** <span style="white-space: pre-wrap;">Seems like a circular import error, check the name of the files, some require odd names such as </span>`<span class="editor-theme-code">detected_objects.svelte.ts</span>`. If you remove the .svelte it will error out oddly.