# Reproducing the demo

## Tested host

- Ubuntu 24.04 x86_64 desktop
- 4+ logical CPUs; 8+ recommended
- 12 GiB RAM and 4 GiB swap
- 20 GiB free before setup
- X11 or XWayland available through `DISPLAY`

Install the small set of host utilities used by setup, process isolation, GUI
readiness, and screenshots:

```bash
sudo apt update
sudo apt install -y curl git gzip iproute2 procps tar util-linux \
  x11-utils xdotool gnome-screenshot
```

ROS, Gazebo, PX4 build dependencies, AprilTag, MAVROS, PyQt5, Pillow, and
`pymavlink` are installed inside the project-owned rootfs, not on the host.

## Setup from a fresh clone

```bash
git clone https://github.com/albert17github/PX4-AprilTag-Follow-Demo.git
cd PX4-AprilTag-Follow-Demo
./scripts/check_environment.sh --setup
./setup.sh --jobs 4
```

Setup performs six explicit stages: host check, pinned PX4 checkout, SHA256-
checked Ubuntu rootfs download, package installation, PX4 SITL build, and a
runtime verification. Logs are written under `runtime/logs/`. Rerunning setup is
safe and skips already-valid expensive stages.

The generated runtime is approximately 13 GiB and is excluded from Git. Version
and source locks are in `runtime/config/versions.env`; the resulting package and
binary hashes are recorded in `runtime/.setup/runtime.lock`.

Verify an existing installation without downloading or building:

```bash
./setup.sh --verify-only
./scripts/check_environment.sh --run
```

## Run

Start the scripted visible demo from the Ubuntu desktop:

```bash
./demo.sh
```

For interactive cart motion:

```bash
./demo.sh --keyboard
```

Gazebo can take 30–90 seconds to open under VMware software rendering and may
appear behind the terminal. Use `Alt+Tab` if necessary. Do not start a second
run; inspect and stop the first one instead:

```bash
./demo.sh --status
./demo.sh --stop
```

## Verification

```bash
./demo.sh --verify
```

This runs Python unit tests, keyboard and overlay self-tests, documentation and
asset integrity checks, runtime version/import checks, the machine-readable
reference evidence contract, and residual process/port checks. Full flight
gates create local evidence under `runs/`; those potentially large artifacts
are not committed.

## Troubleshooting

- `Runtime is missing`: run `./setup.sh` and inspect the stage log printed on
  failure.
- `A run is already active`: use `./demo.sh --status`, then `./demo.sh --stop`.
- no GUI: confirm `echo "$DISPLAY"` is non-empty and `xdpyinfo` succeeds.
- slow simulation: reduce competing VM load; metrics use simulation timestamps,
  while timeouts and cleanup also retain wall-clock watchdogs.
- package download failure: rerun setup. Downloads use retries and content hashes;
  never bypass a reported signature or checksum failure.