airship-autopilot/README.md

# Airship Autopilot (Create: Aeronautics + CC:Tweaked)

Altitude/pitch autopilot for a hot-air airship, delivered as an in-game installer
so it runs on any Minecraft server regardless of the computer's id.

## Install — ONE command, both PCs

Run the **same** command on each CC computer:

```
wget run https://gt.zyon.no/Stian/airship-autopilot/raw/branch/main/install.lua
```

The installer detects which PC it is on (flight sensors → `autopilot`,
monitor → `cockpit`), installs the right role, and continues **straight into
setup** — no reboot, no role names to remember. Re-run the same command any
time to update; it also cleans out files that no longer belong and asks
whether to keep or reset the ship profile.

(Advanced: append `autopilot` or `cockpit` to override detection.)

Requires HTTP enabled on the server (default on). If it is off, set
`[http] enabled = true` in `computercraft-server.toml` and restart the server.

## First-time setup (per ship)

The installer ships **code only** — everything ship-specific (which redstone
side drives which balloon, pitch sign, hover level) is measured on the ship by
the **setup wizard**, which the install flow takes you straight into:

1. **Wiring** — the wizard pulses each free side; you say which burner fired.
2. **Sign test** — the ship lifts off by itself, finds its own lift power,
   pushes the front balloon, verifies the response in both directions
   (auto-escalating the push if the response is weak), then descends and holds
   hover. No config editing, no freefall. Takes 1–3 minutes.

After that the ship is ready: `FLY` from the menu or `ENGAGE` from the cockpit
console. Pitch and altitude keep self-learning in flight. The wizard can be
re-run any time: `ap setup`, press `S` in standby, or menu choice 1.

Balloon orientation does **not** need to match any particular side of the
computer: sensors are found by type, wiring is mapped by the wizard, and the
pitch sign is measured — the only physical requirement is both balloons on the
fore/aft line (the axis the gimbal reports as pitch).

## Roles

| Role        | Boots                | Purpose                                     |
|-------------|----------------------|---------------------------------------------|
| `autopilot` | `ap boot` → wizard/standby | v3 observer autopilot (13 modules in `autopilot/`) |
| `cockpit`   | `cockpit`            | pilot control console (monitor + modem)     |

Boot chain (autopilot): `startup.lua` → `ap boot` → `autopilot/main.lua`.
Menu any time: `Ctrl+T`, then `ap`. (`stabilizeV2` remains as an alias.)

Ship state lives on the computer only: `sides.txt`, `calib.txt`, `target.txt`,
`settings.txt`. Reset it via menu `p` → `R`, or when re-running the installer.

## Updating the code

The repo is the source of truth for the installer. After editing the Lua:

```
./build.sh                # regenerate manifests
git commit -am "sync autopilot"
git push
```

Then re-run the `wget run` command in-game to pull the update.

Syncing with the singleplayer dev world (optional):

```
./build.sh --from-world   # world -> files/  (code only; state/legacy filtered)
./build.sh --to-world     # files/ -> world  (code only; never touches state)
```

Default world path is the "Modda wii" save; pass a different
`computercraft/computer` path as arg 2 if the world moves.

## Notes

Design history, hardware facts, tuning lessons and the recommended control
strategy are in `AIRSHIP_AUTOPILOT_NOTES.md` (in the modpack profile). The
control loop never fully converged; pitch oscillation under climb is the open
problem. Keep the altitude cascade simple and make pitch a slow trim.