Skip to content

Install an SD A/B system

This experimental installer gives an N810 two replaceable SD operating-system slots, a shared persistent data partition, and an internal recovery system. Initial installation erases the selected card and internal 2 GB storage. It does not replace Nokia's bootloader. Hardware acceptance must be completed before treating a new build as a release.

Requirements

Build with Python 3.11 or newer, Git, Make, tar, and a Linux Docker engine. The container pins its base image, Debian snapshot, Python dependencies, kernel source, and compiler. No host ARM compiler is required. Give Docker at least 4 GiB RAM (8 GiB recommended) and 30 GiB free storage. Reserve at least 6 GiB for the default kit; on Docker Desktop reserve 40 GiB host free space for container growth and output. A card of at least 4 GB is required for the default 1536 MiB slots. Larger cards allocate the remaining space to persistent data.

The card writer supports native Linux and macOS. Windows and BSD can use a Linux machine with direct access to the card reader and tablet USB device; native raw-device installation on those hosts is not implemented.

Build and configure

From a clean, committed source checkout:

make n810-build-ab SSH_PUBLIC_KEY="$HOME/.ssh/id_ed25519.pub" \
  AB_KIT="$PWD/dist/n810-ab" N810_CONFIGURE=1
make n810-check-ab AB_KIT="$PWD/dist/n810-ab"

The interactive prompt collects optional Wi-Fi settings, service startup choices, and a login password. The supplied public key enables SSH. Credentials are private kit inputs; do not publish the kit or its persistent-data image. Radio receive, MeshCore, and Reticulum startup are opt-in. Device pairing, firmware, callsigns, and offline downloads remain separate setup operations.

Fresh installation

Connect only the intended N810 in Nokia update mode. Put its SD card into the host reader. Build the host flasher with make flasher. On Linux, install the host iproute2 tools and OpenSSH client. The installer configures only the network interface on the tablet USB port it identified; disk and network setup require root privileges or an authorized sudo session.

Check the card using make n810-write-ab AB_KIT=PATH N810_DISK=DEVICE. On macOS DEVICE is a whole /dev/diskN; on Linux it is /dev/sdX or /dev/mmcblkN. Run the same target with root privileges and N810_ERASE=1 to write and read back the card. This is a fresh-install operation, never an OS-update command.

Insert the verified card into the intended tablet and enter Nokia update mode. Use ab_install.py boot-sd --kit PATH --flasher PATH to load the temporary bootstrap kernel into RAM. Its filesystem and separately matched modules are on the card. It starts only a console and key-only USB SSH, not Pocket or radio services, and does not flash the kernel or write internal storage.

Use ab_install.py inspect --kit PATH --key SSH_PRIVATE_KEY to read the internal MMC identity. The host needs a USB address on the 169.254.0.0/16 subnet; the installer listens on 169.254.81.1, using the kit's pinned SD host key.

Write internal recovery using ab_install.py write-recovery --kit PATH --key SSH_PRIVATE_KEY --expected-cid CID --erase. The CID must be the one reported by the inspection. The writer verifies the isolated SD environment and read-only root, internal MMC type, capacity, identity, and mounted-state guards, then reads back every written byte.

Leave the SD inserted and USB connected to the same port. With the temporary installer still running, choose Install again in Pocket Setup, or run:

python3 platform/bootstrap/ab_install.py flash-recovery --kit PATH --flasher PATH --key SSH_PRIVATE_KEY

Use the host flasher from this checkout. If replacing an older build, build to a fresh directory with make flasher FLASHER_OUTPUT=PATH and pass its 0xFFFF executable. On macOS, replace an installed privileged helper with the one built for that binary.

The host checks the SD and recovery write receipts, starts watching the recorded USB port, verifies the running installer's internal storage identity over SSH, and requests a reboot. When the bootloader appears, the flasher checks for an RX-44 on that USB connection, writes the shared kernel, and requests the next boot. On the next boot, early internal startup waits up to 120 seconds for the configured card, prepares the selected slot and persistent mounts, and switches into that root filesystem before starting services. The kernel keeps running throughout; normal SD boot does not use kexec.

The USB icon and the A/B boot selection

With the N810 connected to the host over USB, the USB icon appears briefly during reboot. A host already listening can catch the Nokia bootloader during that window. Holding the front Swap key (the Home key, marked with two overlapping rectangles on the N810) at power-on keeps the tablet in update mode so the host has time to connect.

If the 45-second capture window expires, or the bootloader leaves before the flasher opens it, hold Swap at power-on and retry the same step. The host can use an already waiting bootloader. The attended CLI procedure also accepts flash-recovery without --key once the tablet is in update mode. If writing started and the result is uncertain, check the kit’s USB-OPERATIONS.log, RECOVERY-INSTALL.json, and the tablet’s boot before another attempt.

An ordinary A/B update takes a different path. On reboot the tablet starts its existing kernel, then early startup reads the slot selection from the SD card and mounts the chosen Debian filesystem. Switching slots needs no host at the USB icon and writes nothing to kernel flash.

Storage and updates

Location Purpose
SD partition 1 Boot selection and trial-attempt record.
SD partition 2 Read-only OS A and modules matching the flashed kernel.
SD partition 3 Read-only OS B and modules matching the flashed kernel.
SD partition 4 User homes, service state, network settings, and identities.
Internal 2 GB Recovery filesystem, USB SSH, console and repair tools.
Internal kernel flash Shared kernel for SD operation and internal recovery.

The OS mounts read-only. A persistent /etc overlay preserves edits and atomic file replacements while untouched configuration comes from the selected OS. The writable /var view starts from the selected OS defaults; declared configuration and service-state paths point to the data partition. User application state and downloads under home survive updates. Application binaries and package-manager metadata belong to the OS image. Files manually installed into the OS are not persistent application data.

For an update, copy a matching UPDATE.json and slot.ext4 into a directory on persistent storage, then run sudo n810-ab update --bundle DIRECTORY. The updater requires the exact flashed kernel build and data schema, refuses mounted slot targets, verifies the image and full readback, and selects the inactive slot for up to three trial boots. Reboot normally to select the trial during early startup. Updates never write the data partition, card partition table, or flashed kernel. A kernel change is a separate maintenance operation that must supply matching modules to recovery and both slots; ordinary OS updates cannot silently replace it.

The health check confirms a boot after persistent mounts, a read-only root, and a live fault-free GPU desktop are observed across three samples. An unconfirmed boot consumes one attempt; after three attempts, the next recovery boot selects the previously confirmed slot. A hard hang still requires a restart; autonomous watchdog recovery is not established. A five-minute health timeout leaves the boot unconfirmed rather than interrupting calibration.

Data-schema changes are rejected by the updater. They require a separate, backed-up migration compatible with the rollback policy. A/B images alone do not roll back shared database changes.

Development updates

Application changes can be tested without rebooting or replacing an OS slot. Stop Pocket through its service so the owner releases the display and GPU, apply the changed runtime files, then start Pocket again. On the read-only OS, a temporary bind mount can expose a verified development file from persistent storage. Keep the original file available underneath for rollback. Native library changes must also match the graphics release manifest checked by the launcher.

These temporary mounts disappear at reboot. Save changes in source and rebuild a kit after the development round, then test a normal slot update and boot. An in-place application test does not establish that a fresh image boots or that an update preserves data. Kernel and boot-layout changes need their own boot tests; ordinary Python, app and compatible library edits do not.

Recovery

With the card absent, the internal system remains available through USB SSH and the console after the bounded card-detection wait. A stay-in-recovery file on the card's control partition prevents SD boot. An administrator can also create /etc/n810-ab/stay-in-recovery on internal recovery to bypass card selection until that file is removed.

From the running SD system, sudo n810-ab stay-recovery makes the next normal reboot stop in recovery. Use sudo n810-ab resume-sd there to clear that request, then sudo n810-ab boot to reboot normally and select the SD root. sudo n810-ab status shows the confirmed slot, pending trial, and remaining attempts.

The kit records separate SSH host public keys for recovery and the SD system. Use recovery-known-hosts or slot-known-hosts with SSH's UserKnownHostsFile option. The SD identity persists across slot updates. The temporary SD installer uses that SD host identity and enables key-only root SSH only for the installation session. Normal slot boot retains its normal SSH policy.

The SD system creates a 512 MiB swapfile at /data/.swapfile on first boot. Both OS slots reuse it. Run cat /proc/swaps to check the two entries. Compressed RAM swap on /dev/zram0 has priority 100. The SD file has priority 10, so Linux uses it for overflow. Internal storage holds recovery.

Desktop crash recovery

An ordinary app callback failure stops that app and displays an error in its window. Press R to retry it. The desktop log records the app name, operation, and traceback. This boundary contains Python exceptions; native crashes and shared GPU failures can still end the desktop process.

After an unexpected desktop exit, the owner restores the display and releases the GPU before attempting one recovery launch. If cleanup fails, or the recovery launch also fails, it stays stopped instead of looping. The recovery desktop starts without restoring saved windows or their background effects. It shows the failure and the archived log path under /var/log/n810-pocket-native/.

In Desktop Recovery, press A to restore all saved apps, or select an app with the arrow keys and press Enter to restore just that app. S leaves recovery open so apps can be opened individually from Applications. Recovery protects the saved desktop from being overwritten. Press C only when ready to keep the current desktop and resume saving it.

The image build includes the Doom engine, bridge library, checksum-pinned Freedoom data, and their license notices. Games do not download dependencies at launch. Personal maps, radio identities, and optional third-party Symbian applications remain separately supplied data.

Optional offline maps and terrain

Prepare regional data using the map data guide. Keep raw GIS imports on the build host. The tablet needs the generated maps/, geography, hydrography and selected elevation packs, rather than the raw downloads.

In N810 Setup, open Storage, Wi-Fi and startup choices, select SD A/B, and enter the optional offline maps/elevation folder. Use the separate map views field only when those prepared files live outside that folder. Then choose Build kit from source. These host paths are build inputs; they are not saved in the tablet's configuration.

For make n810-build-ab, set REFERENCE_DATA and, if needed, REFERENCE_MAPS to those folders. To invoke the builder directly, add --reference-data /absolute/path/to/pocket/data to platform/bootstrap/build_ab_host.py. If the prepared legacy map views are kept separately, also pass --reference-maps /absolute/path/to/maps. The builder validates selected elevation tile checksums before building. It seeds the data partition once, increases its initial size to fit, and leaves the two system slots free of reference datasets. Reserve the normal build space plus three times the selected data size for staging and image output.

To install or refresh prepared data on an existing tablet, the installed n810-install-reference-data tool supports --source DIR --target DIR and --verify DIR. Run it as nokia with the target /home/nokia/.local/share/pocket. It preserves unrelated files and skips unchanged files. Its --stream mode writes a tar stream directly to standard output for transfer without an intermediate archive; --plan validates inputs and reports file count and size without installing anything. Restart Pocket after changing the selected data so its existing workers reopen the catalogue.

Prepared reference data can include map-overview.json, the 192 by 96 regional preview used by the overview loader. Importing the original filesystem's map folder also discovers its checksum-pinned preview beside the legacy runtime. The host builder mounts that file explicitly into the build container and seeds it with the reference data, so opening the sidebar does not regenerate regional terrain. build_ab_host.py --reference-overview FILE selects it explicitly.

Map display overviews and LOS use different sampling: rendering may use reduced levels, while path calculations use selected fine elevation. Missing coverage is unknown, never evidence of a clear path. A successful software LOS calculation is not a radio link test.

Sound

Fresh images include the ALSA utilities, the N810 audio helper, and a boot service that initializes the speakers at a quiet level. The nokia account belongs to the audio group. Both OS slots use modules built for the shared flashed kernel.

After boot, check the sound card and play a short test:

/usr/local/sbin/n810-audio status
/usr/local/sbin/n810-audio pcm-status
/usr/local/sbin/n810-audio play-test

The boot service checks the OMAP2420 McBSP2 device-tree configuration before enabling the test helper. If streaming is blocked, inspect sudo /etc/init.d/n810-audio start and dmesg; do not create an approval file manually. Older images need the matching kernel/device tree, machine driver, ALSA tools, and boot service together. Installing only alsa-utils does not repair an incompatible kernel configuration.

To capture five seconds from the internal microphone and listen to it:

/usr/local/sbin/n810-audio record-test "$HOME/audio-test.wav"
aplay -D hw:N810,0 "$HOME/audio-test.wav"
rm "$HOME/audio-test.wav"

Speaker playback and microphone capture are separate checks. ALSA reporting success does not establish that a speaker is audible or a recording is clear.