Skip to content

docs(guides): first setup and updates - #417

Merged
mottihoresh merged 3 commits into
mainfrom
mh/docs-380-first-setup-page
Nov 11, 2026
Merged

mottihoresh merged 3 commits into
mainfrom
mh/docs-380-first-setup-page

Conversation

@mottihoresh

@mottihoresh mottihoresh commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Third PR for #380 (deliverable 2): the public first-setup page.

New page: docs/guides/first-setup.md, "First Setup & Updates"

It sits in the Build Guides nav after Flashing Firmware. It covers only what works today; client board updates (SkyHawkClient#175/#176/#177) are held for follow-ups.

  • What's in a release: which zip file goes on which board, and how (a 4-row table). A release has no PanelGroup file; the page points to Firmware/Examples/PanelGroupSample/.
  • Flash every board once:
    • the cockpit side: ST-Link with -full.hex;
    • the USB side: drag onto RPI-RP2, BOOTSEL only if the drive never appears;
    • PDUs: -full.hex;
    • PanelGroup boards: pio run -t bootstrap.
  • Check the Gateway in SkyHawkClient: Cockpit tab → Firmware, plus what Manual update only means.
  • Update the Gateway: the USB side first, then the cockpit side, with a hand-made SVG of the update order. The client's checks (relay stopped). Keep the PC awake and the cable in; after an unplug, check and update again.
  • The other boards: by ST-Link for now (.elf, or pio run -t upload, both of which keep the bootloader). To move a board to another node number, flash that node's firmware by ST-Link.
  • Red and green together:
    • Needs firmware = update again;
    • Won't start = install a different version;
    • a board flashed by ST-Link out of Won't start needs the cockpit switched off and on (the restart count survives the flash's reset; FirmwarePlan § Recovery says the same);
    • for a board whose firmware won't answer: click Retry, then press the reset button on the board being updated (never a cockpit power cycle);
    • links to the bring-up power-cut recipe and the status LED page.

The client labels were checked against SkyHawkClient main bd8e53e (after #201): the Cockpit tab, Firmware · n, Update / Retry, MANUAL UPDATE ONLY, the usb-first redirect, and the relay check. The shipped client uses the same Retry + reset-button wording.

Other pages

  • flashing.md: a link to the new page. :32 "the Gateway's PanelBridge chip" becomes "the Gateway's cockpit side".
  • guides/index.md: a "Start here" entry.
  • getting-started/client-app.md: a one-sentence pointer.
  • bring-up.md:76: "PanelBridge chip" becomes "cockpit side".
  • bootloader.md:20: the unstable board is now "Won't start" in SkyHawkClient (the LED description is kept). :88: "won't start it" becomes "treats it as no firmware at all", so it doesn't read like the new label.
  • mkdocs.yml: the nav entry.
  • Firmware/ScratchPad/FirmwarePlan/12-bootloader.md § Recovery: the same ST-Link Won't start line.
  • docs/assets/images/diagrams/update-order.svg: new. It goes with the repo's other diagrams rather than in docs/guides/.

Checks

  • tools/docs-drift/check_doc_refs.py: OK (43 citations, 80 pages).
  • mkdocs build -f docs/mkdocs.yml: exit 0. The only warning is the pre-existing mkdoxy docs/api anchor one.
  • I previewed the static build under /OpenSkyhawk/: the page, the table, the SVG and every link render.

Part of #380. Board updates from the client come in follow-up PRs as SkyHawkClient#175, #176 and #177 land.

A new guide, First Setup & Updates (#380), after Flashing Firmware:
- which release file goes on which board for the first flash, and how
  (ST-Link, drag and drop onto RPI-RP2, `pio run -t bootstrap`);
- checking the Gateway in SkyHawkClient, and updating it there, USB side
  first (a hand-made SVG of the update order);
- the other boards by ST-Link for now; moving a board to another node
  number by flashing that node's firmware;
- red and green together: "Needs firmware" and "Won't start", Retry then
  the reset button on the board being updated, and the power-cut recipe.
Client board updates (SkyHawkClient#175/#176/#177) are left out until they
land.

Linked from Flashing Firmware, the guides index and the client page. The
last "PanelBridge chip" mentions (flashing, bring-up) become "the Gateway's
cockpit side", and bootloader.md says "Won't start" for an unstable board.

Part of #380.
The crash-loop count survives an ST-Link flash and its reset; only a bus
commit, GO or a power cycle clears it. Say so on the first-setup page and
in FirmwarePlan § Recovery.
@mottihoresh
mottihoresh merged commit 67dad23 into main Nov 11, 2026
12 checks passed
@mottihoresh
mottihoresh deleted the mh/docs-380-first-setup-page branch November 11, 2026 05:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant