From 2edf20cbc490689c855c0c17f6172239ab7f1088 Mon Sep 17 00:00:00 2001 From: JoeGodz Date: Tue, 3 Nov 2026 21:35:29 -0600 Subject: [PATCH 1/3] add F08 hardware revision to Pod 3 update guide This update adds explicit support for F08 Pod 3 hardware revisions and clarifies how frankenfirmware handles UART port mapping dynamically. The Problem: The frankenfirmware daemon dynamically reads the hub's hardware revision from /deviceinfo/device-label on boot. If a user has a newer Pod 3 board like F08 and it is missing from machine.json, the daemon fails to find a match. The Symptom: It falls back to the default NXP i.MX 8M Mini ports (/dev/ttymxc0), leaving the STM32 microcontrollers disconnected. This causes the thermal loop to fail and temperature commands to be rejected ([thermostat] %s heat-on rejected - no peripheral connected). The Fix: Explicitly added the "F08" block to the generated machine.json in Step 6 to ensure the daemon correctly routes /dev/ttyS1 and /dev/ttyS2. Documentation Improvement: Updated the Step 6 Callout warnings to explain this dynamic label parsing so users with future unlisted hardware revisions (e.g., F09) know they must add their specific F0X code to the configuration block. --- .../core/firmware-updates/manual-update.mdx | 137 +++++++----------- 1 file changed, 51 insertions(+), 86 deletions(-) diff --git a/content/core/firmware-updates/manual-update.mdx b/content/core/firmware-updates/manual-update.mdx index 60e4d22..b3339d0 100644 --- a/content/core/firmware-updates/manual-update.mdx +++ b/content/core/firmware-updates/manual-update.mdx @@ -1,18 +1,10 @@ ---- -title: 'Pod 3 hub + Pod 4 cover update' +## title: 'Pod 3 hub + Pod 4 cover update' description: 'Manually update subsystems on the verified MediaTek Pod 3 hub and STM32G0 Pod 4 cover.' ---- import { Callout } from 'nextra/components' # Pod 3 hub + Pod 4 cover update - - -**Hardware scope: Pod 3 MT8365 F04 hub + Pod 4 STM32G0 cover.** Confirm the board and revisions against [Compatibility and releases](/core/firmware-updates/compatibility/) before proceeding. Never install the full NXP `.swu` image on the MediaTek hub. F03 mapping is included, but the recorded flash verification is F04. - - - This method extracts 64-bit ARM binaries for the verified hardware combination and STM32 microcontroller firmware from an official `.swu` release and stages them directly on your rooted Pod. This procedure replaces selected subsystem files without installing a complete stock operating system. It does not intentionally change your SSH keys or masked update services. That narrower scope does not guarantee compatibility or recovery: use only the verified hardware combination and keep the backups below. @@ -21,7 +13,7 @@ This procedure replaces selected subsystem files without installing a complete s Connect to your Pod over SSH as `root` (port 8822) and back up the current daemon and firmware directory: -```bash +``` ssh -p 8822 root@POD_IP " if [ ! -e /opt/eight/bin/frankenfirmware.bak ]; then cp -a /opt/eight/bin/frankenfirmware /opt/eight/bin/frankenfirmware.bak; fi && \ if [ ! -e /opt/eight/lib/subsystem_updates.bak ]; then cp -a /opt/eight/lib/subsystem_updates /opt/eight/lib/subsystem_updates.bak; fi && \ @@ -32,6 +24,7 @@ ssh -p 8822 root@POD_IP " done && \ if [ ! -e /opt/eight/backup_nats/was-enabled ]; then systemctl is-enabled nats-server.service > /opt/eight/backup_nats/was-enabled 2>/dev/null || true; fi " + ``` Keep these backups available on the Pod. If you need to revert any changes, see [Roll back subsystem files](/core/firmware-updates/rollback/). @@ -42,19 +35,16 @@ Firmware updates are distributed as `.swu` packages through Eight Sleep's update You can check the API directly using your device ID and current revision hash: -```bash -curl -is "https://update-api.8slp.net/v1/updates/pod3/1?deviceId=¤tRev=" ``` +curl -is "https://update-api.8slp.net/v1/updates/pod3/1?deviceId=¤tRev=" -- When an update is available, the API returns `HTTP/1.1 302 Found` with a signed AWS CloudFront/S3 download URL in the `Location:` header pointing to `https://fw.8slp.net/pod3-updates/pod3/releases/.swu`. -- Alternatively, public releases are indexed on the [Wayback Machine](http://web.archive.org/web/*/fw.8slp.net/pod3-updates/pod3/releases/*). For example, `77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu` contains ARM64 daemons with NATS JetStream support, STM32G0 cover firmware (`v5.5.9`), and hub thermal firmware (`v1.5.156`). -- Newer releases (such as `3dd72bdefafbcfc202d6715fc45f9c7bbb3e02ff.swu`) provide updated microcontroller firmware, including STM32G0 cover firmware `v5.5.22.0` and hub thermal firmware `v1.6.114`. +``` - +* When an update is available, the API returns `HTTP/1.1 302 Found` with a signed AWS CloudFront/S3 download URL in the `Location:` header pointing to `https://fw.8slp.net/pod3-updates/pod3/releases/.swu`. -**Release vs. delta archives:** Always use a full release archive containing `/releases/` in its URL path. Full releases contain the complete root filesystem tarball (`eightsleep-nxp-image-*.tar.gz`). Incremental or delta update packages do not include the rootfs and will be missing `libnats` and system binaries. +* Alternatively, public releases are indexed on the [Wayback Machine](http://web.archive.org/web/*/fw.8slp.net/pod3-updates/pod3/releases/*). For example, `77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu` contains ARM64 daemons with NATS JetStream support, STM32G0 cover firmware (`v5.5.9`), and hub thermal firmware (`v1.5.156`). - +* Newer releases (such as `3dd72bdefafbcfc202d6715fc45f9c7bbb3e02ff.swu`) provide updated microcontroller firmware, including STM32G0 cover firmware `v5.5.22.0` and hub thermal firmware `v1.6.114`. Review [artifact compatibility](/core/firmware-updates/compatibility/#choosing-artifacts-pod-3-releases-vs-latest-firmware) before extracting or transferring files. @@ -64,33 +54,35 @@ There are **two extraction layers**: the outer `.swu` package, then the root fil On your computer, use a new, empty directory for each release so files from an earlier extraction cannot hide missing artifacts. Replace the example `.swu` filename with the file you actually downloaded: -```bash +``` mkdir swu_extracted && cd swu_extracted # List the outer package, then extract it. cpio -it < ../77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu cpio -idmv < ../77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu ls + ``` For the documented release, the inner archive is named `eightsleep-nxp-image-*.tar.gz`. Inspect `sw-description` to identify the payload, then use the **exact** archive filename, not a wildcard that could match multiple files. Replace `ROOTFS_ARCHIVE.tar.gz` below with that filename: -```bash +``` sed -n '1,200p' sw-description tar -tzf ROOTFS_ARCHIVE.tar.gz tar -xzf ROOTFS_ARCHIVE.tar.gz + ``` Locate the required artifacts in the extracted root filesystem: -| Path in archive | Artifact description | Target path on Pod | -| :------------------------------------------------------------ | :-------------------------------------------------------------------------- | :---------------------------------------- | -| `opt/eight/bin/frankenfirmware` | ARM64 daemon with NATS JetStream and STM32G0 support | `/opt/eight/bin/frankenfirmware` | -| `opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin` | STM32G0 Pod 4 cover firmware (`v5.5.9` or `v5.5.22.0`, ~137 KB) | `/opt/eight/lib/subsystem_updates/` | -| `opt/eight/lib/subsystem_updates/firmware-sensor-g0-usb.bbin` | Optional: USB cover sensor variant (~145 KB) | `/opt/eight/lib/subsystem_updates/` | -| `opt/eight/lib/subsystem_updates/firmware-frozen.bbin` | Hub thermal controller firmware (`v1.5.156` ~120 KB, or `v1.6.114` ~138 KB) | `/opt/eight/lib/subsystem_updates/` | -| `lib/libnats.so.3.11.0` | C NATS shared library (located in `lib/` or `usr/lib/`, not `usr/lib64/`) | `/usr/lib64/libnats.so.3.11.0` | -| `usr/bin/nats-server` & `usr/bin/nats` | Static ARM64 NATS server and management CLI | `/usr/bin/` | -| `etc/nats.conf` & `lib/systemd/system/nats-server.service` | NATS service configuration and systemd unit | `/etc/nats.conf` & `/etc/systemd/system/` | +| Path in archive | Artifact description | Target path on Pod | +| ----- | ----- | ----- | +| `opt/eight/bin/frankenfirmware` | ARM64 daemon with NATS JetStream and STM32G0 support | `/opt/eight/bin/frankenfirmware` | +| `opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin` | STM32G0 Pod 4 cover firmware (`v5.5.9` or `v5.5.22.0`, \~137 KB) | `/opt/eight/lib/subsystem_updates/` | +| `opt/eight/lib/subsystem_updates/firmware-sensor-g0-usb.bbin` | Optional: USB cover sensor variant (\~145 KB) | `/opt/eight/lib/subsystem_updates/` | +| `opt/eight/lib/subsystem_updates/firmware-frozen.bbin` | Hub thermal controller firmware (`v1.5.156` \~120 KB, or `v1.6.114` \~138 KB) | `/opt/eight/lib/subsystem_updates/` | +| `lib/libnats.so.3.11.0` | C NATS shared library (located in `lib/` or `usr/lib/`, not `usr/lib64/`) | `/usr/lib64/libnats.so.3.11.0` | +| `usr/bin/nats-server` & `usr/bin/nats` | Static ARM64 NATS server and management CLI | `/usr/bin/` | +| `etc/nats.conf` & `lib/systemd/system/nats-server.service` | NATS service configuration and systemd unit | `/etc/nats.conf` & `/etc/systemd/system/` | ### Locating `libnats.so.3.11.0` @@ -98,21 +90,24 @@ In Yocto/OpenEmbedded root filesystem tarballs, shared libraries are placed unde Before transferring anything, search the extraction directory: -```bash +``` find . \( -name 'sw-description' -o -name '*image*.tar*' \ -o -name 'libnats.so*' -o -name 'frankenfirmware' \ -o -name 'nats-server' -o -name 'nats' \) -print + ``` -- **Only the inner archive is present:** finish extracting `ROOTFS_ARCHIVE.tar.gz`. A library inside that archive is not yet a file you can copy with `scp`. -- **`libnats.so.3.11.0` is in `lib/` or `usr/lib/`:** this is expected. Copy it to `/usr/lib64/` on the Pod as shown in Step 4. -- **No `libnats.so*` appears after root filesystem extraction:** inspect the archive listing to distinguish an extraction issue from a delta/patch SWU that does not contain the root filesystem. +* **Only the inner archive is present:** finish extracting `ROOTFS_ARCHIVE.tar.gz`. A library inside that archive is not yet a file you can copy with `scp`. + +* **`libnats.so.3.11.0` is in `lib/` or `usr/lib/`:** this is expected. Copy it to `/usr/lib64/` on the Pod as shown in Step 4. + +* **No `libnats.so*` appears after root filesystem extraction:** inspect the archive listing to distinguish an extraction issue from a delta/patch SWU that does not contain the root filesystem. ### Pre-flight artifact validation Before copying files to the Pod, validate that the extracted binaries and firmware payloads match expected architectures and versions. In both the `file` check below and the Step 4 `scp` command, replace `lib/libnats.so.3.11.0` with the path reported by `find` (for example, `usr/lib/libnats.so.3.11.0`). -```bash +``` # 1. Verify ARM64 ELF architecture across userland binaries and libraries file opt/eight/bin/frankenfirmware lib/libnats.so.3.11.0 usr/bin/nats-server usr/bin/nats # Expected: ELF 64-bit LSB executable/shared object, ARM aarch64 @@ -135,21 +130,16 @@ python3 -c "b=open('opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin','rb python3 -c "b=open('opt/eight/lib/subsystem_updates/firmware-frozen.bbin','rb').read(34); print('v' + '.'.join(str(x) for x in b[29:29+b[28]]))" # Expected: v1.5.156 or v1.6.114 # Alternatively using od: od -An -j 29 -N 3 -t u1 opt/eight/lib/subsystem_updates/firmware-frozen.bbin + ``` ## Step 4: Transfer artifacts to the Pod From your computer within the extracted root filesystem directory (`swu_extracted`), transfer the files to the Pod over port 8822. - - -**Legacy SCP protocol:** Use `scp -O` (the legacy protocol flag). Newer OpenSSH clients default to SFTP, which can be rejected by the Pod's embedded dropbear/sshd server. - - - If you are re-running this step and `nats-server` is already running, stop it first (`ssh -p 8822 root@POD_IP "systemctl stop nats-server.service"`). Otherwise `scp` cannot overwrite the running binary and fails with `Text file busy`. -```bash +``` # Transfer the updated frankenfirmware daemon to staging in /tmp/ scp -O -P 8822 opt/eight/bin/frankenfirmware root@POD_IP:/tmp/frankenfirmware @@ -178,19 +168,14 @@ ssh -p 8822 root@POD_IP " chmod 644 /opt/eight/lib/subsystem_updates/*.bbin && \ chown root:root /opt/eight/lib/subsystem_updates/*.bbin " -``` - - -**Hub controller firmware:** Staging `firmware-frozen.bbin` in `/opt/eight/lib/subsystem_updates/` causes `frank` to reflash the hub's onboard thermal controller MCU upon restarting. Both `v1.5.156` and `v1.6.114` have been tested and verified on a Pod 3 hub (`pn 20500`, hardware revision `0504`). If you only want to update cover support or NATS telemetry without reflashing the hub controller, omit copying `firmware-frozen.bbin`. - - +``` ## Step 5: Install and start NATS JetStream On the Pod, configure the library loader, start the NATS service, and provision the `raw` JetStream stream: -```bash +``` # Link the shared library and update loader cache ssh -p 8822 root@POD_IP " ln -sf /usr/lib64/libnats.so.3.11.0 /usr/lib64/libnats.so.3.11 && \ @@ -211,43 +196,26 @@ ssh -p 8822 root@POD_IP " nats stream info raw >/dev/null 2>&1 || \ nats stream add raw --subjects 'raw.>' --storage file --retention limits --max-age 24h --max-bytes 512MB --discard old --defaults " + ``` ## Step 6: Configure UART mapping, metadata stubs, and stage cover firmware (Pod 3 hub + Pod 4 cover) - - -**Hardware scope:** This step applies specifically when pairing a **Pod 3 hub with a Pod 4 cover**. - -If you are updating a Pod 3 hub paired with its original Pod 3 cover (STM32F0/F1), do **not** overwrite `firmware-sensor.bbin` with the G0 binary or change `machine.json`—retain the stock port mapping and cover firmware so the original microcontroller can initialize normally. - - - When connecting a Pod 4 cover to a Pod 3 MediaTek Pumpkin board, configure the hardware serial port routing in `/opt/eight/config/machine.json`: -- `/dev/ttyS2` connects to the **cover sensor port** (`pn 20600`, Pod 4 cover, 921,600 baud). -- `/dev/ttyS1` connects to the **hub thermal controller** (`pn 20500`, water/TEC/pump controller, 38,400 baud). - - - -**Hub revision compatibility (`F03` vs. `F04`) and `capybara`:** Pod 3 hubs were manufactured in both **`F03`** and **`F04`** hardware revisions (inspect your hub label with `cat /deviceinfo/device-label`, e.g. `20500-0003-F03-...` or `20500-0003-F04-...`). `frankenfirmware` inspects this label at boot and searches `machine.json` for a matching section. If an `F03` hub only has `F04` defined, `frankenfirmware` falls back to default NXP i.MX 8M Mini UART ports (`/dev/ttymxc0`), leaving the cover disconnected and causing `Thermostat.cpp` to reject temperature commands (`[thermostat] %s heat-on rejected - no peripheral connected`). Additionally, legacy `capybara.service` parses UART paths from the root level of `machine.json` and ignores nested blocks. If root keys are missing, `capybara` dumps core on startup and triggers `A dependency job for frank.service failed`. Defining both root keys and both `"F03"` and `"F04"` blocks satisfies all Pod 3 hub revisions and background services. (Note: setting `sensorSideOverrides` with `"force_f04"` or `"hwRev"` is unnecessary; `frankenfirmware` ignores those keys). +* `/dev/ttyS2` connects to the **cover sensor port** (`pn 20600`, Pod 4 cover, 921,600 baud). - - - - -**Silencing `updateCaviaConfig` parse error spam:** Updated `frankenfirmware` polls `/deviceinfo/capybara.run_info` every second. On Pod 3, stock Capybara does not write this file. When missing, `frozen.cpp:927 updateCaviaConfig` throws `[json.exception.parse_error.101]` and spams `journalctl -u frank` with 60 errors per minute. (Writing to `cavia.json` has no effect because `frankenfirmware` reads `/deviceinfo/capybara.run_info`). Deploying an empty JSON object `{}` to `/deviceinfo/capybara.run_info` and persisting it across reboots with a `frank.service` systemd drop-in completely silences this log spam. - - +* `/dev/ttyS1` connects to the **hub thermal controller** (`pn 20500`, water/TEC/pump controller, 38,400 baud). Write the multi-revision configuration, metadata stub, and stage `firmware-sensor-g0.bbin` into the fallback locations: -```bash +``` ssh -p 8822 root@POD_IP " set -e mkdir -p /opt/eight/config - # 1. Write machine.json covering root keys, F03, and F04 revisions + # 1. Write machine.json covering root keys, F03, F04, and F08 revisions + # If your device-label contains a different revision (e.g. F09), add its block below. cat > /opt/eight/config/machine.json << 'EOF' { \"sensorPort\": \"/dev/ttyS2\", @@ -259,6 +227,10 @@ ssh -p 8822 root@POD_IP " \"F04\": { \"sensorPort\": \"/dev/ttyS2\", \"frozenPort\": \"/dev/ttyS1\" + }, + \"F08\": { + \"sensorPort\": \"/dev/ttyS2\", + \"frozenPort\": \"/dev/ttyS1\" } } EOF @@ -286,6 +258,7 @@ EOF cp /opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin /opt/eight/lib/subsystem_updates/firmware-sensor-legacy.bbin cp /opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin /opt/eight/lib/subsystem_updates/firmware-sensor.bbin " + ``` ## Step 7: Deploy updated `frankenfirmware` and trigger flash @@ -294,7 +267,7 @@ EOF Stop the background service, preserve a timestamped backup, place the new binary, and restart: -```bash +``` ssh -p 8822 root@POD_IP " if [ ! -f /tmp/frankenfirmware ]; then echo 'Error: /tmp/frankenfirmware missing; re-run the Step 4 scp' >&2; exit 1; fi && \ systemctl stop frank.service && \ @@ -303,25 +276,14 @@ ssh -p 8822 root@POD_IP " chmod +x /opt/eight/bin/frankenfirmware && \ systemctl start frank.service " -``` - - -**Clean hardware reboot for UART synchronization:** While `systemctl restart frank.service` triggers the update, microcontrollers that were in intermediate UART states or operating at different baud rates may fail to complete the initial handshake over `/dev/ttyS1`. If `frank` stalls or does not report `Firmware initialized` within 60–90 seconds, initiate a clean reboot: - -```bash -ssh -p 8822 root@POD_IP "reboot" ``` -An OS reboot forces the MediaTek MT8365 kernel GPIO lines to toggle the physical STM32 NRST lines, guaranteeing a clean, synchronous bootloader handshake for both microcontrollers upon startup. - - - Monitor the firmware flash progress in real time with `journalctl -u frank -f`. **Expected Sensor Flash Timeline (`v5.5.9` → `v5.5.22`):** -```text +``` frank[...]: INF:... stateBootloaderUseFwInfo|[sensor] current sensor FW version: 5.5.9 frank[...]: INF:... stateBootloaderUseFwInfo|[sensor] Update to FW: 5.5.22 frank[...]: DBG:... handleCommand|[sensor] -> BL: ... [fwu] start erase @@ -329,11 +291,12 @@ frank[...]: DBG:... handleCommand|[sensor] -> BL: ... [fwu] ready for new fw ... frank[...]: DBG:... handleCommand|[sensor] -> BL: ... FW update complete frank[...]: DBG:... handleCommand|[sensor] -> FW: ... [sys] g0 v5.5.22.0 running beep boop bop + ``` **Expected Thermal Controller Flash Timeline (`v1.5.156` → `v1.6.114`):** -```text +``` frank[...]: INF:... stateBootloaderUseFwInfo|[frozen] current frozen FW version: 1.5.156 frank[...]: INF:... stateBootloaderUseFwInfo|[frozen] Update to FW: 1.6.114 frank[...]: DBG:... handleCommand|[frozen] -> BL: Start Erase @@ -345,13 +308,14 @@ frank[...]: INF:... updateHandleStopResponse|update GOOD frank[...]: DBG:... handleCommand|[frozen] -> BL: Jumping to FW frank[...]: DBG:... handleCommand|[frozen] -> FW: [frozen] hwrev=0x0504, is_pod6=0, pod6_ferrites=0 frank[...]: DBG:... handleCommand|[frozen] -> FW: Firmware initialized v1.6.114 + ``` ## Step 8: Restart sleepypod biometrics services Once the microcontrollers boot their new application firmwares, restart the sleepypod processing stack to connect to NATS: -```bash +``` ssh -p 8822 root@POD_IP " systemctl restart \ sleepypod-piezo-processor.service \ @@ -361,6 +325,7 @@ ssh -p 8822 root@POD_IP " sleepypod-calibrator.service \ sleepypod.service " + ``` ## Next: verify the update From 05ef8687050b86e007f65862108db92498136971 Mon Sep 17 00:00:00 2001 From: Jonathan Ng Date: Thu, 5 Nov 2026 01:43:49 -0800 Subject: [PATCH 2/3] Keep the verified guide to F03/F04 and move F08 to a community-reported revisions page Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_016Wac1uHSpomCEBtwBdw1YA --- content/core/firmware-updates/_meta.ts | 1 + .../firmware-updates/community-revisions.mdx | 59 ++++++++ .../core/firmware-updates/manual-update.mdx | 139 +++++++++++------- .../core/firmware-updates/verification.mdx | 2 +- 4 files changed, 149 insertions(+), 52 deletions(-) create mode 100644 content/core/firmware-updates/community-revisions.mdx diff --git a/content/core/firmware-updates/_meta.ts b/content/core/firmware-updates/_meta.ts index 22f5f67..22022da 100644 --- a/content/core/firmware-updates/_meta.ts +++ b/content/core/firmware-updates/_meta.ts @@ -3,6 +3,7 @@ export default { compatibility: 'Compatibility and releases', 'manual-update': 'Pod 3 hub + Pod 4 cover', verification: 'Verify and troubleshoot', + 'community-revisions': 'Community-reported hub revisions', rollback: 'Roll back subsystem files', 'backup-slot': 'Synchronize Slot B', 'factory-reset': 'Return to stock (OTA)', diff --git a/content/core/firmware-updates/community-revisions.mdx b/content/core/firmware-updates/community-revisions.mdx new file mode 100644 index 0000000..593d44d --- /dev/null +++ b/content/core/firmware-updates/community-revisions.mdx @@ -0,0 +1,59 @@ +--- +title: 'Community-reported hub revisions' +description: 'Map Pod 3 hub revisions outside the verified F03/F04 set in machine.json, using reports from the community.' +--- + +import { Callout } from 'nextra/components' + +# Community-reported hub revisions + + + +**Not maintainer-verified.** The [manual update](/core/firmware-updates/manual-update/) covers `F03` and `F04` hubs. The revisions on this page come from community reports on a single unit each. Read the report, keep your [backups](/core/firmware-updates/manual-update/#step-1-back-up-the-existing-pod-state), and verify the result on your own hardware. + + + +`frankenfirmware` reads the hub label from `/deviceinfo/device-label` at boot and looks for a block with the same revision in `/opt/eight/config/machine.json`. If no block matches, it falls back to the default NXP i.MX 8M Mini ports (`/dev/ttymxc0`). The cover and hub controller then stay disconnected, and temperature commands fail with `[thermostat] %s heat-on rejected - no peripheral connected`. + +## Find your revision + +```bash +ssh -p 8822 root@POD_IP "cat /deviceinfo/device-label" +# Example: 20500-0003-F08-... +``` + +The revision is the third dash-separated field (`F08` above). If it is `F03` or `F04`, follow the manual update without changes. + +## Add a block for your revision + +In the [Step 6](/core/firmware-updates/manual-update/#step-6-configure-uart-mapping-metadata-stubs-and-stage-cover-firmware-pod-3-hub--pod-4-cover) `machine.json`, add a block named after your revision next to `F03` and `F04`. Keep the root-level keys, because `capybara.service` reads only those: + +```json +"F08": { + "sensorPort": "/dev/ttyS2", + "frozenPort": "/dev/ttyS1" +} +``` + +In the Step 6 `ssh` command, the JSON sits inside a double-quoted string, so escape each quote as `\"`, matching the existing blocks. + +## Confirm the mapping + +After restarting `frank.service`, confirm that the daemon picked your block and the expected ports: + +```bash +ssh -p 8822 root@POD_IP "journalctl -u frank -b --no-pager | grep -E 'Using machine config|sensor path'" +# Expected: +# INF: DeviceInfo.cpp getPorts | Using machine config for hwRev F08 (device hwRev: F08) +# INF: main.cpp | sensor path: /dev/ttyS2 frozen path: /dev/ttyS1 +``` + +If the log still shows `/dev/ttymxc0`, the block name does not match the label. Check spelling and case. + +## Reported revisions + +| Revision | Example label | Cover | Ports (`sensorPort` / `frozenPort`) | Reported by | Source | +| :------- | :----------------- | :-------------- | :---------------------------------- | :------------------------------------- | :-------------------------------------------------------------- | +| `F08` | `20500-0003-F08-…` | Pod 4 (STM32G0) | `/dev/ttyS2` / `/dev/ttyS1` | [@JoeGodz](https://github.com/JoeGodz) | [#60](https://github.com/sleepypod/sleepypod.github.io/pull/60) | + +To add a revision, open a pull request that adds a row to this table. Include your full `device-label` prefix, your cover generation, and the `Using machine config` log line. diff --git a/content/core/firmware-updates/manual-update.mdx b/content/core/firmware-updates/manual-update.mdx index b3339d0..baa9080 100644 --- a/content/core/firmware-updates/manual-update.mdx +++ b/content/core/firmware-updates/manual-update.mdx @@ -1,10 +1,18 @@ -## title: 'Pod 3 hub + Pod 4 cover update' +--- +title: 'Pod 3 hub + Pod 4 cover update' description: 'Manually update subsystems on the verified MediaTek Pod 3 hub and STM32G0 Pod 4 cover.' +--- import { Callout } from 'nextra/components' # Pod 3 hub + Pod 4 cover update + + +**Hardware scope: Pod 3 MT8365 F04 hub + Pod 4 STM32G0 cover.** Confirm the board and revisions against [Compatibility and releases](/core/firmware-updates/compatibility/) before proceeding. Never install the full NXP `.swu` image on the MediaTek hub. F03 mapping is included, but the recorded flash verification is F04. + + + This method extracts 64-bit ARM binaries for the verified hardware combination and STM32 microcontroller firmware from an official `.swu` release and stages them directly on your rooted Pod. This procedure replaces selected subsystem files without installing a complete stock operating system. It does not intentionally change your SSH keys or masked update services. That narrower scope does not guarantee compatibility or recovery: use only the verified hardware combination and keep the backups below. @@ -13,7 +21,7 @@ This procedure replaces selected subsystem files without installing a complete s Connect to your Pod over SSH as `root` (port 8822) and back up the current daemon and firmware directory: -``` +```bash ssh -p 8822 root@POD_IP " if [ ! -e /opt/eight/bin/frankenfirmware.bak ]; then cp -a /opt/eight/bin/frankenfirmware /opt/eight/bin/frankenfirmware.bak; fi && \ if [ ! -e /opt/eight/lib/subsystem_updates.bak ]; then cp -a /opt/eight/lib/subsystem_updates /opt/eight/lib/subsystem_updates.bak; fi && \ @@ -24,7 +32,6 @@ ssh -p 8822 root@POD_IP " done && \ if [ ! -e /opt/eight/backup_nats/was-enabled ]; then systemctl is-enabled nats-server.service > /opt/eight/backup_nats/was-enabled 2>/dev/null || true; fi " - ``` Keep these backups available on the Pod. If you need to revert any changes, see [Roll back subsystem files](/core/firmware-updates/rollback/). @@ -35,16 +42,19 @@ Firmware updates are distributed as `.swu` packages through Eight Sleep's update You can check the API directly using your device ID and current revision hash: -``` +```bash curl -is "https://update-api.8slp.net/v1/updates/pod3/1?deviceId=¤tRev=" - ``` -* When an update is available, the API returns `HTTP/1.1 302 Found` with a signed AWS CloudFront/S3 download URL in the `Location:` header pointing to `https://fw.8slp.net/pod3-updates/pod3/releases/.swu`. +- When an update is available, the API returns `HTTP/1.1 302 Found` with a signed AWS CloudFront/S3 download URL in the `Location:` header pointing to `https://fw.8slp.net/pod3-updates/pod3/releases/.swu`. +- Alternatively, public releases are indexed on the [Wayback Machine](http://web.archive.org/web/*/fw.8slp.net/pod3-updates/pod3/releases/*). For example, `77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu` contains ARM64 daemons with NATS JetStream support, STM32G0 cover firmware (`v5.5.9`), and hub thermal firmware (`v1.5.156`). +- Newer releases (such as `3dd72bdefafbcfc202d6715fc45f9c7bbb3e02ff.swu`) provide updated microcontroller firmware, including STM32G0 cover firmware `v5.5.22.0` and hub thermal firmware `v1.6.114`. -* Alternatively, public releases are indexed on the [Wayback Machine](http://web.archive.org/web/*/fw.8slp.net/pod3-updates/pod3/releases/*). For example, `77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu` contains ARM64 daemons with NATS JetStream support, STM32G0 cover firmware (`v5.5.9`), and hub thermal firmware (`v1.5.156`). + -* Newer releases (such as `3dd72bdefafbcfc202d6715fc45f9c7bbb3e02ff.swu`) provide updated microcontroller firmware, including STM32G0 cover firmware `v5.5.22.0` and hub thermal firmware `v1.6.114`. +**Release vs. delta archives:** Always use a full release archive containing `/releases/` in its URL path. Full releases contain the complete root filesystem tarball (`eightsleep-nxp-image-*.tar.gz`). Incremental or delta update packages do not include the rootfs and will be missing `libnats` and system binaries. + + Review [artifact compatibility](/core/firmware-updates/compatibility/#choosing-artifacts-pod-3-releases-vs-latest-firmware) before extracting or transferring files. @@ -54,35 +64,33 @@ There are **two extraction layers**: the outer `.swu` package, then the root fil On your computer, use a new, empty directory for each release so files from an earlier extraction cannot hide missing artifacts. Replace the example `.swu` filename with the file you actually downloaded: -``` +```bash mkdir swu_extracted && cd swu_extracted # List the outer package, then extract it. cpio -it < ../77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu cpio -idmv < ../77af88bd8b941fed81786c09a9ac3cdb1e97b126.swu ls - ``` For the documented release, the inner archive is named `eightsleep-nxp-image-*.tar.gz`. Inspect `sw-description` to identify the payload, then use the **exact** archive filename, not a wildcard that could match multiple files. Replace `ROOTFS_ARCHIVE.tar.gz` below with that filename: -``` +```bash sed -n '1,200p' sw-description tar -tzf ROOTFS_ARCHIVE.tar.gz tar -xzf ROOTFS_ARCHIVE.tar.gz - ``` Locate the required artifacts in the extracted root filesystem: -| Path in archive | Artifact description | Target path on Pod | -| ----- | ----- | ----- | -| `opt/eight/bin/frankenfirmware` | ARM64 daemon with NATS JetStream and STM32G0 support | `/opt/eight/bin/frankenfirmware` | -| `opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin` | STM32G0 Pod 4 cover firmware (`v5.5.9` or `v5.5.22.0`, \~137 KB) | `/opt/eight/lib/subsystem_updates/` | -| `opt/eight/lib/subsystem_updates/firmware-sensor-g0-usb.bbin` | Optional: USB cover sensor variant (\~145 KB) | `/opt/eight/lib/subsystem_updates/` | -| `opt/eight/lib/subsystem_updates/firmware-frozen.bbin` | Hub thermal controller firmware (`v1.5.156` \~120 KB, or `v1.6.114` \~138 KB) | `/opt/eight/lib/subsystem_updates/` | -| `lib/libnats.so.3.11.0` | C NATS shared library (located in `lib/` or `usr/lib/`, not `usr/lib64/`) | `/usr/lib64/libnats.so.3.11.0` | -| `usr/bin/nats-server` & `usr/bin/nats` | Static ARM64 NATS server and management CLI | `/usr/bin/` | -| `etc/nats.conf` & `lib/systemd/system/nats-server.service` | NATS service configuration and systemd unit | `/etc/nats.conf` & `/etc/systemd/system/` | +| Path in archive | Artifact description | Target path on Pod | +| :------------------------------------------------------------ | :-------------------------------------------------------------------------- | :---------------------------------------- | +| `opt/eight/bin/frankenfirmware` | ARM64 daemon with NATS JetStream and STM32G0 support | `/opt/eight/bin/frankenfirmware` | +| `opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin` | STM32G0 Pod 4 cover firmware (`v5.5.9` or `v5.5.22.0`, ~137 KB) | `/opt/eight/lib/subsystem_updates/` | +| `opt/eight/lib/subsystem_updates/firmware-sensor-g0-usb.bbin` | Optional: USB cover sensor variant (~145 KB) | `/opt/eight/lib/subsystem_updates/` | +| `opt/eight/lib/subsystem_updates/firmware-frozen.bbin` | Hub thermal controller firmware (`v1.5.156` ~120 KB, or `v1.6.114` ~138 KB) | `/opt/eight/lib/subsystem_updates/` | +| `lib/libnats.so.3.11.0` | C NATS shared library (located in `lib/` or `usr/lib/`, not `usr/lib64/`) | `/usr/lib64/libnats.so.3.11.0` | +| `usr/bin/nats-server` & `usr/bin/nats` | Static ARM64 NATS server and management CLI | `/usr/bin/` | +| `etc/nats.conf` & `lib/systemd/system/nats-server.service` | NATS service configuration and systemd unit | `/etc/nats.conf` & `/etc/systemd/system/` | ### Locating `libnats.so.3.11.0` @@ -90,24 +98,21 @@ In Yocto/OpenEmbedded root filesystem tarballs, shared libraries are placed unde Before transferring anything, search the extraction directory: -``` +```bash find . \( -name 'sw-description' -o -name '*image*.tar*' \ -o -name 'libnats.so*' -o -name 'frankenfirmware' \ -o -name 'nats-server' -o -name 'nats' \) -print - ``` -* **Only the inner archive is present:** finish extracting `ROOTFS_ARCHIVE.tar.gz`. A library inside that archive is not yet a file you can copy with `scp`. - -* **`libnats.so.3.11.0` is in `lib/` or `usr/lib/`:** this is expected. Copy it to `/usr/lib64/` on the Pod as shown in Step 4. - -* **No `libnats.so*` appears after root filesystem extraction:** inspect the archive listing to distinguish an extraction issue from a delta/patch SWU that does not contain the root filesystem. +- **Only the inner archive is present:** finish extracting `ROOTFS_ARCHIVE.tar.gz`. A library inside that archive is not yet a file you can copy with `scp`. +- **`libnats.so.3.11.0` is in `lib/` or `usr/lib/`:** this is expected. Copy it to `/usr/lib64/` on the Pod as shown in Step 4. +- **No `libnats.so*` appears after root filesystem extraction:** inspect the archive listing to distinguish an extraction issue from a delta/patch SWU that does not contain the root filesystem. ### Pre-flight artifact validation Before copying files to the Pod, validate that the extracted binaries and firmware payloads match expected architectures and versions. In both the `file` check below and the Step 4 `scp` command, replace `lib/libnats.so.3.11.0` with the path reported by `find` (for example, `usr/lib/libnats.so.3.11.0`). -``` +```bash # 1. Verify ARM64 ELF architecture across userland binaries and libraries file opt/eight/bin/frankenfirmware lib/libnats.so.3.11.0 usr/bin/nats-server usr/bin/nats # Expected: ELF 64-bit LSB executable/shared object, ARM aarch64 @@ -130,16 +135,21 @@ python3 -c "b=open('opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin','rb python3 -c "b=open('opt/eight/lib/subsystem_updates/firmware-frozen.bbin','rb').read(34); print('v' + '.'.join(str(x) for x in b[29:29+b[28]]))" # Expected: v1.5.156 or v1.6.114 # Alternatively using od: od -An -j 29 -N 3 -t u1 opt/eight/lib/subsystem_updates/firmware-frozen.bbin - ``` ## Step 4: Transfer artifacts to the Pod From your computer within the extracted root filesystem directory (`swu_extracted`), transfer the files to the Pod over port 8822. + + +**Legacy SCP protocol:** Use `scp -O` (the legacy protocol flag). Newer OpenSSH clients default to SFTP, which can be rejected by the Pod's embedded dropbear/sshd server. + + + If you are re-running this step and `nats-server` is already running, stop it first (`ssh -p 8822 root@POD_IP "systemctl stop nats-server.service"`). Otherwise `scp` cannot overwrite the running binary and fails with `Text file busy`. -``` +```bash # Transfer the updated frankenfirmware daemon to staging in /tmp/ scp -O -P 8822 opt/eight/bin/frankenfirmware root@POD_IP:/tmp/frankenfirmware @@ -168,14 +178,19 @@ ssh -p 8822 root@POD_IP " chmod 644 /opt/eight/lib/subsystem_updates/*.bbin && \ chown root:root /opt/eight/lib/subsystem_updates/*.bbin " - ``` + + +**Hub controller firmware:** Staging `firmware-frozen.bbin` in `/opt/eight/lib/subsystem_updates/` causes `frank` to reflash the hub's onboard thermal controller MCU upon restarting. Both `v1.5.156` and `v1.6.114` have been tested and verified on a Pod 3 hub (`pn 20500`, hardware revision `0504`). If you only want to update cover support or NATS telemetry without reflashing the hub controller, omit copying `firmware-frozen.bbin`. + + + ## Step 5: Install and start NATS JetStream On the Pod, configure the library loader, start the NATS service, and provision the `raw` JetStream stream: -``` +```bash # Link the shared library and update loader cache ssh -p 8822 root@POD_IP " ln -sf /usr/lib64/libnats.so.3.11.0 /usr/lib64/libnats.so.3.11 && \ @@ -196,26 +211,45 @@ ssh -p 8822 root@POD_IP " nats stream info raw >/dev/null 2>&1 || \ nats stream add raw --subjects 'raw.>' --storage file --retention limits --max-age 24h --max-bytes 512MB --discard old --defaults " - ``` ## Step 6: Configure UART mapping, metadata stubs, and stage cover firmware (Pod 3 hub + Pod 4 cover) + + +**Hardware scope:** This step applies specifically when pairing a **Pod 3 hub with a Pod 4 cover**. + +If you are updating a Pod 3 hub paired with its original Pod 3 cover (STM32F0/F1), do **not** overwrite `firmware-sensor.bbin` with the G0 binary or change `machine.json`—retain the stock port mapping and cover firmware so the original microcontroller can initialize normally. + + + When connecting a Pod 4 cover to a Pod 3 MediaTek Pumpkin board, configure the hardware serial port routing in `/opt/eight/config/machine.json`: -* `/dev/ttyS2` connects to the **cover sensor port** (`pn 20600`, Pod 4 cover, 921,600 baud). +- `/dev/ttyS2` connects to the **cover sensor port** (`pn 20600`, Pod 4 cover, 921,600 baud). +- `/dev/ttyS1` connects to the **hub thermal controller** (`pn 20500`, water/TEC/pump controller, 38,400 baud). + + + +**Hub revision compatibility (`F03` vs. `F04`) and `capybara`:** Pod 3 hubs were manufactured in both **`F03`** and **`F04`** hardware revisions (inspect your hub label with `cat /deviceinfo/device-label`, e.g. `20500-0003-F03-...` or `20500-0003-F04-...`). `frankenfirmware` inspects this label at boot and searches `machine.json` for a matching section. If an `F03` hub only has `F04` defined, `frankenfirmware` falls back to default NXP i.MX 8M Mini UART ports (`/dev/ttymxc0`), leaving the cover disconnected and causing `Thermostat.cpp` to reject temperature commands (`[thermostat] %s heat-on rejected - no peripheral connected`). Additionally, legacy `capybara.service` parses UART paths from the root level of `machine.json` and ignores nested blocks. If root keys are missing, `capybara` dumps core on startup and triggers `A dependency job for frank.service failed`. Defining both root keys and both `"F03"` and `"F04"` blocks satisfies all Pod 3 hub revisions and background services. (Note: setting `sensorSideOverrides` with `"force_f04"` or `"hwRev"` is unnecessary; `frankenfirmware` ignores those keys). + +If your label shows a revision other than `F03` or `F04`, see [Community-reported hub revisions](/core/firmware-updates/community-revisions/) before running this step. -* `/dev/ttyS1` connects to the **hub thermal controller** (`pn 20500`, water/TEC/pump controller, 38,400 baud). + + + + +**Silencing `updateCaviaConfig` parse error spam:** Updated `frankenfirmware` polls `/deviceinfo/capybara.run_info` every second. On Pod 3, stock Capybara does not write this file. When missing, `frozen.cpp:927 updateCaviaConfig` throws `[json.exception.parse_error.101]` and spams `journalctl -u frank` with 60 errors per minute. (Writing to `cavia.json` has no effect because `frankenfirmware` reads `/deviceinfo/capybara.run_info`). Deploying an empty JSON object `{}` to `/deviceinfo/capybara.run_info` and persisting it across reboots with a `frank.service` systemd drop-in completely silences this log spam. + + Write the multi-revision configuration, metadata stub, and stage `firmware-sensor-g0.bbin` into the fallback locations: -``` +```bash ssh -p 8822 root@POD_IP " set -e mkdir -p /opt/eight/config - # 1. Write machine.json covering root keys, F03, F04, and F08 revisions - # If your device-label contains a different revision (e.g. F09), add its block below. + # 1. Write machine.json covering root keys, F03, and F04 revisions cat > /opt/eight/config/machine.json << 'EOF' { \"sensorPort\": \"/dev/ttyS2\", @@ -227,10 +261,6 @@ ssh -p 8822 root@POD_IP " \"F04\": { \"sensorPort\": \"/dev/ttyS2\", \"frozenPort\": \"/dev/ttyS1\" - }, - \"F08\": { - \"sensorPort\": \"/dev/ttyS2\", - \"frozenPort\": \"/dev/ttyS1\" } } EOF @@ -258,7 +288,6 @@ EOF cp /opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin /opt/eight/lib/subsystem_updates/firmware-sensor-legacy.bbin cp /opt/eight/lib/subsystem_updates/firmware-sensor-g0.bbin /opt/eight/lib/subsystem_updates/firmware-sensor.bbin " - ``` ## Step 7: Deploy updated `frankenfirmware` and trigger flash @@ -267,7 +296,7 @@ EOF Stop the background service, preserve a timestamped backup, place the new binary, and restart: -``` +```bash ssh -p 8822 root@POD_IP " if [ ! -f /tmp/frankenfirmware ]; then echo 'Error: /tmp/frankenfirmware missing; re-run the Step 4 scp' >&2; exit 1; fi && \ systemctl stop frank.service && \ @@ -276,14 +305,25 @@ ssh -p 8822 root@POD_IP " chmod +x /opt/eight/bin/frankenfirmware && \ systemctl start frank.service " +``` + + +**Clean hardware reboot for UART synchronization:** While `systemctl restart frank.service` triggers the update, microcontrollers that were in intermediate UART states or operating at different baud rates may fail to complete the initial handshake over `/dev/ttyS1`. If `frank` stalls or does not report `Firmware initialized` within 60–90 seconds, initiate a clean reboot: + +```bash +ssh -p 8822 root@POD_IP "reboot" ``` +An OS reboot forces the MediaTek MT8365 kernel GPIO lines to toggle the physical STM32 NRST lines, guaranteeing a clean, synchronous bootloader handshake for both microcontrollers upon startup. + + + Monitor the firmware flash progress in real time with `journalctl -u frank -f`. **Expected Sensor Flash Timeline (`v5.5.9` → `v5.5.22`):** -``` +```text frank[...]: INF:... stateBootloaderUseFwInfo|[sensor] current sensor FW version: 5.5.9 frank[...]: INF:... stateBootloaderUseFwInfo|[sensor] Update to FW: 5.5.22 frank[...]: DBG:... handleCommand|[sensor] -> BL: ... [fwu] start erase @@ -291,12 +331,11 @@ frank[...]: DBG:... handleCommand|[sensor] -> BL: ... [fwu] ready for new fw ... frank[...]: DBG:... handleCommand|[sensor] -> BL: ... FW update complete frank[...]: DBG:... handleCommand|[sensor] -> FW: ... [sys] g0 v5.5.22.0 running beep boop bop - ``` **Expected Thermal Controller Flash Timeline (`v1.5.156` → `v1.6.114`):** -``` +```text frank[...]: INF:... stateBootloaderUseFwInfo|[frozen] current frozen FW version: 1.5.156 frank[...]: INF:... stateBootloaderUseFwInfo|[frozen] Update to FW: 1.6.114 frank[...]: DBG:... handleCommand|[frozen] -> BL: Start Erase @@ -308,14 +347,13 @@ frank[...]: INF:... updateHandleStopResponse|update GOOD frank[...]: DBG:... handleCommand|[frozen] -> BL: Jumping to FW frank[...]: DBG:... handleCommand|[frozen] -> FW: [frozen] hwrev=0x0504, is_pod6=0, pod6_ferrites=0 frank[...]: DBG:... handleCommand|[frozen] -> FW: Firmware initialized v1.6.114 - ``` ## Step 8: Restart sleepypod biometrics services Once the microcontrollers boot their new application firmwares, restart the sleepypod processing stack to connect to NATS: -``` +```bash ssh -p 8822 root@POD_IP " systemctl restart \ sleepypod-piezo-processor.service \ @@ -325,7 +363,6 @@ ssh -p 8822 root@POD_IP " sleepypod-calibrator.service \ sleepypod.service " - ``` ## Next: verify the update diff --git a/content/core/firmware-updates/verification.mdx b/content/core/firmware-updates/verification.mdx index 740ef8c..d67dd5a 100644 --- a/content/core/firmware-updates/verification.mdx +++ b/content/core/firmware-updates/verification.mdx @@ -63,7 +63,7 @@ python3 -c "import sqlite3; c=sqlite3.connect('/persistent/sleepypod-data/biomet - **`A dependency job for frank.service failed`:** Check `systemctl status capybara.service` and `journalctl -u capybara -n 50 --no-pager`. If `capybara` dumped core or exited with an error, inspect `/opt/eight/config/machine.json`. Confirm that `sensorPort` and `frozenPort` are declared at both the root level and inside the nested `F03` and `F04` blocks as shown in [Step 6](/core/firmware-updates/manual-update/#step-6-configure-uart-mapping-metadata-stubs-and-stage-cover-firmware-pod-3-hub--pod-4-cover). - **`[thermostat] left heat-on rejected - no peripheral connected` (or cover not detected):** - Check your device label with `cat /deviceinfo/device-label`. If the hardware revision is `F03` (e.g., `20500-0003-F03-...`) and `/opt/eight/config/machine.json` only contains `"F04"`, `frankenfirmware` falls back to default NXP i.MX 8M Mini ports (`/dev/ttymxc0`) and never connects to the cover on `/dev/ttyS2`. Add the `"F03"` block to `machine.json` with `"sensorPort": "/dev/ttyS2"` and `"frozenPort": "/dev/ttyS1"`. (Note: setting `sensorSideOverrides` with `"force_f04"` has no effect as the daemon ignores unknown override keys). + Check your device label with `cat /deviceinfo/device-label`. If the hardware revision is `F03` (e.g., `20500-0003-F03-...`) and `/opt/eight/config/machine.json` only contains `"F04"`, `frankenfirmware` falls back to default NXP i.MX 8M Mini ports (`/dev/ttymxc0`) and never connects to the cover on `/dev/ttyS2`. Add the `"F03"` block to `machine.json` with `"sensorPort": "/dev/ttyS2"` and `"frozenPort": "/dev/ttyS1"`. (Note: setting `sensorSideOverrides` with `"force_f04"` has no effect as the daemon ignores unknown override keys). For revisions other than `F03` or `F04`, see [Community-reported hub revisions](/core/firmware-updates/community-revisions/). - **Log flooding with `frozen.cpp:927 updateCaviaConfig|[frozen] get_cavia_info() failed: [json.exception.parse_error.101]`:** Confirm that `/deviceinfo/capybara.run_info` exists and contains `{}`. Because `/deviceinfo` is an in-memory `tmpfs`, ensure the systemd drop-in `/etc/systemd/system/frank.service.d/capybara-runinfo.conf` is in place to recreate the stub on boot. (Note: creating `cavia.json` has no effect because `frankenfirmware` explicitly polls `/deviceinfo/capybara.run_info`). - **Serial handshake stalls or frozen controller does not initialize:** From 8104c61ec8aedc582375ffe6130fd0735b32add8 Mon Sep 17 00:00:00 2001 From: Jonathan Ng Date: Thu, 5 Nov 2026 03:31:38 -0800 Subject: [PATCH 3/3] Show the full machine.json insertion, scope the log check to the current run and separate F03 mapping from verified flashing Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_016Wac1uHSpomCEBtwBdw1YA --- .../firmware-updates/community-revisions.mdx | 26 ++++++++++++++----- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/content/core/firmware-updates/community-revisions.mdx b/content/core/firmware-updates/community-revisions.mdx index 593d44d..298c19f 100644 --- a/content/core/firmware-updates/community-revisions.mdx +++ b/content/core/firmware-updates/community-revisions.mdx @@ -9,7 +9,7 @@ import { Callout } from 'nextra/components' -**Not maintainer-verified.** The [manual update](/core/firmware-updates/manual-update/) covers `F03` and `F04` hubs. The revisions on this page come from community reports on a single unit each. Read the report, keep your [backups](/core/firmware-updates/manual-update/#step-1-back-up-the-existing-pod-state), and verify the result on your own hardware. +**Not maintainer-verified.** The [manual update](/core/firmware-updates/manual-update/) includes the `F03` port mapping, but its recorded flash verification covers only `F04` hubs. The revisions on this page come from community reports on a single unit each. Read the report, keep your [backups](/core/firmware-updates/manual-update/#step-1-back-up-the-existing-pod-state), and verify the result on your own hardware. @@ -22,16 +22,28 @@ ssh -p 8822 root@POD_IP "cat /deviceinfo/device-label" # Example: 20500-0003-F08-... ``` -The revision is the third dash-separated field (`F08` above). If it is `F03` or `F04`, follow the manual update without changes. +The revision is the third dash-separated field (`F08` above). If it is `F04`, follow the manual update without changes. If it is `F03`, the manual update already includes your port mapping, but its flash verification covers only `F04`. ## Add a block for your revision -In the [Step 6](/core/firmware-updates/manual-update/#step-6-configure-uart-mapping-metadata-stubs-and-stage-cover-firmware-pod-3-hub--pod-4-cover) `machine.json`, add a block named after your revision next to `F03` and `F04`. Keep the root-level keys, because `capybara.service` reads only those: +In the [Step 6](/core/firmware-updates/manual-update/#step-6-configure-uart-mapping-metadata-stubs-and-stage-cover-firmware-pod-3-hub--pod-4-cover) `machine.json`, add a block named after your revision after `F04`. Add a comma after the closing brace of the `F04` block, and keep the root-level keys, because `capybara.service` reads only those: ```json -"F08": { +{ "sensorPort": "/dev/ttyS2", - "frozenPort": "/dev/ttyS1" + "frozenPort": "/dev/ttyS1", + "F03": { + "sensorPort": "/dev/ttyS2", + "frozenPort": "/dev/ttyS1" + }, + "F04": { + "sensorPort": "/dev/ttyS2", + "frozenPort": "/dev/ttyS1" + }, + "F08": { + "sensorPort": "/dev/ttyS2", + "frozenPort": "/dev/ttyS1" + } } ``` @@ -39,10 +51,10 @@ In the Step 6 `ssh` command, the JSON sits inside a double-quoted string, so esc ## Confirm the mapping -After restarting `frank.service`, confirm that the daemon picked your block and the expected ports: +After restarting `frank.service`, confirm that the daemon picked your block and the expected ports. The command reads only the current run of the service, so log lines from before the change do not appear: ```bash -ssh -p 8822 root@POD_IP "journalctl -u frank -b --no-pager | grep -E 'Using machine config|sensor path'" +ssh -p 8822 root@POD_IP 'journalctl --no-pager _SYSTEMD_INVOCATION_ID="$(systemctl show -p InvocationID --value frank.service)" | grep -E "Using machine config|sensor path"' # Expected: # INF: DeviceInfo.cpp getPorts | Using machine config for hwRev F08 (device hwRev: F08) # INF: main.cpp | sensor path: /dev/ttyS2 frozen path: /dev/ttyS1