Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/core/firmware-updates/_meta.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)',
Expand Down
71 changes: 71 additions & 0 deletions content/core/firmware-updates/community-revisions.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
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

<Callout type="warning">

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

</Callout>

`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 `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 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
{
"sensorPort": "/dev/ttyS2",
"frozenPort": "/dev/ttyS1",
"F03": {
"sensorPort": "/dev/ttyS2",
"frozenPort": "/dev/ttyS1"
},
"F04": {
"sensorPort": "/dev/ttyS2",
"frozenPort": "/dev/ttyS1"
},
"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. 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 --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
```

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.
2 changes: 2 additions & 0 deletions content/core/firmware-updates/manual-update.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,8 @@ When connecting a Pod 4 cover to a Pod 3 MediaTek Pumpkin board, configure the h

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

</Callout>

<Callout type="default">
Expand Down
2 changes: 1 addition & 1 deletion content/core/firmware-updates/verification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand Down
Loading