Raspberry Pi Connect Remote Updates: Complete Trixie Guide¶

Raspberry Pi Connect can now deliver updates to devices behind firewalls or temporarily offline. A queued update runs when the device reconnects. This guide starts with script artefacts for standard Raspberry Pi OS installations and explains when an A/B image is safer.

Choose the Update Model¶

Update type	Works with standard install	Automatic rollback	Best for
Script artefact with `otamaker`	Yes	No	Packages, configuration, service deployments
A/B image with `rpi-image-gen`	No; special initial image required	Yes	OS, partition, and appliance-style fleet updates

Script artefacts execute as root. A syntax error or unsafe package change can make a remote device unreachable, so staging is mandatory. A/B updates require physical preparation but can return to the previous slot after a failed boot. See the current Raspberry Pi Connect documentation.

Prepare a Trixie Device¶

Install Desktop Connect or Connect Lite plus OTA support:

sudo apt update
sudo apt install rpi-connect rpi-connect-ota
# For a headless device, use rpi-connect-lite instead of rpi-connect.

Enable, sign in, and opt in to remote updates:

rpi-connect on
rpi-connect signin
rpi-connect ota on
rpi-connect status
rpi-connect doctor

If remote shell must survive logout and reboot, enable lingering for the signed-in user:

1	`loginctl enable-linger`

Enable two-factor authentication for the Raspberry Pi ID. For a team, use Connect for Organisations and assign the minimum necessary role; only administrators should deploy artefacts.

Create an Idempotent Update Script¶

An update must be safe to run again. This example installs a package, writes a version marker atomically, and requests reboot only when required:

#!/bin/sh
set -eu

export DEBIAN_FRONTEND=noninteractive
version=1.0.0
marker=/var/lib/local-ota/example-version

if [ -r "$marker" ] && [ "$(cat "$marker")" = "$version" ]; then
    echo "version $version already applied"
    exit 0
fi

apt-get update
apt-get install -y --no-install-recommends jq

install -d -m 0755 "$(dirname "$marker")"
printf '%s\n' "$version" > "${marker}.new"
mv "${marker}.new" "$marker"

if [ -r /var/run/reboot-required ]; then
    exit 2
fi
exit 0

Connect interprets exit 0 as success, 1 as failure, and 2 as success followed by reboot. Avoid downloading and executing an unpinned latest script from inside the update.

Package with `otamaker`¶

Save the script as apply-update, make it executable, and create update.yaml:

artefact:
  name: example-maintenance
  version: 1.0.0
  device_type: rpi

payloads:
- name: apply-update
  type: script

Build the Zstandard-compressed artefact:

chmod 0755 apply-update
otamaker update.yaml
sha256sum ./*.tar.zst

Retain the manifest, script, checksum, Git commit, and test evidence together. The checksum protects transport integrity only; it does not make an unreviewed root script safe.

Host and Deploy¶

Use HTTPS storage accessible from the recipient. For a lab-only test on the same network:

python3 -m http.server 8080 --directory .

Before registering the artefact, open a remote shell on the recipient and verify access:

curl --fail --head http://<host-address>:8080/<artefact>.tar.zst

In connect.raspberrypi.com:

Open Remote update and create an artefact.
Enter the URI and SHA-256 checksum.
Deploy first to one non-critical canary device.
Confirm application health, network reachability, disk space, and reboot recovery.
Expand to a small batch, then the remaining fleet.

Never expose Python's test HTTP server to the public internet.

Verify and Troubleshoot¶

Inspect the dedicated OTA journal:

journalctl -t rpi-ota-connector
rpi-connect status
rpi-connect doctor
systemctl --failed
df -h

Add a service-specific health check. A successful package command is not enough:

systemctl is-active --quiet example.service
curl --fail --max-time 5 http://127.0.0.1:8080/health

No Deploy button¶

Run rpi-connect ota on, update the Connect packages, refresh the dashboard, and verify the device is signed in to the expected personal or organisation account.

Deployment remains pending¶

The device may be offline. Check its last-seen time and Connect status. A newly queued deployment can cancel an older pending deployment, so do not stack updates casually.

Download fails¶

Test the exact URI from the recipient, not from your laptop. Check DNS, firewall rules, TLS trust, redirects, credentials, file permissions, and checksum.

Script succeeded but the service is broken¶

Your script's exit criteria were incomplete. Add validation before writing the version marker and exit non-zero if the application health check fails.

When to Use A/B Boot¶

Choose A/B updates for unattended appliances where a broken root filesystem or kernel would require a site visit. Raspberry Pi's flow uses rpi-image-gen, two boot/system slots, a persistent user-data partition, and an initial image written with Raspberry Pi Imager. The recipient must be prepared for that layout before remote A/B updates are possible.

Budget at least 16GB and test rollback by deliberately deploying a non-booting canary image in a controlled lab. Do not test failure recovery for the first time on a remote production device.

Fleet Metrics¶

For every deployment, record:

artefact name, version, checksum, and source commit
targeted, succeeded, failed, and pending device counts
download-to-completion time
reboot time and first healthy timestamp
failure reason by stage
rollback or manual-recovery count

Compare canary and fleet percentiles instead of reporting only an average.

FAQ¶

Can Connect update an offline Raspberry Pi?¶

The deployment can be queued while the device is offline and begins after the device reconnects to Connect.

Can a normal script artefact roll back automatically?¶

No. Implement a safe application-level rollback in the script or use an A/B image for operating-system recovery.

Should access keys be placed in the artefact?¶

No. Avoid long-lived secrets in scripts, manifests, URLs, or logs. Use scoped credentials and a secure secret-provisioning process.