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,
   waits until buoyancy has righted it and the rates have steadied, and only
   *then* takes its attitude reference. It rocks between front and aft pushes;
   the sign comes from `rate(+push) − rate(−push)`, which cancels any constant
   lean exactly, so a ship hanging crooked measures fine — that lean **is**
   what is being measured. It then learns the differential trim that levels
   the ship, saves it as a warm-start, and descends to hover. No config
   editing, no freefall. Takes 2–4 minutes.

A hull built to fly usually lies over on the ground; that is fine and
expected. The ground attitude is never used as a reference — nothing is
measured until the ship is airborne and steady.

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 — or any particular build direction: sensors are found by type,
wiring is mapped by the wizard, and the sign test measures **which gimbal
axis** responds to the push (saved as `pitchIndex`) along with its sign. The
only physical requirement is two balloons spaced along the hull.

## 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.