docs: clarify source setup and hardware qualification

[vincentkoc]

Problem

The setup documentation did not clearly distinguish current repository source from registry packages and prebuilt firmware. It also understated role-specific reconnect-token persistence and the explicit status-command policy needed by Tab5.

Changes

• Document per-example SDK requirements, room examples, submodule setup, and the observed source-versus-registry version drift.
• Correct node/operator reconnect-session and handoff-token persistence documentation.
• Include shared status commands in the Tab5 allowlist and add invocation examples.
• Add a board- and firmware-specific hardware qualification checklist, with every new physical result initially marked not run.

Checks

• Documentation checked against the existing source and independently reviewed.
• All 18 relative file links in the final changed documents resolve.
• The scoped documentation git diff --check passed.
• Final diff and publication text checked for private data.
• Hosted CI for PR head 0e94978edc042df16d4a82956cf0778668792531: all five builds passed in https://github.com/openclaw/esp-openclaw-node/actions/runs/34130469594.
• All three CodeQL analyses passed for the same head in https://github.com/openclaw/esp-openclaw-node/actions/runs/34130467173.

Hardware Smoke Evidence

A limited run used the firmware from #37, checked-out source test merge e37937d8b3b796a5f4c64d7207d729371f49f3fd, on an M5Stack Tab5 with ESP32-P4 revision 1.3 and 16 MiB flash. A full-flash erase and four image writes completed with hash verification. ST7121 LCD selection and readable local diagnostics rendering were observed. External Osmo Pocket 3 measurement confirmed approximately one second of 1 kHz speaker output. This was the PR37 image, not a separate PR36 firmware build; its IDF revision was v5.5.5-648-g362a1776ec2, not release v5.5.5.

In that limited PR37 run, microphone/AFE activity was observed, but controlled speech response was inconclusive. Physical touch, the Tab5 camera, network pairing, Canvas RPC, and provider Talk were not run. No provider API calls were made and no provider key was loaded.

The initial diagnostics-close attempt hit a display-lock TIMEOUT. UI progress was verified, then one explicit retry closed diagnostics. This intermittent failure remains unresolved; no source fix was made. These observations are not clean, complete GUI or board qualification. Existing historical evidence and panel-specific limitations remain applicable.

Final Stack Documentation

The reviewed wording correction distinguishes the Tab5 manifest's ==5.5.5
constraint from the qualified SDK source revision
362a1776ec212788fda95f75b733bfdde3a0c394, tracked compatibility patches,
immutable CI image, and explicit manual procedure. It does not describe that
patched build as pristine release 5.5.5 or treat build success as hardware
qualification.

Land this documentation last, after
#55, preserving the original
signed docs commit and the accepted cumulative source repairs. The checklist
is a template for a named board and firmware, not a claim that this final
tree has been physically tested. Later bounded camera results belong to
their exact historical images; successful end-to-end voice, calibrated
camera color, and full encrypted-media qualification remain unproven.
No release or device action is authorized by this documentation landing.

Signed integration head 6b91262112064543c0ac756d700989291b51433e
preserves the original docs commit and the reviewed final tree
ad62c3fa643079c8b6012f0a661d269c7c129deb.
All five native builds and all three CodeQL analyses passed for this head in
CI run 34706310289
and CodeQL run 34706308480.
After PR55 landed, GitHub's synthetic merge has the current main/head parents
and this exact final tree. This is source/build proof, not final-image hardware
qualification.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs changes before merge. Reviewed September 12, 2026, 12:51 PM ET / 16:51 UTC (Revision 4).

ClawSweeper review

What this changes

Clarifies source setup, reconnect storage, and hardware qualification, while incorporating invoke-reply diagnostics and a console-header framing repair with regression coverage.

Merge readiness

⛔ Needs changes before merge - 1 item remains

Useful documentation remains absent from main, and this member-authored PR is protected from automatic closure. The overlapping send repair has landed separately; no blocking introduced defect was found.

Priority: P3
Reviewed head: 6b91262112064543c0ac756d700989291b51433e

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The remaining changes are coherent, preserve existing contracts, and include focused regression coverage with appropriately limited hardware claims.
Proof confidence	🌊 off-meta tidepool	Not applicable: The member-author exemption applies. Related diagnostic PRs provide bounded historical device observations, while this PR's supplied smoke uses the firmware-packaging image; neither is presented as fresh cumulative-image or complete hardware qualification.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The member-author exemption applies. Related diagnostic PRs provide bounded historical device observations, while this PR's supplied smoke uses the firmware-packaging image; neither is presented as fresh cumulative-image or complete hardware qualification.
Evidence reviewed	7 items	Introduced scope and clean checkout: Read the complete pinned introduced changes across 12 files. The delta includes production +87 net lines and tests +602 net lines. git diff --check passed, and git status remained clean; no builds or tests were executed. Meaningful work remains outside main: Fetched main still has the generic ESP-IDF prerequisite, only two example links, and a diagnostics header spread across multiple printf calls. The branch's setup guidance and single-call console repair therefore remain useful. Separately merged send repair: GitHub verifies #54 merged as fetched main. Its protocol implementation and tests match this branch's overlapping changes. Its body records a real camera response correctly classified as a zero-byte send failure and a later complete response delivered to the Gateway. The release API returned no GitHub releases; this establishes main presence, not registry shipment.
Findings	None	None.
Security	None	None.

How this fits together

The ESP32 node firmware receives Gateway commands and returns device results over WebSocket. Its setup guides and local console help operators configure boards and distinguish successful builds from physically verified behavior.

flowchart TD
  A[Source or firmware artifact] --> B[Board setup guidance]
  B --> C[ESP32 node firmware]
  D[Gateway commands] --> C
  C --> E[Command results and reply diagnostics]
  C --> F[Local status console]
  E --> G[Hardware qualification record]
  F --> G

Loading

Before merge

• Complete next step (P2) - Mark the draft ready for review before merging.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	Pinned introduced delta: production +87 net lines; tests +602 net lines	Production growth supports bounded reply diagnostics, already merged separately, while regression coverage also protects the remaining console repair.

Technical review

Best possible solution:

Keep artifact-specific setup instructions and explicit qualification limits, preserving the independently reviewed diagnostic repairs through the existing stack.

Do we have a high-confidence way to reproduce the issue?

Yes for the console defect: main splits one header across stdio calls, allowing another writer between fragments; the added deterministic fixture exercises that schedule. This review inspected the source without executing tests.

Is this the best way to solve the issue?

Yes. The documentation reflects existing contracts, and one printf preserves the console's bytes while removing the between-call interleaving window without adding locks or configuration.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 6a1dac665311.

Labels

Label justifications:

• P3: The remaining contribution improves setup accuracy, qualification guidance, and diagnostic output framing without an established urgent user regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The member-author exemption applies. Related diagnostic PRs provide bounded historical device observations, while this PR's supplied smoke uses the firmware-packaging image; neither is presented as fresh cumulative-image or complete hardware qualification.

Evidence

What I checked:

• Introduced scope and clean checkout: Read the complete pinned introduced changes across 12 files. The delta includes production +87 net lines and tests +602 net lines. git diff --check passed, and git status remained clean; no builds or tests were executed. (6b9126211206)
• Meaningful work remains outside main: Fetched main still has the generic ESP-IDF prerequisite, only two example links, and a diagnostics header spread across multiple printf calls. The branch's setup guidance and single-call console repair therefore remain useful. (components/esp-openclaw-room-node/esp_openclaw_room_node.c:1134, 6a1dac665311)
• Separately merged send repair: GitHub verifies fix(node): validate JSON sends and trace invoke replies #54 merged as fetched main. Its protocol implementation and tests match this branch's overlapping changes. Its body records a real camera response correctly classified as a zero-byte send failure and a later complete response delivered to the Gateway. The release API returned no GitHub releases; this establishes main presence, not registry shipment. (components/esp-openclaw-node/src/esp_openclaw_node_protocol.c:116, 6a1dac665311)
• Console repair has an open landing candidate: fix(room): keep diagnostic header in one stdio call #55 remains open at the exact second parent of this PR. Its discussion accepts the single-header repair, reports passing byte/contention regressions and native builds, and carefully limits physical evidence to a historical boot and complete idle-status response. (components/esp-openclaw-room-node/esp_openclaw_room_node.c:1143, fe8e2fbba12d)
• Documentation matches existing storage and command contracts: Existing persistence code selects separate node/operator keys; protocol code stores supported other-role handoff tokens. The voice-bootstrap test checks operator-token persistence, and provisioning registers device.info, device.status, and wifi.status. These documentation edits do not introduce a storage migration or change runtime authorization. (components/esp-openclaw-node/src/esp_openclaw_node_persisted_session.c:23, 6b9126211206)
• Proof scope and review continuity: The supplied complete body explicitly identifies the limited hardware smoke as an image from ci: publish traceable example firmware bundles #37, and leaves touch, camera, pairing, Canvas, and provider Talk unqualified. The prior review had no findings and requested leaving draft state; the live endpoint confirms this PR is still draft at the pinned head. (6b9126211206)

Likely related people:

• vincentkoc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (3 earlier review cycles)

• reviewed 2026-09-07T14:01:48.675Z sha 0e94978 :: needs maintainer review before merge. :: none
• reviewed 2026-09-07T14:17:40.207Z sha 0e94978 :: needs changes before merge. :: none
• reviewed 2026-09-07T14:57:31.318Z sha 0e94978 :: needs changes before merge. :: none