# Songbird simulator box — setup and update

This guide covers everything for a Songbird hardware-in-the-loop simulator box, from a
blank SD card to a running simulator, and the later updates. You need a Windows PC and
about 30 minutes, most of which is waiting.

The box is a Raspberry Pi running the real PX4 flight stack against a flight-mechanics
model of the Songbird. A ground control station connects to it exactly as it would to an
aircraft, which is what makes it useful for training, for GCS work and for testing
without flying.

Everything you download comes from `https://pub.germandrones.com/simulator/`.

**Contents**

1. [What you need](#1-what-you-need)
2. [Write the SD card](#2-write-the-sd-card)
3. [Get the installer](#3-get-the-installer)
4. [Run the installer](#4-run-the-installer)
5. [Check that it works](#5-check-that-it-works)
6. [Using the box](#6-using-the-box)
7. [Updating the box](#7-updating-the-box)
8. [If something is wrong](#8-if-something-is-wrong)
9. [Reference](#9-reference)

---

## 1. What you need

| | |
|---|---|
| Raspberry Pi | **4 Model B, 2 GB or more**. A Pi 3 will not work: the software is 64-bit. |
| Power supply | The **official 3 A USB-C** supply. An underpowered supply causes faults that look like software problems — see [section 8](#8-if-something-is-wrong). |
| SD card | 16 GB or more, class 10 / A1 or better. |
| Network | The box needs internet access during setup, and must be reachable from your PC afterwards. See the three ways below. |
| PC | Windows 10 or 11, with a way to read the SD card. |

You do **not** need a monitor, keyboard or mouse. The box is set up entirely over the
network.

The box can connect in three ways. Decide which one before you start:

| | Internet for the setup comes from | Administrator rights on your PC |
|---|---|---|
| **WiFi** | the WiFi | not needed |
| **Cable to a local network with DHCP** (a router, an office network) | that network | not needed |
| **Cable directly to your PC** | the WiFi of the box, or through your PC if it has none | usually needed, see [section 4](#4-run-the-installer) |

## 2. Write the SD card

Install the **Raspberry Pi Imager** from <https://www.raspberrypi.com/software/> and
start it. It leads you through its steps one at a time.

**Device:** Raspberry Pi 4.

**OS:** `Raspberry Pi OS (other)` → **`Raspberry Pi OS Lite (64-bit)`**.

Both words matter:

- **64-bit**, because the simulator binaries are 64-bit and will not run on the 32-bit
  image. The installer checks this and stops rather than half-installing.
- **Lite**, because the box has no monitor. The desktop version wastes memory and CPU
  the simulator needs. The installer warns you if it finds the desktop version.

**Storage:** your SD card. Check the size shown — the card is erased completely.

Then fill in the customisation steps. Do not skip them: without them the box has no way
to log in, and you would need a monitor and keyboard.

| Step | Value |
|---|---|
| Hostname | `SB1SIM01` — the naming scheme is `SB<model>SIM<number>`, so box 2 of model 1 is `SB1SIM02`. Use the name you were given. |
| Localisation | Your time zone and keyboard layout. |
| User | Username **`pi`**, password **`pi`**. |
| Wi-Fi | Your WiFi name and password, if the box will use WiFi or has no other way to the internet. Otherwise skip it. |
| Remote access | **Enable SSH**, with **Use password authentication**. |

Then write the card. Writing and verifying takes a few minutes.

**When the Imager has finished, Windows normally shows the card again.** If it does not, take
the card out and put it back in. If Windows says the card cannot be read, or offers to format
it, do not format it: write it again with the Imager.

## 3. Get the installer

Download the installer to a folder you can find again, for example `Downloads`:

<https://pub.germandrones.com/simulator/install64.ps1>

Your browser may warn about the file; keep it. Then open **PowerShell** and go to that
folder:

```
cd $env:USERPROFILE\Downloads
```

## 4. Run the installer

```
powershell -ExecutionPolicy Bypass -File .\install64.ps1
```

`-ExecutionPolicy Bypass` applies to this one command only and changes nothing on your PC
permanently. Without it, Windows refuses a script that came from the internet.

First it asks where to get the simulator and the PX4 firmware. It shows an address for each:
press Enter to use it, or type another if you were given one. It downloads and checks both
right away, so a wrong address shows now. The address can be that of a package or of the
folder holding it, the same as on the **Upgrade** tab of the web page later.

Then it finds the card and reads what you told the Imager from it: the name of the box, the user,
the WiFi and the time zone, so you do not have to type them. It shows them and asks you to
confirm. It warns you if something will not work, such as SSH that is switched off, or a card
that has already been started in a box.

Every box ends up with the same network setup:

- **WiFi**, if it is on the card: the WiFi network gives it an address, and it is reachable by
  name.
- **Ethernet with DHCP**, alongside the WiFi or without it: a DHCP server gives it an address,
  and it is reachable by name there as well.
- **A fixed address on Ethernet**, always, as the last resort: it can be reached at that
  address over a cable with no DHCP at all.

So a box can move between these without being set up again.

The installer asks one question about this:

```
Is it connected by a cable directly to this PC? (y/N, or q to stop)
```

Then it asks for the **fixed address**. It proposes one, ending in `.98`, after trying it to
see that nothing answers there; if something does, it proposes the next one.

**If the answer is no**, press Enter if you have no preference: `192.168.0.98`. The box is
found by its name. The try can only see devices on a network your PC is on. If the network the
box goes on is itself `192.168.0.x`, ask whoever runs it which address is free: two devices
with one address disturb each other.

**If the answer is yes**, nothing on that cable hands out addresses, so your PC has to be in the
same network as the box:

- **If your PC's Ethernet adapter has a fixed address**, the box has to be in that network.
  The installer shows the address and proposes one that fits. Press Enter to accept it, or
  type another.
- **If it has none**, you have no preference to respect: press Enter to accept
  `192.168.0.98`. Your PC gets `192.168.0.10` on that adapter. If your PC is already in that
  network some other way, the installer proposes a different one.

There is one more thing with a direct cable: if there is no WiFi on the card, the box gets its
internet through your PC.

Setting an address on your PC and sharing its internet both need **administrator rights**:
Windows asks you to allow it. Without those rights a cable directly to your PC is not
possible, unless your adapter already has a fixed address and the card has WiFi. The
installer says so, and then the way left is WiFi or a cable to a network with DHCP. It lists
at the end what it changed on your PC.

Then it prepares the card and tells you what to do:

1. Remove the card safely, from the icon at the right of the taskbar.
2. Put it in the box, and connect the network cable if you use one.
3. Plug in the power, and press Enter on the PC. There is no on/off switch.

The first start takes a few minutes. The installer waits until the box answers.

Now the box asks for its **password**, once or twice: first to log in, and then a request
starting with `[sudo]`. It is `pi` both times, and then never again. The box asks for it
itself, so it never appears in your command line or in any file. It uses them to set up:

- **An SSH key**, so your PC can reach the box without a password from now on. The key is
  created on your PC if you do not already have one.
- **Passwordless `sudo` on the box**, for the user `pi`. The installation itself runs a
  long list of administrative commands over a connection that has no terminal, so there
  is nowhere for `sudo` to ask for a password — without this the install stops at the
  first command.

  Be aware of what this means: with the password `pi`, anyone on the same network can log
  in to the box and has full control of it. That is the normal trade for a lab tool on a
  trusted network, and it is the same arrangement every one of these boxes uses. Keep the
  box off untrusted networks.

After that it copies the simulator and the firmware to the box and installs them. Expect five to ten minutes
— installing the Python packages is the slow part. It then waits 35 seconds and reports
the state of every service.

If it stops half-way, finish the job on the running box. Use its name or address:

```
powershell -ExecutionPolicy Bypass -File .\install64.ps1 -Box SB1SIM01
```

That is safe to run at any time. It repairs an installation rather than duplicating it, so
if anything looks wrong, running it again is a reasonable first move.

## 5. Check that it works

The installer finishes with a list like this:

```
    sim_px4          active     restarts=0
    sim_songbird     active     restarts=0
    sim_gimbal       active     restarts=0
    gimbal-control   active     restarts=0
    telemetry        active     restarts=0
    sim_failures     active     restarts=0
    web UI           200
```

Every line should say **`active`** with **`restarts=0`**, and the web UI **200**.

`restarts=0` matters as much as `active`. A service that is failing and being restarted
over and over still says `active` the instant you look at it; the restart count is what
gives it away. This is why the installer waits before checking.

Then, from your PC:

- Open **`http://SB1SIM01/`** in a browser, or the address if you chose a cable directly
  to your PC; the installer shows which at the end. You should get the settings page, with
  the German Drones logo, a **Home Position** list and **Wind Settings**.
- Connect your GCS to **UDP port 14550** on the box. It should connect and show the
  aircraft, disarmed.

## 6. Using the box

The page has three tabs across the top:

| tab | what is on it |
|---|---|
| **Setup** | home position and wind — the everyday settings |
| **Advanced** | restart one service on its own, delete a location from the list |
| **Upgrade** | install a newer simulator, model or firmware ([section 7](#7-updating-the-box)) |

**Home position and wind** are set on the **Setup** tab, `http://SB1SIM01/`:

- **Home Position** — pick a location and press **Save**. **New Entry** and **Edit** manage
  the list.
- **Wind Settings** — speed in m/s and the direction it blows from, in degrees. **Save**.
- Both take effect when the simulation is reset. **Reset Simulation** at the bottom of the
  page does that, and takes a few seconds.

**Advanced Settings** holds the individual restarts and lets you delete a location.

The box starts the simulator automatically whenever it is powered on. Nothing needs to be
started by hand.

To switch it off, pull the power. It is a simulator; there is nothing to lose by doing so.

## 7. Updating the box

Once a box is running, update it **from its own web page** — no PC tools, nothing to
install, and you can do it from anything with a browser.

Open `http://SB1SIM01/` and go to the **Upgrade** tab.

It shows what is installed now, and three addresses to fetch from:

| | what it updates |
|---|---|
| **PX4 firmware** | the flight stack |
| **Model** | the flight-mechanics model |
| **Simulator** | the scripts, the services and this web page itself |

The addresses are filled in already and point at the current versions, so normally you
just press a button. Each part has its own **Upgrade** button, and **Upgrade all three**
does the lot. Tick **Reboot when finished** if you want the box to come up completely
fresh afterwards; it is not required.

Then leave the page alone. It reloads itself every few seconds and shows the log as it
goes, so you can watch it. A firmware or model update takes seconds; a simulator update
takes a few minutes, because it reinstalls the software the box is built from. **Do not
switch the box off while it runs.** The buttons are greyed out until it finishes, so a
second upgrade cannot be started on top of the first.

Nothing is installed unless it matches the checksum published next to it, so a
half-downloaded or tampered package is refused rather than installed.

Your home position list and wind setting are kept across all of this.

If it fails, the log on the page says where it stopped. The box is still running the old
version in that case — except for a simulator update, which is the one step that can
leave a half-installed box; pressing the button again repairs it.

### From Windows instead

Name the box, so the installer leaves the card out of it, with `-SkipSetup` so you are not
asked about the password and the key again:

```
powershell -ExecutionPolicy Bypass -File .\install64.ps1 -Box SB1SIM01 -SkipSetup
```

Use this for a box whose web page is not working. Download a
fresh `install64.ps1` now and then — it is the installer that knows where the current
versions live.

## 8. If something is wrong

**The installer does not find the card**

If Windows does not show it, take it out and put it back in. If Windows shows it under
another name, or it is still not found, name the drive yourself:
`-Card E:\`. If it says the card has no settings from the Imager, the customisation
steps were skipped ([section 2](#2-write-the-sd-card)): write the card again.

**The installer cannot find or reach the box**

Give it two full minutes from power-on. Then: is the WiFi password right, is the box within
range? Name lookup fails on some networks even when the box is perfectly reachable, so
give the installer the address when it asks, from your router's list of connected devices.
With an Ethernet cable, check the link lights at both ends. With a cable directly to your
PC, the two addresses must be in the same network.

**`the box at ... is not the one this PC talked to last time`**

Expected if the card of that box was written again, or another box now has this address.
The message gives the one command that clears it.

**`Permission denied (publickey,password)`**

The password is not what the box expects. It is the one set in the Imager, `pi`. If you are
unsure, write the card again.

**You want to change the fixed address, or the card has already been started**

The installer can only set these on a card that has never been in a box. Write the card
again and start over.

**The installer stops with an error about `sudo`**

The passwordless sudo step did not complete. Run the installer again without
`-SkipSetup`.

**`this box runs armhf, but the simulator is built for arm64`**

The 32-bit image was written. Write the card again with **Raspberry Pi OS Lite
(64-bit)** ([section 2](#2-write-the-sd-card)).

**A service is not `active`, or `restarts` keeps climbing**

Run the installer once more; a missing Python package is repaired by a re-run. If it
persists, collect the reason and send it on:

```
ssh pi@SB1SIM01 "systemctl status sim_px4 telemetry --no-pager -l | head -40"
```

**The web page is there but has no logos and no formatting**

The installation is incomplete — run the installer again.

**The GCS connects but shows no telemetry, or stops after a while**

Check that your GCS and the box are on the **same** network. A box reachable over two
networks at once (WiFi and Ethernet, on different segments) is the awkward case; prefer
one.

If it worked and then stopped, reset the simulation from the web page. If that helps only
temporarily, report it with the time it happened — the box keeps its logs now, so the
fault can be looked at afterwards.

**An upgrade on the Upgrade tab fails**

The log on the page says where it stopped. `no SHA256SUMS at ...` means the address is
wrong — it has to be a package, or the folder holding one, on a server that publishes
checksums beside it. `checksum mismatch` means the download was corrupted or the package
was altered; try again, and if it repeats, report it rather than working around it. A
failed firmware or model upgrade leaves the box on the old version; a failed simulator
upgrade is repaired by pressing the button again.

**The clock on the box is wrong**

A Raspberry Pi has no battery-backed clock: it learns the time from the network at every
boot. If the box has no internet access, timestamps in its logs will be wrong. The
installer warns about this if it cannot confirm the time service is running.

**Odd faults that come and go: suspect power**

An undervolted Pi corrupts SD cards and drops network links, and it looks like a software
fault. Use the official 3 A supply, and check:

```
ssh pi@SB1SIM01 "vcgencmd get_throttled"
```

`throttled=0x0` is healthy. Anything else means the supply or cooling is inadequate.

## 9. Reference

**On the box**

| | |
|---|---|
| Everything is installed in | `/opt/px4/` |
| What version is installed | `/opt/px4/MANIFEST` |
| Home position / wind | `/opt/px4/llh_home.txt`, `/opt/px4/wind.txt` |
| Flight logs | `/fs/microsd/` |
| Logs of the services | `ssh pi@<box> "journalctl -u telemetry -n 50 --no-pager"` |

**Services**

| | |
|---|---|
| `sim_px4` | the PX4 flight stack |
| `sim_songbird` | the flight-mechanics model |
| `sim_gimbal`, `gimbal-control` | the camera gimbal |
| `telemetry` | the MAVLink link to your GCS, UDP 14550 |
| `sim_failures` | the hardware failure switches |

**Network ports**

| | |
|---|---|
| 14550/UDP | MAVLink, for your GCS |
| 80/TCP | the settings web page |
| 22/TCP | SSH |

**Installer options**

| | |
|---|---|
| none | set up a new box from a freshly written card |
| `-Box`, followed by a name or an address | a box that is already running. `user@host` if the user is not `pi`. |
| `-Card`, followed by a drive | where the card is, if the installer does not find it |
| `-SkipSetup` | skip the key and sudo setup; for updating a box already set up. |
| `-SimUrl`, `-Px4Url`, each followed by an address | where to get the simulator and the firmware, so the installer does not ask. |

Run `Unblock-File .\install64.ps1`, then `Get-Help .\install64.ps1 -Full`, for the same list
on your PC.
