diff --git a/.claude/skills/pifinder-remote/SKILL.md b/.claude/skills/pifinder-remote/SKILL.md index d1a75b204..81f62766b 100644 --- a/.claude/skills/pifinder-remote/SKILL.md +++ b/.claude/skills/pifinder-remote/SKILL.md @@ -61,6 +61,8 @@ to see the UI; that is how you "look at" PiFinder. | `logs [-n N]` | Tails the captured PiFinder and cedar startup logs (first place to look if `launch` fails). | | `ready` | Polls until the API answers; useful after a manual launch. | +`/api/key`, `/api/stop` and `/api/camera/*` need the Web UI login. `key` and `stop` log in on the first 401 with `PIFINDER_PASSWORD` (default `solveit`); a headless dev run accepts any password. + ## Keypad buttons PiFinder has a small keypad. Pass these names to `key` (case-sensitive), or a diff --git a/.claude/skills/pifinder-remote/scripts/pf_remote.py b/.claude/skills/pifinder-remote/scripts/pf_remote.py index 5231af588..51563240c 100755 --- a/.claude/skills/pifinder-remote/scripts/pf_remote.py +++ b/.claude/skills/pifinder-remote/scripts/pf_remote.py @@ -43,7 +43,9 @@ import sys import tempfile import time +import http.cookiejar import urllib.error +import urllib.parse import urllib.request from pathlib import Path @@ -132,25 +134,51 @@ def base_url(args): return f"http://127.0.0.1:{getattr(args, 'port', DEFAULT_PORT)}" -def http_get(url, timeout=15): - req = urllib.request.Request(url, method="GET") +# One cookie jar for the process, so the Web UI login session is sent with +# every request after login(). +_OPENER = urllib.request.build_opener( + urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()) +) + + +def _open(req, timeout): try: - with urllib.request.urlopen(req, timeout=timeout) as r: + with _OPENER.open(req, timeout=timeout) as r: return r.status, r.read() except urllib.error.HTTPError as e: return e.code, e.read() +def http_get(url, timeout=15): + return _open(urllib.request.Request(url, method="GET"), timeout) + + +def login(base, timeout=15): + """Log in to the Web UI. The password comes from PIFINDER_PASSWORD + (default "solveit"). A headless dev run accepts any password.""" + form = urllib.parse.urlencode( + {"password": os.environ.get("PIFINDER_PASSWORD", "solveit")} + ).encode("utf-8") + req = urllib.request.Request(base + "/login", data=form, method="POST") + return _open(req, timeout) + + def http_post(url, payload, timeout=15): + """POST JSON. On a 401, log in once and send the request again.""" data = json.dumps(payload if payload is not None else {}).encode("utf-8") - req = urllib.request.Request( - url, data=data, method="POST", headers={"Content-Type": "application/json"} - ) - try: - with urllib.request.urlopen(req, timeout=timeout) as r: - return r.status, r.read() - except urllib.error.HTTPError as e: - return e.code, e.read() + + def send(): + req = urllib.request.Request( + url, data=data, method="POST", headers={"Content-Type": "application/json"} + ) + return _open(req, timeout) + + status, body = send() + if status == 401: + parts = urllib.parse.urlsplit(url) + login(f"{parts.scheme}://{parts.netloc}", timeout) + status, body = send() + return status, body def wait_ready(base, timeout=60.0, interval=1.0): diff --git a/.envrc b/.envrc new file mode 100644 index 000000000..c98b77264 --- /dev/null +++ b/.envrc @@ -0,0 +1,4 @@ +use nix +watch_file flake.nix flake.lock shell.nix +watch_file nixos/pkgs/uv-python.nix +watch_file python/pyproject.toml python/uv.lock diff --git a/.github/scripts/publish_manifest.sh b/.github/scripts/publish_manifest.sh old mode 100644 new mode 100755 diff --git a/.github/scripts/update_manifest.py b/.github/scripts/update_manifest.py index 587db850d..0ad72e5ba 100644 --- a/.github/scripts/update_manifest.py +++ b/.github/scripts/update_manifest.py @@ -4,11 +4,19 @@ import argparse import json import re +import urllib.error +import urllib.request from datetime import datetime, timezone from pathlib import Path STORE_PATH_RE = re.compile(r"^/nix/store/[a-z0-9]+-[A-Za-z0-9._+=?,-]+$") + +# The binary caches devices resolve upgrades from. A build is only advertised +# as available once one of these actually serves its narinfo — see set_available. +DEV_CACHE = "https://cache.pifinder.eu/pifinder" +RELEASE_CACHE = "https://cache.pifinder.eu/pifinder-release" +DEFAULT_CACHES = (DEV_CACHE, RELEASE_CACHE) EMPTY_MANIFEST = { "schema": 1, "generated_at": None, @@ -49,14 +57,54 @@ def valid_store_path(value: str | None) -> bool: return isinstance(value, str) and STORE_PATH_RE.fullmatch(value) is not None -def set_available(entry: dict) -> dict: - if valid_store_path(entry.get("store_path")): - entry["available"] = True - entry.pop("reason", None) - else: +def _narinfo_url(store_path: str, cache: str) -> str: + digest = Path(store_path).name.split("-", 1)[0] + return f"{cache.rstrip('/')}/{digest}.narinfo" + + +def cache_serves(store_path: str, caches, timeout: int = 15) -> bool | None: + """Whether the closure is actually downloadable from a cache right now. + + Returns True if any cache serves the narinfo (200); False only if every + cache answered and none had it (a real 404 everywhere); None if a cache + could not be reached, so presence is unknown. Publishing treats anything + other than True as "do not advertise", so a failed push or a down cache can + never advertise a build the device cannot fetch. + """ + saw_404 = False + for cache in caches: + url = _narinfo_url(store_path, cache) + try: + with urllib.request.urlopen(url, timeout=timeout) as resp: + if resp.status == 200: + return True + except urllib.error.HTTPError as exc: + if exc.code == 404: + saw_404 = True + else: + return None + except (urllib.error.URLError, OSError, TimeoutError): + return None + return False if saw_404 else None + + +def set_available(entry: dict, caches=DEFAULT_CACHES, verify: bool = True) -> dict: + store_path = entry.get("store_path") + if not valid_store_path(store_path): entry["store_path"] = None entry["available"] = False entry.setdefault("reason", "no build") + return entry + + if verify: + present = cache_serves(store_path, caches) + if present is not True: + entry["available"] = False + entry["reason"] = "not in cache" if present is False else "cache unreachable" + return entry + + entry["available"] = True + entry.pop("reason", None) return entry @@ -79,11 +127,17 @@ def key(item: dict) -> tuple[int, int, str]: return sorted(entries, key=key) +def resolve_verify(args: argparse.Namespace) -> tuple[tuple[str, ...], bool]: + caches = tuple(args.verify_cache) if args.verify_cache else DEFAULT_CACHES + return caches, not args.skip_cache_check + + def update_build(args: argparse.Namespace) -> None: manifest = load_manifest(args.manifest) channels = manifest["channels"] store_path = args.store_path or None short_sha = (args.head_sha or args.sha)[:7] + caches, verify = resolve_verify(args) if args.pr_number: number = int(args.pr_number) @@ -100,7 +154,7 @@ def update_build(args: argparse.Namespace) -> None: "store_path": store_path, "built_at": now_iso(), } - set_available(entry) + set_available(entry, caches, verify) channels["unstable"] = replace_entry( channels["unstable"], lambda item: item.get("kind") == "pr" @@ -120,7 +174,7 @@ def update_build(args: argparse.Namespace) -> None: "store_path": store_path, "built_at": now_iso(), } - set_available(entry) + set_available(entry, caches, verify) channels["unstable"] = replace_entry( channels["unstable"], lambda item: item.get("kind") == "trunk" @@ -135,6 +189,7 @@ def update_build(args: argparse.Namespace) -> None: def update_release(args: argparse.Namespace) -> None: manifest = load_manifest(args.manifest) + caches, verify = resolve_verify(args) channel = "beta" if args.release_type == "beta" else "stable" entry = { "kind": "release", @@ -150,7 +205,7 @@ def update_release(args: argparse.Namespace) -> None: "migration_sha256_url": args.migration_sha256_url or None, "built_at": now_iso(), } - set_available(entry) + set_available(entry, caches, verify) manifest["channels"][channel] = replace_entry( manifest["channels"][channel], lambda item: item.get("kind") == "release" and item.get("label") == args.tag, @@ -159,6 +214,17 @@ def update_release(args: argparse.Namespace) -> None: save_manifest(args.manifest, manifest) +def add_cache_args(sub: argparse.ArgumentParser) -> None: + # A build is advertised as available only if one of these caches actually + # serves its narinfo. Repeatable; defaults to the dev + release caches. + sub.add_argument("--verify-cache", action="append", metavar="URL") + sub.add_argument( + "--skip-cache-check", + action="store_true", + help="advertise on store-path syntax alone (tests / offline only)", + ) + + def parser() -> argparse.ArgumentParser: root = argparse.ArgumentParser() sub = root.add_subparsers(dest="command", required=True) @@ -176,6 +242,7 @@ def parser() -> argparse.ArgumentParser: build.add_argument("--head-repo") build.add_argument("--head-ref") build.add_argument("--head-sha") + add_cache_args(build) build.set_defaults(func=update_build) release = sub.add_parser("release") @@ -190,6 +257,7 @@ def parser() -> argparse.ArgumentParser: release.add_argument("--migration-sha256-url") release.add_argument("--title") release.add_argument("--notes") + add_cache_args(release) release.set_defaults(func=update_release) return root diff --git a/.github/workflows/nixos-pr-build.yml b/.github/workflows/nixos-pr-build.yml index 004591805..494e0df28 100644 --- a/.github/workflows/nixos-pr-build.yml +++ b/.github/workflows/nixos-pr-build.yml @@ -6,10 +6,10 @@ name: Build PiFinder NixOS (testable PRs) # `pull_request_target` runs in the BASE repo's trusted context, so the job has # the real ATTIC_TOKEN and a read-write GITHUB_TOKEN even for fork PRs. The # contributor's code is checked out explicitly (head SHA) and built. This is -# only reached after a maintainer applies the `testable` (or `preview`) label — -# that label is the security boundary: it runs contributor code with the cache -# push token, so review the diff before labeling, and re-review on each new push -# to a labeled PR. +# only reached after a maintainer applies the `testable` label — that label is +# the security boundary: it runs contributor code with the cache push token, so +# review the diff before labeling, and re-review on each new push to a labeled +# PR. # # Build strategy: the free GitHub-hosted ubuntu-24.04-arm runner builds first. # Its cores are faster than the Pi5, and the Attic cache (cache.pifinder.eu) is @@ -33,9 +33,7 @@ permissions: jobs: # Primary: free GitHub-hosted arm64 runner (native aarch64, no QEMU). build-hosted: - if: | - contains(github.event.pull_request.labels.*.name, 'preview') || - contains(github.event.pull_request.labels.*.name, 'testable') + if: contains(github.event.pull_request.labels.*.name, 'testable') runs-on: ubuntu-24.04-arm # Generous: only a kernel/source change compiles from scratch (~1 h on this # 4-core runner); everything else substitutes from Attic in minutes. @@ -52,8 +50,8 @@ jobs: persist-credentials: false # Fork PRs: pull_request_target checkout of the head requires opt-in # since actions/checkout began refusing it. The head SHA is pinned - # explicitly and only reached after the `testable`/`preview` label, - # which is the review gate for running contributor code. + # explicitly and only reached after the `testable` label, which is the + # review gate for running contributor code. allow-unsafe-pr-checkout: true - uses: DeterminateSystems/nix-installer-action@main @@ -106,8 +104,7 @@ jobs: needs: build-hosted if: | always() && - (contains(github.event.pull_request.labels.*.name, 'preview') || - contains(github.event.pull_request.labels.*.name, 'testable')) && + contains(github.event.pull_request.labels.*.name, 'testable') && needs.build-hosted.result == 'failure' runs-on: [self-hosted, aarch64] timeout-minutes: 240 @@ -121,8 +118,8 @@ jobs: persist-credentials: false # Fork PRs: pull_request_target checkout of the head requires opt-in # since actions/checkout began refusing it. The head SHA is pinned - # explicitly and only reached after the `testable`/`preview` label, - # which is the review gate for running contributor code. + # explicitly and only reached after the `testable` label, which is the + # review gate for running contributor code. allow-unsafe-pr-checkout: true - name: Ensure nix is on PATH (self-hosted runner) @@ -170,7 +167,18 @@ jobs: group: manifest-write cancel-in-progress: false steps: + # Check out the PR's BASE branch explicitly. A bare checkout under + # pull_request_target lands on the repository's default branch, which + # may carry this workflow (so the event fires) without carrying the + # scripts below -- the job then dies after a successful build, leaving + # an image in Attic that no device can reach because the manifest was + # never written. The base branch is the branch this workflow file itself + # came from, so the scripts are always beside it, and it stays + # maintainer-controlled: never check out the PR head here, which would + # run contributor code with contents:write and the Attic token. - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.base.ref }} - name: Update generated manifest branch env: diff --git a/.github/workflows/nox.yml b/.github/workflows/nox.yml index 33352f1a8..a979ea084 100644 --- a/.github/workflows/nox.yml +++ b/.github/workflows/nox.yml @@ -1,4 +1,9 @@ name: nox +# The nixos branch manages the Python environment with uv (pyproject.toml + +# uv.lock) instead of nox + requirements*.txt, so this runs the same checks +# (ruff, mypy, pytest) through uv. The workflow keeps upstream's "nox" name so +# PR check wiring stays identical across branches. +# # Run on pushes to the long-lived branches and on pull requests. Restricting # `push` to main/release means a push to a feature branch with an open PR only # triggers the `pull_request` run (not also a `push` run), so a PR gets a single @@ -18,12 +23,22 @@ jobs: working-directory: ./python steps: - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v5 with: - submodules: true - # python/tetra3 -> PiFinder/tetra3/tetra3 is untracked (see ADR 0035), - # and `import tetra3` resolves the package through it. - - run: ln -sfn PiFinder/tetra3/tetra3 tetra3 - - uses: wntrblm/nox@2024.04.15 - with: - python-versions: "3.9" - - run: nox -s lint format type_hints smoke_tests unit_tests ui_tests + enable-cache: true + # Same ruff pin as upstream main's noxfile, so shared files keep one style. + - name: Lint + run: uvx ruff@0.4.8 check --config "builtins=['_']" . + - name: Format check + run: uvx ruff@0.4.8 format --check . + - name: Sync environment + run: uv sync --frozen + - name: Type check + run: uv run mypy PiFinder + - name: Smoke tests + run: uv run pytest -m smoke + - name: Unit tests + run: uv run pytest -m unit + # The web tests need a Selenium grid, which CI does not have. + - name: Integration tests + run: uv run pytest -m integration --ignore-glob='tests/test_web_*' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index df87b7859..f0041125d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,13 +1,16 @@ name: Release NixOS image -# Builds the PiFinder NixOS SD image and migration tarball and publishes them as +# Builds the PiFinder NixOS SD images (lean, and full when flake.nix has +# catalog images) and the migration tarball and publishes them as # a GitHub (pre-)release, and records the closure in the nixos-manifest branch. # -# Runners are native aarch64 (no QEMU): the Pi5 self-hosted runner is tried -# first, with the free GitHub-hosted `ubuntu-24.04-arm` runner as a fallback if -# the Pi is offline/slow — mirroring nixos-pr-build.yml. The arch-sensitive -# `nix build` runs there; the image is handed off as an artifact and the -# arch-independent packaging + publishing happens on ubuntu-latest. +# Runners are native aarch64 (no QEMU): the free GitHub-hosted +# `ubuntu-24.04-arm` runner builds first (faster than the Pi5; Attic substitutes +# everything already built, so only a kernel/source change compiles), with the +# self-hosted Pi5 as a last-resort fallback if the hosted build fails — +# mirroring nixos-pr-build.yml. The arch-sensitive `nix build` runs there; the +# image is handed off as an artifact and the arch-independent packaging + +# publishing happens on ubuntu-latest. on: workflow_dispatch: inputs: @@ -33,11 +36,18 @@ on: required: false default: '' +# Read-only by default. The release job asks for contents: write itself. +permissions: + contents: read + jobs: - # Native aarch64 build on the Pi5 self-hosted runner (preferred, fast). + # Last-resort fallback: self-hosted Pi5. Only runs if the hosted build failed + # (Pi offline/at capacity). Slow for a from-scratch kernel, hence the timeout. build-native: + needs: build-hosted + if: always() && needs.build-hosted.result == 'failure' runs-on: [self-hosted, aarch64] - timeout-minutes: 90 + timeout-minutes: 240 outputs: store_path: ${{ steps.push.outputs.store_path }} source_sha: ${{ steps.sha.outputs.source_sha }} @@ -80,6 +90,7 @@ jobs: fi echo "store_path=$STORE_PATH" >> "$GITHUB_OUTPUT" + # Lean image: the system and an empty PiFinder_data. - name: Build SD image run: | nix build .#images.pifinder -L -o result-sd @@ -91,54 +102,46 @@ jobs: path: result-sd/sd-image/*.img.zst retention-days: 1 - # The migration tarball is cut from the MINIMAL migration system, not the - # full image — it resolves the full system from the update manifest at - # first boot (ADR 0004 / 0003). - - name: Build migration image + # Full image: the lean image plus the catalog images. It exists only when + # flake.nix sets catalogImagesSrc (plan A4 and B8). + - name: Build full SD image + id: full + run: | + if [ "$(nix eval --json .#images --apply 'i: i ? pifinder-full')" = true ]; then + nix build .#images.pifinder-full -L -o result-full + echo "built=true" >> "$GITHUB_OUTPUT" + else + echo "No images.pifinder-full: publishing the lean image only." + fi + + - name: Upload full SD image + if: steps.full.outputs.built == 'true' + uses: actions/upload-artifact@v4 + with: + name: sdfull-native + path: result-full/sd-image/*.img.zst + retention-days: 1 + + # The migration tarball holds the MINIMAL migration system, built + # straight from its closure. It resolves the full system from the update + # manifest at first boot (ADR 0039). + - name: Build migration tarball run: | - nix build .#images.pifinder-migration -L -o result-mig + nix build .#packages.aarch64-linux.migration-tarball -L -o result-mig - name: Upload migration image uses: actions/upload-artifact@v4 with: name: migimage-native - path: result-mig/sd-image/*.img.zst + path: result-mig/pifinder-migration.tar.zst retention-days: 1 - # Poll the native builder for ~15 min, then decide whether to fall back. - native-wait: - runs-on: ubuntu-latest - timeout-minutes: 20 - outputs: - need_fallback: ${{ steps.wait.outputs.need_fallback }} - steps: - - name: Wait for native build - id: wait - env: - GH_TOKEN: ${{ github.token }} - run: | - for i in $(seq 1 30); do - sleep 30 - RESULT=$(gh api "repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/jobs" \ - --jq '.jobs[] | select(.name == "build-native") | .conclusion // "pending"' 2>/dev/null || echo "pending") - echo "Check $i/30: build-native=$RESULT" - if [ "$RESULT" = "success" ]; then - echo "need_fallback=false" >> "$GITHUB_OUTPUT" - exit 0 - elif [ "$RESULT" = "failure" ] || [ "$RESULT" = "cancelled" ]; then - echo "need_fallback=true" >> "$GITHUB_OUTPUT" - exit 0 - fi - done - echo "Native build not done after 15 min, falling back to hosted" - echo "need_fallback=true" >> "$GITHUB_OUTPUT" - - # Fallback on a free GitHub-hosted arm64 runner (native aarch64, no QEMU). + # Primary: free GitHub-hosted arm64 runner (native aarch64, no QEMU). Attic + # substitutes anything already built, so only a kernel/source change compiles + # from scratch (~1 h here); the result is pushed back so the next build is fast. build-hosted: - needs: native-wait - if: needs.native-wait.outputs.need_fallback == 'true' runs-on: ubuntu-24.04-arm - timeout-minutes: 120 + timeout-minutes: 150 outputs: store_path: ${{ steps.push.outputs.store_path }} source_sha: ${{ steps.sha.outputs.source_sha }} @@ -159,7 +162,7 @@ jobs: extra-conf: | extra-system-features = big-parallel extra-substituters = https://cache.pifinder.eu/pifinder - extra-trusted-public-keys = pifinder:VkemNaMqXDcsYlpONItSvOOcBIa1vEfnpyqdetr3gck= + extra-trusted-public-keys = pifinder:8UU/O3oLkaJHHUyqEcPGl+9F1m4MqDca39Ewl49jBmE= - name: Setup Attic caches (cache.pifinder.eu) env: @@ -181,6 +184,7 @@ jobs: fi echo "store_path=$STORE_PATH" >> "$GITHUB_OUTPUT" + # Lean image: the system and an empty PiFinder_data. - name: Build SD image run: | nix build .#images.pifinder -L -o result-sd @@ -192,25 +196,45 @@ jobs: path: result-sd/sd-image/*.img.zst retention-days: 1 - # Minimal migration system — see the native job's comment (ADR 0004). - - name: Build migration image + # Full image: the lean image plus the catalog images. It exists only when + # flake.nix sets catalogImagesSrc (plan A4 and B8). + - name: Build full SD image + id: full + run: | + if [ "$(nix eval --json .#images --apply 'i: i ? pifinder-full')" = true ]; then + nix build .#images.pifinder-full -L -o result-full + echo "built=true" >> "$GITHUB_OUTPUT" + else + echo "No images.pifinder-full: publishing the lean image only." + fi + + - name: Upload full SD image + if: steps.full.outputs.built == 'true' + uses: actions/upload-artifact@v4 + with: + name: sdfull-hosted + path: result-full/sd-image/*.img.zst + retention-days: 1 + + # Minimal migration system — see the native job's comment (ADR 0039). + - name: Build migration tarball run: | - nix build .#images.pifinder-migration -L -o result-mig + nix build .#packages.aarch64-linux.migration-tarball -L -o result-mig - name: Upload migration image uses: actions/upload-artifact@v4 with: name: migimage-hosted - path: result-mig/sd-image/*.img.zst + path: result-mig/pifinder-migration.tar.zst retention-days: 1 # Arch-independent: package the migration tarball + checksums and publish. Runs - # on whichever build succeeded (native preferred). + # on whichever build succeeded (hosted preferred). release: - needs: [build-native, native-wait, build-hosted] + needs: [build-hosted, build-native] if: | always() && - (needs.build-native.result == 'success' || needs.build-hosted.result == 'success') + (needs.build-hosted.result == 'success' || needs.build-native.result == 'success') runs-on: ubuntu-latest permissions: contents: write @@ -221,10 +245,10 @@ jobs: - name: Checkout base repo uses: actions/checkout@v4 - # Download native and hosted images to separate dirs. If both builds ran - # (native slow → fallback fired) their images share a filename, so merging - # them would corrupt the archive — never merge; the assemble step prefers - # native. + # Download hosted and native images to separate dirs. If both builds ran + # (hosted failed → Pi5 fallback fired) their images share a filename, so + # merging them would corrupt the archive — never merge; the assemble step + # prefers the hosted (primary) artifact. - name: Download native SD image continue-on-error: true uses: actions/download-artifact@v4 @@ -239,6 +263,20 @@ jobs: name: sdimage-hosted path: img-hosted + - name: Download native full SD image + continue-on-error: true + uses: actions/download-artifact@v4 + with: + name: sdfull-native + path: full-native + + - name: Download hosted full SD image + continue-on-error: true + uses: actions/download-artifact@v4 + with: + name: sdfull-hosted + path: full-hosted + - name: Download native migration image continue-on-error: true uses: actions/download-artifact@v4 @@ -263,45 +301,30 @@ jobs: run: | set -euo pipefail # Only some dirs may exist (downloads are continue-on-error); create - # all so find can't fail under pipefail. Prefer the native builder's - # artifacts (listed first); fall back to hosted. - mkdir -p img-native img-hosted mig-native mig-hosted - IMAGE_SRC=$(find img-native img-hosted -type f -name '*.img.zst' -print -quit) - MIG_SRC=$(find mig-native mig-hosted -type f -name '*.img.zst' -print -quit) + # all so find can't fail under pipefail. Prefer the hosted builder's + # artifacts (listed first); fall back to native (Pi5). + mkdir -p img-native img-hosted full-native full-hosted mig-native mig-hosted + IMAGE_SRC=$(find img-hosted img-native -type f -name '*.img.zst' -print -quit) + FULL_SRC=$(find full-hosted full-native -type f -name '*.img.zst' -print -quit) + MIG_SRC=$(find mig-hosted mig-native -type f -name '*.tar.zst' -print -quit) if [ -z "$IMAGE_SRC" ] || [ -z "$MIG_SRC" ]; then echo "Missing artifact: sd=[$IMAGE_SRC] migration=[$MIG_SRC]" >&2 exit 1 fi mkdir -p release cp "$IMAGE_SRC" "release/pifinder-${TAG}.img.zst" + # The full image is optional (flake.nix catalogImagesSrc). + if [ -n "$FULL_SRC" ]; then + cp "$FULL_SRC" "release/pifinder-full-${TAG}.img.zst" + fi + + # The migration tarball is built by Nix from the minimal migration + # system's closure (ADR 0039); publish it as is. + cp "$MIG_SRC" "release/pifinder-migration-${TAG}.tar.zst" - # The migration tarball is cut from the MINIMAL migration image — it - # resolves the full system from the update manifest at first boot, so - # its content never goes stale (ADR 0004 / 0003). - rm -f /tmp/pifinder-mig.img - zstd -d "$MIG_SRC" -o /tmp/pifinder-mig.img - - LOOP=$(sudo losetup --find --show --partscan /tmp/pifinder-mig.img) - sudo mkdir -p /mnt/boot /mnt/root - sudo mount "${LOOP}p1" /mnt/boot - sudo mount "${LOOP}p2" /mnt/root - - mkdir -p /tmp/tarball-staging - sudo cp -a /mnt/boot /tmp/tarball-staging/boot - sudo cp -a /mnt/root /tmp/tarball-staging/rootfs - - sudo umount /mnt/boot /mnt/root - sudo losetup -d "$LOOP" - rm -f /tmp/pifinder-mig.img - - sudo tar -C /tmp/tarball-staging -cf - \ - --exclude='*/lost+found' \ - boot rootfs | zstd -T0 -19 -o "release/pifinder-migration-${TAG}.tar.zst" - sudo rm -rf /tmp/tarball-staging - - # Never-again guard (2026-07-05 field failure): during migration the - # tarball is copied into RAM, so a 2GB board can only hold ~1.4GB. - # Refuse to publish a release that cannot migrate 2GB boards. + # Size guard. The btrfs migration reads the tarball from the card, not + # from RAM, but the download still happens over the user's WiFi, and + # the budget keeps the minimal system minimal. MIG_MB=$(( $(stat -c%s "release/pifinder-migration-${TAG}.tar.zst") / 1048576 )) BUDGET_MB=800 echo "migration tarball: ${MIG_MB}MB (budget ${BUDGET_MB}MB)" @@ -325,7 +348,7 @@ jobs: # still publishes the artifacts to this repo. if: (inputs.source_repository || github.repository) == github.repository env: - SOURCE_SHA: ${{ needs.build-native.outputs.source_sha || needs.build-hosted.outputs.source_sha }} + SOURCE_SHA: ${{ needs.build-hosted.outputs.source_sha || needs.build-native.outputs.source_sha }} run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" @@ -353,8 +376,8 @@ jobs: # runs for fork-source builds too. source_sha is the built source commit; # the tarball URL points at this repo's release assets. env: - STORE_PATH: ${{ needs.build-native.outputs.store_path || needs.build-hosted.outputs.store_path }} - SOURCE_SHA: ${{ needs.build-native.outputs.source_sha || needs.build-hosted.outputs.source_sha }} + STORE_PATH: ${{ needs.build-hosted.outputs.store_path || needs.build-native.outputs.store_path }} + SOURCE_SHA: ${{ needs.build-hosted.outputs.source_sha || needs.build-native.outputs.source_sha }} RELEASE_NOTES: ${{ inputs.notes }} run: | set -euo pipefail diff --git a/.github/workflows/web-integration-tests.yml b/.github/workflows/web-integration-tests.yml index 6cac28709..bcc5025d9 100644 --- a/.github/workflows/web-integration-tests.yml +++ b/.github/workflows/web-integration-tests.yml @@ -39,9 +39,8 @@ jobs: run: | git submodule sync git submodule update --init --recursive - # The python/tetra3 -> PiFinder/tetra3/tetra3 symlink is untracked - # (see ADR 0035), so CI creates it here. - ln -sfn PiFinder/tetra3/tetra3 tetra3 + # The python/tetra3 -> PiFinder/tetra3/tetra3 symlink is tracked in + # the repo, so it no longer needs to be created here. - name: Use cache of hip_main.dat star catalog diff --git a/.gitignore b/.gitignore index 37db3ce29..593e6ef1f 100644 --- a/.gitignore +++ b/.gitignore @@ -164,6 +164,8 @@ case/my_printer .direnv/ **/.claude/* !**/.claude/skills/ +.agents/ +.codex/ .serena/ astro_data/comets.txt @@ -171,3 +173,7 @@ astro_data/comets.txt test_ubx test_ubx/* python/telemetry_analysis/ + +# nix build result symlinks +result +result-* diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index bbd1b94ab..000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "python/PiFinder/tetra3"] - path = python/PiFinder/tetra3 - url = https://github.com/smroid/cedar-solve diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2a538aa17..317fee59c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,15 +1,27 @@ -# See https://pre-commit.com for more information -# See https://pre-commit.com/hooks.html for more hooks repos: - - repo: https://github.com/saltstack/mirrors-nox - rev: 'v2022.11.21' # Use the sha / tag you want to point at + - repo: local hooks: - - id: nox - files: ^.*\.py$ - args: - - -f - - python/noxfile.py - - -s - - type_hints - - smoke_tests - - -- + - id: ruff-lint + name: ruff lint + entry: bash -c 'cd python && ruff check' + language: system + files: ^python/.*\.py$ + pass_filenames: false + - id: ruff-format + name: ruff format check + entry: bash -c 'cd python && ruff format --check' + language: system + files: ^python/.*\.py$ + pass_filenames: false + - id: mypy + name: mypy type check + entry: bash -c 'cd python && mypy .' + language: system + files: ^python/.*\.py$ + pass_filenames: false + - id: smoke-tests + name: smoke tests + entry: bash -c 'cd python && pytest -m smoke' + language: system + files: ^python/.*\.py$ + pass_filenames: false diff --git a/CLAUDE.md b/CLAUDE.md index cac5d7f52..19a168efc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,66 +22,46 @@ Maintainers can make `fresh` root on `main` automatically per clone (without cha git remote set-head origin main ``` -**Initialise the `tetra3` submodule in every new worktree.** `python/PiFinder/tetra3` is a git submodule (the `cedar-solve`/Tetra3 solver); the importable package is its inner `tetra3/tetra3/` dir, and `import tetra3` resolves it through the symlink `python/tetra3 -> PiFinder/tetra3/tetra3`. That symlink is deliberately **untracked** (see ADR 0035 — tracking it broke `git pull` on fielded units), so in every fresh clone or worktree create it by hand alongside initialising the submodule. `git worktree add` / `EnterWorktree` does **not** populate submodules, so a fresh worktree starts with an empty submodule dir. Any test that imports the solver then fails with `ModuleNotFoundError: No module named 'tetra3'` (or `cedar_detect_pb2`) — this is a missing checkout, **not** a code problem, so don't reach for `PYTHONPATH` hacks. Fix it once per worktree: - -```bash -git submodule update --init python/PiFinder/tetra3 -ln -sfn PiFinder/tetra3/tetra3 python/tetra3 -``` - -mypy also needs this: its config points at `python/PiFinder/tetra3/tetra3`, so `nox -s type_hints` can't run in a worktree until the submodule is initialised. +**No tetra3 submodule on this branch.** Unlike upstream `main`, the solver +(`cedar-solve`/Tetra3) is an ordinary uv dependency (pinned git rev in +`python/pyproject.toml`), so worktrees need no `git submodule` step. ## Development Commands -**Running Python** -Developers may have created virtual environments in directories like ".venv" or "venv". Make sure these virtual -environments are activated before any of the python based tools below. - -**Development workflow uses Nox for task automation:** -```bash -nox -s lint # Code linting with Ruff (auto-fixes issues) -nox -s format # Code formatting with Ruff -nox -s type_hints # Type checking with MyPy -nox -s smoke_tests # Quick functionality validation -nox -s unit_tests # Full unit test suite -nox -s babel # I18n message extraction and compilation -nox -s web_tests # Testing the webserver, see below -``` - -**Direct testing with pytest:** -```bash -pytest -m smoke # Smoke tests for core functionality -pytest -m unit # Unit tests for isolated components -pytest -m integration # End-to-end integration tests -``` +**This branch uses uv (pyproject.toml + uv.lock), not nox/requirements*.txt.** +All Python tooling runs through uv from `python/`: -**Development setup:** ```bash cd python/ -python3.9 -m venv .venv -source .venv/bin/activate -pip install -r requirements.txt -pip install -r requirements_dev.txt +uv sync --frozen # create/refresh .venv from uv.lock +uvx ruff@0.4.8 check --config "builtins=['_']" . # lint (same pin as CI / upstream noxfile) +uvx ruff@0.4.8 format . # format +uv run mypy PiFinder # type checking +uv run pytest -m smoke # smoke tests +uv run pytest -m unit # unit tests +uv run pytest -m integration --ignore-glob='tests/test_web_*' # integration (web tests need Selenium) ``` -If the .venv dir already exists, you can directly source it and run the app. +CI (`.github/workflows/nox.yml` — keeps the upstream "nox" check name) runs +exactly these commands. -Watch out for .venv directories containing virtual environments, that you need to activate first. +NixOS dev-box note: manylinux wheels (numpy etc.) need `libstdc++`; if imports +fail with `libstdc++.so.6: cannot open shared object file`, run tests with +`LD_LIBRARY_PATH=$(nix build --print-out-paths nixpkgs#stdenv.cc.cc.lib)/lib`. **Running the application:** First start the `cedar-detect-server` which is in `bin` (you need to use `-p 50551`, when invoking it). -Use the correct architecture suffix for cedar-detect-server according to the platform you're running on. +Use the correct architecture suffix for cedar-detect-server according to the platform you're running on. -Development setup has to have run and you should be in .venv virtual environment ```bash cd python/ -python -m PiFinder.main [options] +uv run python -m PiFinder.main [options] ``` Usual startup: ```bash -python3.9 -m PiFinder.main -fh --camera debug --keyboard local -x +uv run python -m PiFinder.main -fh --camera debug --keyboard local -x ``` ## Reference Documentation @@ -192,6 +172,39 @@ Tests use pytest with custom markers for different test types. The smoke tests p - **Linting:** Ruff with Python 3.9 target, Black-compatible formatting - **Type Checking:** MyPy with gradual typing adoption - **Code Style:** 88-character line length, double quotes, space indentation +- **Comments:** describe what the code does now, not how it changed. No "previously / no longer / used to / moved from" — history lives in git/jj, not in comments. - **I18n Support:** Babel integration for multi-language UI The codebase follows modern Python practices with type hints, comprehensive testing, and automated code quality checks integrated into the development workflow. + +## NixOS Development + +**CRITICAL: Never run `nix build` or `nix eval` on Pi 4 targets.** The Pi 4 lacks sufficient resources and will hang/crash. Always build on pi5.local (GitHub Actions runner), push to Attic, then trigger the upgrade service: +```bash +# Build on pi5 +ssh pi5.local 'nix build --no-link --print-out-paths github:mrosseel/PiFinder/nixos#nixosConfigurations.pifinder.config.system.build.toplevel' +# Push to Attic (so Pi can download signed paths) +ssh pi5.local 'attic push pifinder:pifinder ' +# Trigger upgrade on target Pi (downloads from Attic, activates, reboots) +ssh pifinder@ 'echo "" > /run/pifinder/upgrade-ref && sudo systemctl start --no-block pifinder-upgrade.service' +# Monitor progress +ssh pifinder@ 'cat /run/pifinder/upgrade-status' +``` + +**Netboot deployment (dev Pi on proxnix NFS):** +```bash +./deploy-image-to-nfs.sh # Build and deploy to NFS +``` + +**Power control (Shelly plug via Home Assistant):** +```bash +~/.local/bin/pifinder-power-off.sh # Turn off PiFinder +~/.local/bin/pifinder-power-on.sh # Turn on PiFinder +``` + +**Check Pi status:** +```bash +ssh pifinder@192.168.5.146 # SSH to netboot Pi +systemctl status pifinder # Check service status +journalctl -u pifinder -f # Follow service logs +``` diff --git a/bin/cedar-detect-server-aarch64 b/bin/cedar-detect-server-aarch64 deleted file mode 100755 index 7b44b89b7..000000000 Binary files a/bin/cedar-detect-server-aarch64 and /dev/null differ diff --git a/bin/cedar-detect-server-arm64 b/bin/cedar-detect-server-arm64 deleted file mode 100755 index ea792437f..000000000 Binary files a/bin/cedar-detect-server-arm64 and /dev/null differ diff --git a/default_config.json b/default_config.json index 0178cd13a..10bbbd5b6 100644 --- a/default_config.json +++ b/default_config.json @@ -181,7 +181,10 @@ "active_eyepiece_index": 0 }, "imu_threshold_scale": 1, + "dev_mode": false, + "show_fps": false, "telemetry_record": false, - "telemetry_images": false, - "telemetry_raw_imu": false + "telemetry_raw_imu": false, + "telemetry_sections": ["imu", "sqm", "solve", "target"], + "telemetry_max_session_mb": 1024 } diff --git a/deploy-image-to-nfs.sh b/deploy-image-to-nfs.sh new file mode 100755 index 000000000..1aec63990 --- /dev/null +++ b/deploy-image-to-nfs.sh @@ -0,0 +1,383 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Deploy PiFinder NixOS netboot configuration to proxnix +# +# Builds the pifinder-netboot closure (NFS root baked in), copies the nix store +# closure to NFS, and sets up TFTP with kernel/initrd/firmware for PXE boot. +# +# Boot sequence: Pi firmware → u-boot → extlinux/extlinux.conf (TFTP) → NFS root + +PROXNIX="mike@192.168.5.12" +NFS_ROOT="/srv/nfs/pifinder" +TFTP_ROOT="/srv/tftp" +PI_IP="192.168.5.150" +PI_MAC="e4-5f-01-b7-37-31" # For PXE boot speedup + +# SSH options to prevent timeout during long transfers +SSH_OPTS="-o ServerAliveInterval=30 -o ServerAliveCountMax=10" +export RSYNC_RSH="ssh ${SSH_OPTS}" + +SSH_PUBKEY="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGrPg9hSgxwg0EECxXSpYi7t3F/w/BgpymlD1uUDedRz mike@nixtop" + +# Password hash for "solveit" +SHADOW_HASH='$6$upbQ1/Jfh7zDiIYW$jPVQdYJCZn/Pe/OIGx89DZm9trIhEJp7Q4LNZsq/5x9csj6U08.P2avebrQIDJCEyD0xipsV6C19Sr5iAbCuv1' + +# ── Helpers ────────────────────────────────────────────────────────────────── + +run_proxnix() { + ssh ${SSH_OPTS} "${PROXNIX}" "bash -euo pipefail -c \"$1\"" +} + +# ── Build netboot closure ──────────────────────────────────────────────────── + +echo "=== Building pifinder-netboot closure ===" +nix build .#nixosConfigurations.pifinder-netboot.config.system.build.toplevel \ + -o result-netboot --system aarch64-linux + +CLOSURE=$(readlink -f result-netboot) +echo "Closure: $CLOSURE" + +# Extract paths from closure +KERNEL=$(readlink -f result-netboot/kernel) +INITRD=$(readlink -f result-netboot/initrd) +DTBS=$(readlink -f result-netboot/dtbs) +INIT_PATH="${CLOSURE}/init" + +KERNEL_NAME=$(basename "$(dirname "$KERNEL")")-Image +INITRD_NAME=$(basename "$(dirname "$INITRD")")-initrd + +echo "Kernel: $KERNEL" +echo "Initrd: $INITRD" +echo "DTBs: $DTBS" +echo "Init: $INIT_PATH" + +# ── Stop TFTP — prevent Pi from netbooting during deploy ───────────────────── + +echo "Stopping TFTP server..." +ssh "${PROXNIX}" "sudo systemctl stop atftpd.service" + +# ── Halt Pi if running — prevent NFS corruption ────────────────────────────── + +if ssh -o ConnectTimeout=3 -o BatchMode=yes "pifinder@${PI_IP}" "echo ok" 2>/dev/null; then + echo "Pi is running — halting..." + ssh "pifinder@${PI_IP}" "echo solveit | sudo -S poweroff" 2>/dev/null || true + echo "Waiting for Pi to go down..." + sleep 3 + while ping -c1 -W1 "${PI_IP}" &>/dev/null; do sleep 1; done + echo "Pi is down" +else + echo "Pi not reachable, proceeding" +fi + +# ── Backup SSH host keys ───────────────────────────────────────────────────── + +echo "Backing up SSH host keys..." +ssh "${PROXNIX}" "sudo cp -a ${NFS_ROOT}/etc/ssh/ssh_host_* /tmp/ 2>/dev/null || true" + +# ── Copy nix store closure to NFS ──────────────────────────────────────────── + +echo "Copying nix store closure to NFS..." +ssh "${PROXNIX}" "sudo mkdir -p ${NFS_ROOT}/nix/store" + +# Get list of store paths and stream via tar (fast, handles duplicates via overwrite) +STORE_PATHS=$(nix path-info -r "$CLOSURE") +TOTAL_PATHS=$(echo "$STORE_PATHS" | wc -l) +echo "Streaming ${TOTAL_PATHS} store paths via tar..." + +# Rsync store paths with -R to preserve directory structure +# shellcheck disable=SC2086 +rsync -avR --rsync-path="sudo rsync" $STORE_PATHS "${PROXNIX}:${NFS_ROOT}/" +echo "Transfer complete" + +# ── Set up NFS root directory structure ────────────────────────────────────── + +echo "Setting up NFS root directory structure..." +ssh "${PROXNIX}" "sudo bash -euo pipefail" << SETUP +# Create standard directories (bin/usr are symlinks, not dirs) +mkdir -p ${NFS_ROOT}/{etc/ssh,home/pifinder/.ssh,root/.ssh,var,tmp,proc,sys,dev,run,boot} +chmod 1777 ${NFS_ROOT}/tmp + +# Symlinks from NixOS system (remove existing dirs/symlinks first) +rm -rf ${NFS_ROOT}/bin ${NFS_ROOT}/usr +ln -sfT ${CLOSURE}/sw/bin ${NFS_ROOT}/bin +ln -sfT ${CLOSURE}/sw ${NFS_ROOT}/usr + +# /etc/static points to the NixOS etc derivation (required for PAM, etc.) +ln -sfT ${CLOSURE}/etc ${NFS_ROOT}/etc/static + +# Critical /etc symlinks that NixOS activation would normally create +rm -rf ${NFS_ROOT}/etc/pam.d 2>/dev/null || true +ln -sfT /etc/static/pam.d ${NFS_ROOT}/etc/pam.d +ln -sfT /etc/static/bashrc ${NFS_ROOT}/etc/bashrc +# passwd/shadow/group are created as real files later (need to be writable for netboot) +rm -f ${NFS_ROOT}/etc/passwd ${NFS_ROOT}/etc/shadow ${NFS_ROOT}/etc/group 2>/dev/null || true +ln -sfT /etc/static/sudoers ${NFS_ROOT}/etc/sudoers 2>/dev/null || true +ln -sfT /etc/static/sudoers.d ${NFS_ROOT}/etc/sudoers.d 2>/dev/null || true +ln -sfT /etc/static/nsswitch.conf ${NFS_ROOT}/etc/nsswitch.conf 2>/dev/null || true +ln -sfT /etc/static/systemd ${NFS_ROOT}/etc/systemd 2>/dev/null || true +ln -sfT /etc/static/polkit-1 ${NFS_ROOT}/etc/polkit-1 2>/dev/null || true + +# Create nix profile symlinks +mkdir -p ${NFS_ROOT}/nix/var/nix/profiles +ln -sfT ${CLOSURE} ${NFS_ROOT}/nix/var/nix/profiles/system +ln -sfT ${CLOSURE} ${NFS_ROOT}/run/current-system 2>/dev/null || true +SETUP + +# ── Restore SSH host keys ──────────────────────────────────────────────────── + +echo "Restoring/generating SSH host keys..." +ssh "${PROXNIX}" "bash -euo pipefail -c ' +if ls /tmp/ssh_host_* >/dev/null 2>&1; then + sudo cp -a /tmp/ssh_host_* ${NFS_ROOT}/etc/ssh/ + echo \"Restored existing host keys\" +else + sudo ssh-keygen -A -f ${NFS_ROOT} + echo \"Generated new host keys\" +fi +'" + +# ── Link NixOS /etc files ──────────────────────────────────────────────────── + +echo "Linking NixOS etc files..." +ssh "${PROXNIX}" "sudo bash -euo pipefail -c ' +ln -sf /etc/static/ssh/sshd_config ${NFS_ROOT}/etc/ssh/sshd_config +ln -sf /etc/static/ssh/ssh_config ${NFS_ROOT}/etc/ssh/ssh_config 2>/dev/null || true +ln -sf /etc/static/ssh/moduli ${NFS_ROOT}/etc/ssh/moduli 2>/dev/null || true +# pam.d already symlinked to /etc/static/pam.d in SETUP block +'" + +# ── Static user files ──────────────────────────────────────────────────────── + +echo "Creating static user files..." + +ssh "${PROXNIX}" "sudo tee ${NFS_ROOT}/etc/passwd > /dev/null" << 'PASSWD' +root:x:0:0:System administrator:/root:/run/current-system/sw/bin/bash +pifinder:x:1000:100::/home/pifinder:/run/current-system/sw/bin/bash +nobody:x:65534:65534:Unprivileged account:/var/empty:/run/current-system/sw/bin/nologin +sshd:x:993:993:SSH daemon user:/var/empty:/run/current-system/sw/bin/nologin +avahi:x:994:994:Avahi daemon user:/var/empty:/run/current-system/sw/bin/nologin +gpsd:x:992:992:GPSD daemon user:/var/empty:/run/current-system/sw/bin/nologin +PASSWD + +ssh "${PROXNIX}" "sudo tee ${NFS_ROOT}/etc/group > /dev/null" << 'GROUP' +root:x:0: +wheel:x:1:pifinder +users:x:100:pifinder +kmem:x:9:pifinder +input:x:174:pifinder +nobody:x:65534: +spi:x:996:pifinder +i2c:x:997:pifinder +gpio:x:998:pifinder +dialout:x:995:pifinder +video:x:994:pifinder +networkmanager:x:993:pifinder +sshd:x:993: +avahi:x:994: +gpsd:x:992: +GROUP + +ssh "${PROXNIX}" "echo 'root:${SHADOW_HASH}:1:::::: +pifinder:${SHADOW_HASH}:1:::::: +nobody:!:1:::::: +sshd:!:1:::::: +avahi:!:1:::::: +gpsd:!:1::::::' | sudo tee ${NFS_ROOT}/etc/shadow > /dev/null" + +run_proxnix "sudo chmod 644 ${NFS_ROOT}/etc/passwd ${NFS_ROOT}/etc/group" +run_proxnix "sudo chmod 640 ${NFS_ROOT}/etc/shadow" + +# ── SSH authorized_keys ────────────────────────────────────────────────────── + +echo "Setting up SSH authorized_keys..." +ssh "${PROXNIX}" "echo '${SSH_PUBKEY}' | sudo tee ${NFS_ROOT}/home/pifinder/.ssh/authorized_keys > /dev/null" +ssh "${PROXNIX}" "echo '${SSH_PUBKEY}' | sudo tee ${NFS_ROOT}/root/.ssh/authorized_keys > /dev/null" +run_proxnix "sudo chown -R 1000:100 ${NFS_ROOT}/home/pifinder" +run_proxnix "sudo chmod 700 ${NFS_ROOT}/home/pifinder/.ssh ${NFS_ROOT}/root/.ssh" +run_proxnix "sudo chmod 600 ${NFS_ROOT}/home/pifinder/.ssh/authorized_keys ${NFS_ROOT}/root/.ssh/authorized_keys" + +# ── PiFinder symlink ───────────────────────────────────────────────────────── + +echo "Setting up PiFinder directory..." +# Find pifinder-src from the current closure (not just any old one in the store) +PFSRC_REL=$(nix path-info -r "$CLOSURE" | grep pifinder-src | head -1) +echo "PiFinder source from closure: $PFSRC_REL" +ssh "${PROXNIX}" "sudo bash -euo pipefail -c ' +PFSRC=\"${NFS_ROOT}${PFSRC_REL}\" +if [ ! -d \"\$PFSRC\" ]; then + echo \"ERROR: pifinder-src not found: \$PFSRC\" + exit 1 +fi +PFHOME=${NFS_ROOT}/home/pifinder/PiFinder + +echo \"PiFinder source: ${PFSRC_REL}\" + +[ -L \"\$PFHOME\" ] && rm \"\$PFHOME\" +[ -d \"\$PFHOME\" ] && rm -rf \"\$PFHOME\" + +ln -sfT \"${PFSRC_REL}\" \"\$PFHOME\" + +mkdir -p ${NFS_ROOT}/home/pifinder/PiFinder_data +chown 1000:100 ${NFS_ROOT}/home/pifinder/PiFinder_data +'" + +# ── Copy firmware to TFTP (from raspberrypi firmware package) ──────────────── + +echo "Copying firmware to TFTP..." +FW_PKG=$(nix build nixpkgs#raspberrypifw --print-out-paths --system aarch64-linux 2>/dev/null) +ssh "${PROXNIX}" "sudo mkdir -p ${TFTP_ROOT}" + +# Copy firmware files +rsync -avz "${FW_PKG}/share/raspberrypi/boot/"*.{elf,dat,bin,dtb} "${PROXNIX}:/tmp/fw/" +ssh "${PROXNIX}" "sudo cp /tmp/fw/* ${TFTP_ROOT}/ && rm -rf /tmp/fw" + +# Copy custom u-boot with network boot priority +UBOOT=$(nix build .#packages.aarch64-linux.uboot-netboot --print-out-paths --system aarch64-linux 2>/dev/null) +echo "Using custom u-boot: $UBOOT" +rsync -avz "${UBOOT}/u-boot.bin" "${PROXNIX}:/tmp/u-boot-rpi4.bin" +ssh "${PROXNIX}" "sudo mv /tmp/u-boot-rpi4.bin ${TFTP_ROOT}/" + +# ── Copy kernel, initrd, DTBs to TFTP ──────────────────────────────────────── + +echo "Copying kernel/initrd/DTBs to TFTP..." +ssh "${PROXNIX}" "sudo mkdir -p ${TFTP_ROOT}/nixos" +rsync -avz "${KERNEL}" "${PROXNIX}:/tmp/${KERNEL_NAME}" +rsync -avz "${INITRD}" "${PROXNIX}:/tmp/${INITRD_NAME}" +ssh "${PROXNIX}" "sudo mv /tmp/${KERNEL_NAME} /tmp/${INITRD_NAME} ${TFTP_ROOT}/nixos/" + +# Copy NixOS-built DTBs (with camera overlay baked in) to dtbs/ subdirectory +ssh "${PROXNIX}" "sudo mkdir -p ${TFTP_ROOT}/dtbs" +rsync -avz "${DTBS}/broadcom/" "${PROXNIX}:/tmp/dtbs/" +ssh "${PROXNIX}" "sudo cp /tmp/dtbs/*.dtb ${TFTP_ROOT}/dtbs/ && sudo rm -rf /tmp/dtbs" + +# Copy overlays from kernel package +KERNEL_DIR=$(dirname "$KERNEL") +rsync -avz "${KERNEL_DIR}/dtbs/overlays/" "${PROXNIX}:/tmp/overlays/" +ssh "${PROXNIX}" "sudo rm -rf ${TFTP_ROOT}/overlays && sudo mv /tmp/overlays ${TFTP_ROOT}/" + +# ── Write config.txt for u-boot ────────────────────────────────────────────── + +echo "Writing config.txt..." +ssh "${PROXNIX}" "sudo tee ${TFTP_ROOT}/config.txt > /dev/null" << CONFIG +[pi4] +kernel=u-boot-rpi4.bin +enable_gic=1 +armstub=armstub8-gic.bin + +disable_overscan=1 +arm_boost=1 + +[all] +arm_64bit=1 +enable_uart=1 +avoid_warnings=1 +CONFIG + +# ── Generate extlinux/extlinux.conf ──────────────────────────────────────────── + +echo "Generating extlinux/extlinux.conf..." +ssh "${PROXNIX}" "sudo mkdir -p ${TFTP_ROOT}/extlinux && sudo tee ${TFTP_ROOT}/extlinux/extlinux.conf > /dev/null" << EXTLINUX +TIMEOUT 10 +DEFAULT nixos-default + +LABEL nixos-default + MENU LABEL NixOS - Default + LINUX /nixos/${KERNEL_NAME} + INITRD /nixos/${INITRD_NAME} + FDTDIR /dtbs + APPEND init=${INIT_PATH} ip=dhcp console=ttyS0,115200n8 console=ttyAMA0,115200n8 console=tty0 loglevel=4 +EXTLINUX + +# ── Create pxelinux.cfg for faster MAC-based boot ───────────────────────────── + +echo "Creating pxelinux.cfg/01-${PI_MAC}..." +ssh "${PROXNIX}" "sudo mkdir -p ${TFTP_ROOT}/pxelinux.cfg && sudo ln -sf ../extlinux/extlinux.conf ${TFTP_ROOT}/pxelinux.cfg/01-${PI_MAC}" + +# ── Clean up old artifacts ─────────────────────────────────────────────────── + +echo "Cleaning up old artifacts..." +ssh "${PROXNIX}" "sudo rm -f ${TFTP_ROOT}/cmdline.txt ${TFTP_ROOT}/nixos/patched-initrd 2>/dev/null || true" +ssh "${PROXNIX}" "sudo rm -f /tmp/ssh_host_*" + +# ── Restart TFTP ───────────────────────────────────────────────────────────── + +echo "Restarting TFTP server..." +ssh "${PROXNIX}" "sudo systemctl start atftpd.service" + +# ── Verification ───────────────────────────────────────────────────────────── + +echo "" +echo "==========================================" +echo "VERIFYING DEPLOYMENT CONSISTENCY" +echo "==========================================" +VERIFY_FAILED=0 + +echo -n "Checking u-boot... " +if ssh "${PROXNIX}" "test -f ${TFTP_ROOT}/u-boot-rpi4.bin"; then + echo "OK" +else + echo "FAILED" + VERIFY_FAILED=1 +fi + +echo -n "Checking config.txt... " +if ssh "${PROXNIX}" "grep -q 'kernel=u-boot-rpi4.bin' ${TFTP_ROOT}/config.txt"; then + echo "OK" +else + echo "FAILED" + VERIFY_FAILED=1 +fi + +echo -n "Checking extlinux/extlinux.conf... " +if ssh "${PROXNIX}" "test -f ${TFTP_ROOT}/extlinux/extlinux.conf"; then + echo "OK" +else + echo "FAILED" + VERIFY_FAILED=1 +fi + +echo -n "Checking kernel... " +if ssh "${PROXNIX}" "test -f ${TFTP_ROOT}/nixos/${KERNEL_NAME}"; then + echo "OK" +else + echo "FAILED" + VERIFY_FAILED=1 +fi + +echo -n "Checking initrd... " +if ssh "${PROXNIX}" "test -f ${TFTP_ROOT}/nixos/${INITRD_NAME}"; then + echo "OK" +else + echo "FAILED" + VERIFY_FAILED=1 +fi + +echo -n "Checking NFS closure... " +if ssh "${PROXNIX}" "test -f ${NFS_ROOT}${INIT_PATH}"; then + echo "OK" +else + echo "FAILED" + VERIFY_FAILED=1 +fi + +echo -n "Checking PiFinder symlink... " +PFSRC_TARGET=$(ssh "${PROXNIX}" "readlink ${NFS_ROOT}/home/pifinder/PiFinder 2>/dev/null || true") +if [ -n "$PFSRC_TARGET" ] && ssh "${PROXNIX}" "test -d ${NFS_ROOT}${PFSRC_TARGET}/python"; then + echo "OK" +else + echo "FAILED" + VERIFY_FAILED=1 +fi + +echo "==========================================" + +if [ $VERIFY_FAILED -eq 1 ]; then + echo "=== DEPLOY FAILED VERIFICATION — DO NOT BOOT ===" + exit 1 +fi + +echo "=== Deploy complete and verified ===" +echo "" +echo "Boot chain: Pi firmware → u-boot → extlinux/extlinux.conf → NFS root" +echo "To boot the Pi: power cycle it" diff --git a/docs/adr/0023-sqm-per-frame-optical-black.md b/docs/adr/0023-sqm-per-frame-optical-black.md new file mode 100644 index 000000000..752a61099 --- /dev/null +++ b/docs/adr/0023-sqm-per-frame-optical-black.md @@ -0,0 +1,60 @@ +# Per-frame optical black as the IMX290/IMX462 SQM pedestal + +## Decision + +On IMX290/IMX462 the SQM pedestal is the sensor's own shielded optical-black +(OB) rows, measured on every frame, rather than a static profile offset or a +nightly-fitted dark-current model. + +The IMX290/462 already transmits ten front vertical OB rows per frame. A kernel +patch adds a second sensor source pad (`MEDIA_BUS_FMT_SENSOR_DATA`) so those +rows reach the receiver as a separate metadata stream without changing the +1920x1080 image matrix. A libcamera cam-helper unpacks the shielded pixels, +trims the outer 5% each side, averages the central 90% and publishes the result +through `controls::SensorBlackLevels` on the 16-bit scale, tagging it +`{level, level, level, level + 1}`. The one-count sentinel in the fourth +channel distinguishes a measured value from libcamera's static tuning tuple. +`camera_pi` converts a marked value back to native ADU and attaches it to the +radiometer sample as `optical_black_pedestal`. + +A valid marked OB value is the complete per-frame pedestal: it already contains +the bias and the frame's accumulated dark signal. Pedestal precedence is +therefore: valid same-frame OB, then a user-calibrated pedestal, then the +profile `bias_offset`. No dark-current rate is applied on top of OB and no +nightly rate is fitted or persisted for these sensors. + +## Status + +Accepted for IMX462 (and IMX290, same driver). Supersedes the earlier +scheduled-pedestal-probe proposal, which is not implemented: same-frame OB makes +scheduled probe frames unnecessary on these sensors. + +## Rationale + +Sony documents OB as the reference zero for image signals, but documentation +alone did not prove OB dark accumulation matches active-pixel dark accumulation +on this stack. A same-frame cupboard test on mr2 (IMX462, production gain, +requested 30 / reported 29.512) settled it: comparing normal Bayer pixels and +shielded OB rows from identical frames, the active-green and OB +dark-accumulation slopes agreed to well under 1 ADU/s, with active green a fixed +~0.8-1.0 ADU below OB (~0.01 mag). That residual is too small to justify a +per-unit constant from one camera and is left unmodelled. + +A same-frame measurement strictly dominates a once-per-night model: it tracks +bias and accumulated dark signal live, with no user action. The rolling +radiometer median smooths gain-30 frame noise without storing a fitted rate. +Central-90% averaging (not a whole-code median) preserves sub-ADU resolution, +which matters because the exposure-dependent dark signal is small. + +## Consequences + +- IMX462 SQM is zero-touch: no lens cap, dark frames, or calibration wizard. +- Manual calibration remains the fallback for sensors without usable OB and for + frames where OB is missing or unmarked; it never overrides valid OB. +- The patched kernel is built via `nixos-hardware`; `pifinder-fast` / + `pifinder-kernel-cross` provide a fast x86_64 cross build to seed the binary + cache so CI substitutes the kernel rather than compiling it. +- Added camera-process cost is about +0.23 percentage points of one core. +- Open: IMX296 OB uses a different CSI line-type path; IMX477 OB is not yet + proved accessible in this stack. Independent-unit and temperature-range + validation of IMX462 remains useful but is not required for users. diff --git a/docs/adr/0036-delta-updates-on-demand-differ.md b/docs/adr/0036-delta-updates-on-demand-differ.md new file mode 100644 index 000000000..6dadfdfd8 --- /dev/null +++ b/docs/adr/0036-delta-updates-on-demand-differ.md @@ -0,0 +1,67 @@ +# Updates transfer byte-level NAR deltas, computed on demand beside the cache + +A NixOS store path is downloaded whole, and its name contains the hash of its +inputs, so a one-line source edit renames — and re-downloads — hundreds of +paths whose bytes barely changed. Measured on real CI build pairs, ~255 MiB of +"changed" store paths differ by ~1.5 MiB of actual content (0.6%). Devices +update over phone hotspots in the field; bytes on the wire should track the +real content difference between any two versions. + +The upgrade therefore prefetches patches before nix downloads anything +(`delta_updates.py`, called from `nixos_upgrade.py`): for each missing path it +names the newest same-stem paths it already holds — across all retained +generations — and a server (`pifinder-differ`, running beside the Attic cache) +answers with a `zstd --patch-from` patch between the two paths' NARs. The +device reconstructs the target NAR from `nix-store --dump` of its base +(canonical on both ends), verifies sha256 **before** `nix-store --import` +(import does not check the NAR against the path name), and assembles the +import framing locally from the response's references and deriver. Pairs are +computed once, on first request, and cached forever; the server pre-warms +predictable pairs in the background. Requests are budgeted per update: the +device opens a session naming its target toplevel and the server sizes the +request budget from that closure. + +## Considered Options + +- **Pre-compute all pairs in CI, serve static files.** Cannot cover arbitrary + version pairs (n² at hundreds of releases) and couples every release to a + patch-build step. Rejected as the primary mechanism; it survives as the + server's self-warming, which needs no CI involvement at all. +- **Styx (lazy chunk substitution via EROFS/fscache).** Purpose-built, but + experimental, kernel-resident in the boot path, and lazy fetch is wrong for + a telescope that must work offline: it would need a "pull everything" + pass that discards its main advantage and keeps its risk. +- **Content-defined chunking (casync/desync/bita).** Base-agnostic and + CDN-friendly, but has a chunk-sized floor (~64 KiB): a Nix hash rewrite + touches a few bytes in thousands of files, dirtying nearly every chunk. + Weakest exactly on the dominant case. (The differ still uses Attic's + FastCDC chunk lists — as a free similarity index for ranking candidate + bases, not as the transfer unit. Data packs, whose files do not change + with each build, do use chunks as the transfer unit: see ADR 0040.) +- **Content-addressed derivations.** Removes rebuild fan-out only for + bit-identical rebuilds; helps nothing on a real code change. Complementary, + not a transport. +- **Per-IP rate limiting on the server.** Fails both directions: devices + sharing a hotspot NAT starve each other, attackers rotate addresses. + Replaced by per-update session budgets derived from the target closure's + size in the cache database — inflatable by nobody, fair behind NAT. + +## Consequences + +- **Off by default.** `pifinder.deltaUrl = ""` disables the entire path; every + failure (server down, bad patch, disk full, corrupt base, exhausted budget) + falls back to a normal binary-cache download, per path. The delta layer can + only reduce downloads, never block an upgrade. +- The sha256-before-import check is load-bearing. A patch applied without it + can register a corrupt path as valid. Never import an unverified stream. +- Patching needs base NAR + patch + reconstructed NAR on disk at once + (~2× NAR size) and `2^window_log` bytes of decode memory. The device caps + `window_log` at 28 (256 MiB); paths larger than the cap fall back to full + download. +- The server is a new operational component (loopback service behind a Caddy + vhost, `deltas.pifinder.eu`). It reads Attic's SQLite DB and NAR bytes, so + it inherits Attic's availability — and Attic's retention holes: a path GC'd + from the cache simply cannot be patched, which degrades per path by design. +- Delta bases are whatever old generations the device retains; GC policy on + the device is therefore part of the bandwidth story, not just the rollback + story. diff --git a/docs/adr/0037-nixos-builds-cache-and-update-channels.md b/docs/adr/0037-nixos-builds-cache-and-update-channels.md new file mode 100644 index 000000000..ec517d71d --- /dev/null +++ b/docs/adr/0037-nixos-builds-cache-and-update-channels.md @@ -0,0 +1,44 @@ +# NixOS builds come from a self-hosted Attic cache; the Pi installs them through three update channels + +A NixOS PiFinder runs only prebuilt store paths. It never compiles: a build on a Pi takes hours, and Rust crates alone are too slow. So CI builds every system, and the Pi downloads it from a binary cache. + +**Cache.** We host the [Attic](https://github.com/zhaofengli/attic) cache at `cache.pifinder.eu`. It has two caches with different retention: + +- `pifinder`: CI builds, PR builds and beta prereleases. Old paths are garbage-collected. +- `pifinder-release`: stable releases. Garbage collection is off, so a release stays installable for ever. + +Each cache has its own signing key. The Pi trusts both keys and `cache.nixos.org`. Attic stores each NAR as FastCDC chunks and keeps each chunk once, across both caches. This makes the storage and the CI upload small. Attic serves whole NARs to the Nix client, so the Pi does not get chunk deltas from Attic itself. [ADR 0036](./0036-delta-updates-on-demand-differ.md) adds deltas for system paths, and [ADR 0040](./0040-data-packs.md) adds chunk transfer for data packs. + +**Channels.** The Pi offers three channels. Each resolves through the update manifest (`update-manifest.json` on the `nixos-manifest` branch) to a store path: + +- **stable:** official GitHub Releases, not prereleases, from the version gate on. Pushed to `pifinder-release`. +- **beta:** GitHub prereleases cut from `main`. Curated like stable (notes, semver, version gate), but pushed to `pifinder`, so a beta is installable only while its closure is not garbage-collected. +- **unstable:** the trunk head plus open PRs with the `testable` label. The trunk row shows in bold. Until the NixOS line is mainline, the trunk is the `nixos` branch of the fork (`source_ref == "nixos"`). + +The Pi installs a pick with `nix build --max-jobs 0`, so it downloads and never builds. + +**Recovery from a bad build.** There is no fleet-wide automatic revert. A bad build is recovered in three ways: + +1. The boot watchdog rolls back a generation that fails its first boots ([ADR 0038](./0038-boot-watchdog-and-recovery.md)). +2. The user reinstalls an older build from its channel. For stable this always works. +3. A bad release is yanked: it is demoted or superseded, so new installs do not get it. A Pi that runs it shows an advisory. + +## Considered options + +- **Stay on cachix.org, rejected.** Quota limits, and no chunk dedup, so the cost grows with each closure. +- **Magic Nix Cache alone, rejected.** It is a CI cache in GitHub Actions storage. It cannot serve devices. +- **nix-casync, rejected.** The same chunk idea, but a tool, not a complete server. +- **harmonia, rejected.** Simpler, but without chunk dedup. +- **beta as the live `main` head, rejected.** GitHub prereleases keep beta curated like stable. Continuous delivery is the job of unstable. +- **stable as the `release` branch head, rejected.** It loses release notes, versions, the version gate and the release assets. +- **An active kill switch for yanked builds, rejected for now.** A passive yank plus an advisory needs no server list and no polling. + +## Consequences + +- We operate one small server: Attic (one Rust binary, SQLite, local disk, Caddy with Let's Encrypt). Backup is a snapshot of the SQLite file and the chunk directory. +- CI pushes with `attic push` and a long-lived token (`secrets.ATTIC_TOKEN`). The upload holds only new chunks. +- If `cache.pifinder.eu` is down, the Pi still gets every path that `cache.nixos.org` has. Only our own paths (patched kernel, `cedar-detect-server`, Python packages) wait for our cache. +- Rollback by reinstall is guaranteed only for stable. beta and unstable closures can be garbage-collected, and then that build cannot install until CI pushes it again. +- The update manifest is the single mapping from versions to store paths. The first boot after the migration reads it too ([ADR 0039](./0039-card-layout-and-migration.md)). + +Replaces NixOS ADR 0001 (Attic cache) and 0002 (update channels and rollback). diff --git a/docs/adr/0038-boot-watchdog-and-recovery.md b/docs/adr/0038-boot-watchdog-and-recovery.md new file mode 100644 index 000000000..5a3cf325e --- /dev/null +++ b/docs/adr/0038-boot-watchdog-and-recovery.md @@ -0,0 +1,31 @@ +# A self-arming boot watchdog rolls back failed trials; recovery mode is the update screen alone (proposed) + +**Watchdog (in use, `pifinder-watchdog.service`).** A generation is a **trial** until it passes one boot health check. The health check passes when the app itself declares that its UI is live (systemd READY from the first drawn frame) and then stays up for a short time. A passed trial **confirms** the generation, and a ledger on the Pi records it (`/var/lib/pifinder/confirmed-generations`). Each boot of a generation that is not confirmed is a trial, whichever build installed it. So the protection does not depend on the code of the previous system. A trial that fails rolls back to the newest confirmed generation, captures the journal to `PiFinder_data`, and tells the user on the screen. + +The watchdog never rolls back a confirmed generation. A cold night or a slow SD read must not downgrade a Pi that worked. If a confirmed generation's app fails, the watchdog only shows an advisory that names the recovery hold. + +**Recovery mode (proposed, not built).** Holding the square-equivalent input at power-on starts a stripped app with only the update screen: display and keypad, no camera, solver or positioning. It shows the local generations, marks the confirmed ones, and offers the internet channels. A generation pick is sticky: it becomes the boot default. An internet pick installs through the normal upgrade and faces a normal trial. If recovery mode itself fails its health check, the Pi falls back to a blind rollback to the newest confirmed generation. Today only the advisory text exists (`nixos/services.nix`), and no code detects the hold. + +## Considered options + +- **Trial only when the upgrade writes a marker, rejected.** The first design. A Pi upgraded by an older build that did not write the marker got one unprotected boot. On 2026-07-03 the first v3.0.0-beta looped this way with no rollback. +- **Roll back on any repeated boot failure, rejected.** A transient failure would downgrade a confirmed build without a reason. +- **A separate minimal recovery tool, rejected.** A second UI with its own generation list and install code, which would age apart from the real one. +- **Blind rollback only, rejected.** The user often wants a specific version or a fresh install from a channel. + +## Consequences + +- The marker that the upgrade writes (`/var/lib/pifinder/trial-generation.json`) is only a hint. It names the exact system before the upgrade, camera specialisation included. The ledger is what counts. Loss of the ledger is harmless: a healthy generation confirms again. +- A failing trial with no generation to roll back to (a first install) shows a failure message and stays up for rescue, and it does not loop. +- The watchdog runs only after the root file system is mounted. A build that stops in the kernel or the initrd never reaches it. On 2026-09-26 a CM4 stopped in the initrd this way, and recovery needed a change of `extlinux.conf` on the card. **The U-Boot boot counter** closes this gap (`nixos/pkgs/uboot-sd.nix`, `pifinder-bootcount` in `nixos/services.nix`): + - U-Boot keeps a 4-byte file, `pifinder.bootcount`, on the FAT partition: magic, version, count and `upgrade_available` (U-Boot `BOOTCOUNT_FS`). With `upgrade_available=0`, U-Boot neither counts nor writes. + - Before the reboot into a trial, the upgrade sets `upgrade_available=1` and writes `pifinder-fallback.env` with the extlinux entry of the system that runs now (`pxe_label_override=nixos--`). + - Each boot of the trial counts. Above `bootlimit` (3), U-Boot runs `altbootcmd`: it imports `pifinder-fallback.env` and boots that entry. + - The kernel parameters `boot.panic_on_fail panic=10` restart the Pi after a failure in the initrd or a kernel panic, so the count goes up without a hand on the power switch. A hang with no panic still needs power cycles. + - The watchdog stops the counter on each healthy boot. When it finds the counter on while a confirmed generation runs that is not the profile's generation, U-Boot has fallen back: the watchdog makes the running generation the default again and writes `upgrade_failed.json`. + - `pifinder-uboot-update` puts the U-Boot of the build on the FAT partition when it differs, only from a confirmed generation, and keeps the replaced one as `u-boot-rpi4.bin.old`. + - Chosen over Raspberry Pi `tryboot`, which works on partitions and would force an A/B layout, and over a counter in the U-Boot environment (`BOOTCOUNT_ENV`): a saved environment replaces the built-in one, `bootcmd` included, and an older U-Boot would read a partial file. + - Risk: a new U-Boot that does not start stops the device before any rollback. The `.old` copy then goes back with a card reader. +- The upgrade and the first boot refuse a build that cannot mount the root of the Pi ([ADR 0039](./0039-card-layout-and-migration.md)). That closes the cause of the 2026-09-26 failure. + +Replaces NixOS ADR 0005 (watchdog) and 0006 (recovery mode). diff --git a/docs/adr/0039-card-layout-and-migration.md b/docs/adr/0039-card-layout-and-migration.md new file mode 100644 index 000000000..bad52af8a --- /dev/null +++ b/docs/adr/0039-card-layout-and-migration.md @@ -0,0 +1,80 @@ +# A NixOS card is FAT firmware plus a btrfs root; the migration converts the Raspbian root in place + +**Status:** decided 2026-09-26. The system is btrfs-only on `nixos`. The migration and the SD images still write ext4 `NIXOS_SD`, and the plan in `docs/ax/nixos/btrfs-and-data-packs-plan.md` changes them. + +## Card layout + +Every NixOS PiFinder card has two partitions: + +- **Partition 1:** FAT, label `FIRMWARE`. It holds only what the boot ROM and the GPU firmware must read: `config.txt`, `start*.elf`, the DTBs, the armstub and U-Boot. The boot ROM reads only FAT, so this partition must stay. It is written at install or migration, and again only by a firmware or U-Boot update. +- **Partition 2:** btrfs, label `PIFINDER_SD`. It holds everything else, including `/boot` with `extlinux.conf`, the kernels and the initrds. U-Boot reads them with `sysboot mmc 0:2`. + +We use btrfs for the root because: + +- it checksums data and metadata, so it finds a corrupt block and does not return it; +- its copy-on-write updates leave a file old or new after a power cut. `/boot` changes on each generation switch, so this matters; +- it gives reflink copies, compression and subvolume snapshots. The migration and the data packs use them ([ADR 0040](./0040-data-packs.md)). + +The root is mounted as `/dev/mmcblk0p2`, not by label. The SD card and the eMMC of the Pi 4 and the CM4 are both `mmcblk0`. + +`/home/pifinder/PiFinder_data` is its own subvolume. Everything else is on the top level. The system needs no subvolume, because NixOS generations give it rollback. + +## Migration + +The migration moves a Raspbian PiFinder to NixOS once. A Raspbian card runs ext4 and stays on 2.6.4 until it migrates. So no NixOS system needs ext4. + +1. **Trigger:** the Software screen offers the migration when the flag `nixos_migration` in `migration_gate.json` on the upstream `release` branch is true. Pressing square 7 times offers it without the gate. Pi OS up to 2.6.3 reads only the old flag `nixos_for_everyone`, which stays false, so such a Pi must update to a version with the btrfs migration first. +2. **Prepare (Raspbian):** download the migration tarball of the chosen release, check its sha256, build a migration initramfs on the boot partition, add it to `config.txt`, and reboot. +3. **Convert (initramfs):** `btrfs-convert` changes partition 2 from ext4 to btrfs in place, so the files stay, `PiFinder_data/catalog_images` included. The initramfs then: + - creates the `PiFinder_data` subvolume and reflink-copies the kept data into it; + - deletes the Raspbian system files; + - extracts the NixOS system from the tarball; + - grows the file system if the partition was not grown; + - formats partition 1 as FAT `FIRMWARE` and copies the firmware. + + The partition table stays as it is, so the FAT partition keeps its Raspbian size (256 or 512 MB). +4. **First boot:** a minimal migration system boots. It reads the update manifest, takes the newest entry of the best channel (stable, then beta, then the unstable trunk), downloads that full system, switches to it and reboots. The minimal system carries a built-in target only as a fallback when the manifest cannot be read. +5. **Cleanup:** after the first confirmed generation, a service deletes the `ext2_saved` subvolume that `btrfs-convert` left for rollback. In the same boot a second service runs one balance of the chunks under 50 % use, at idle priority. There is no defragment: the only converted data left is `PiFinder_data`, nearly all JPEGs, which do not compress. The system files were written after the conversion and are btrfs extents with zstd already. + +**Tarball.** It holds the minimal migration system, not the full system, so it never goes stale: the full system comes from the manifest. CI builds it straight from the Nix closure (a `boot/` folder with the firmware and a `rootfs/` folder with the store paths), without an SD image and without a loop mount. It is published as an asset with a `.sha256` sidecar on each stable or beta release, and the manifest names it per entry as `migration_url`. + +## Considered options + +- **ext4 root (NixOS ADR 0007), superseded.** Atomic renames, but no checksums, reflinks or snapshots. +- **btrfs for everything, rejected.** The boot ROM cannot read btrfs. +- **Subvolumes for `/nix` and the system, rejected.** A snapshot of `/nix` holds gigabytes of old store paths, and generations already cover the system. +- **Root by label, rejected.** A build that names a label the card does not have stops in the initrd, before the watchdog runs. On 2026-09-26 a `NIXOS_SD` build left a `PIFINDER_SD` card with a black screen. +- **Format partition 2 with `mkfs.btrfs`, rejected.** Simpler, but it deletes the catalog images (up to 5 GB). They do not fit in RAM during a format. +- **Tarball cut from a loop-mounted SD image, rejected.** The image is only an intermediate step, and the loop mount needs `sudo` in CI. +- **Tarball with the full system, rejected.** About 1.4 GB per release, and it freezes the migrated version. +- **Tarball built once at a fixed URL, rejected.** It has no version, notes or checksum record. +- **A pinned store path in the tarball, rejected.** In the short-retention cache it is garbage-collected while the tarball is still published. In the retained cache, every test build stays for ever. + +## Consequences + +- The system supports only btrfs and vfat, and its initrd carries only btrfs. ext4 stays in the kernel config: removing it needs a kernel rebuild for a few kB. +- The upgrade refuses a build whose `etc/fstab` root does not match the mounted root (`check_root_mountable` in `nixos_upgrade.py`). `pifinder-first-boot` must make the same check. +- U-Boot must read btrfs, because `extlinux.conf` and the kernels are on partition 2. +- The SD images must create btrfs `PIFINDER_SD` with the `PiFinder_data` subvolume, so flashed and migrated cards are the same apart from the FAT size. +- The upgrade takes a read-only snapshot of `PiFinder_data` before it switches, into `/.snapshots/PiFinder_data--` on the same file system, and keeps the newest two. A failed snapshot only logs a warning. The restore is manual (below). + +## Restore of PiFinder_data from a snapshot + +There is no automatic restore: only a person can tell if the data after an upgrade is wrong. As root on the device: + +```sh +ls /.snapshots/ # pick the snapshot before the bad upgrade +systemctl stop pifinder +btrfs subvolume snapshot /.snapshots/PiFinder_data-