Web Serial HMI + USB CDC Firmware (Octolux ↔ RP-series) - README.md

by Caleb

Build a paired NTX HMI (Chromium kiosk on Octolux) + firmware (USB CDC on RP2040/RP2350) that auto-connects over USB with no permission picker. End-to-end recipe: Pico SDK firmware template, HMI Web Serial via getPorts() + VID filter, Chromium SerialAllowAllPortsForUrls policy, udev MODE=0666 for /dev/ttyACM*, SCP + chromium-restart + screencast-bounce deploy, CDP verification, visible-debug-strip diagnostics, and a 12-row failure-mode table.

Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity

Download

What this skill fixes

Failure modes that appear when building paired HMI + USB CDC firmware on Octolux. Cross off as the upstream platform / firmware ships a fix.

Web Serial picker shows "No compatible devices found" — lsusb confirms the device. Cause: missing Chromium SerialAllowAllPortsForUrls policy or /dev/ttyACM* not world-readable.
requestPort() rejects with NotFoundError: No port selected by the user — every session. Cause: picker is wrong UX for a kiosk; use getPorts() + VID filter.
port.open() throws "Failed to execute 'open' on 'SerialPort'" — open ports[0] is a platform UART, not the USB CDC device. Always filter by VID.
getPorts().length === 0 — policy path wrong, Chromium not restarted, or /dev/ttyACM0 still root-only.
Tap on the HMI does nothing visible — Chromium permission dialogs don't render in the VNC stream. Use a visible debug strip on the page + CDP-via-SSH.
octolux deploy push times out — SCP + chromium-restart + screencast-bounce shell sequence is the workaround.
ps aux \| grep screencast returns nothing on the device — busybox ps truncates cmdlines. Use /proc/[0-9]*/cmdline matching.
DANGER: walking /proc/[0-9]*/net/tcp to find a port owner mass-kills system PIDs. Lost SSH and Chromium during this session. Use cmdline matching instead.
/tmp/screencast.js or /tmp/node_modules/ws/ missing after a bad kill — both in tmpfs. SCP-restore from ~/ntx-embedded/apps/octolux/.
Dashboard VNC tile frozen after Chromium restart — screencast's CDP binding died with the old target. Bounce the screencast.
error code: 502 no-body on the Adom proxy — strips 5xx bodies. Return HTTP 200 with {ok:false, error, hint} instead. (Cross-ref: octolux-app-server-debug.)

Install

adompkg install caleb/octolux-web-serial-hmi
# or the whole NTX bundle:
adompkg install caleb/ntx-octolux-toolkit

Lands at ~/.claude/skills/octolux-web-serial-hmi/ and becomes discoverable to Claude on the next run.

Full reference

Browse SKILL.md in the Files tab — Quick-start recipe for new HMI projects, Pico SDK firmware template, full Web Serial HMI template, Chromium policy install, udev rule, deploy sequence, CDP diagnostics, 12-row failure-mode table.

## What this skill fixes

Failure modes that appear when building paired HMI + USB CDC firmware on Octolux. Cross off as the upstream platform / firmware ships a fix.

- **Web Serial picker shows *"No compatible devices found"*** — `lsusb` confirms the device. Cause: missing Chromium `SerialAllowAllPortsForUrls` policy or `/dev/ttyACM*` not world-readable.
- **`requestPort()` rejects with `NotFoundError: No port selected by the user`** — every session. Cause: picker is wrong UX for a kiosk; use `getPorts()` + VID filter.
- **`port.open()` throws *"Failed to execute 'open' on 'SerialPort'"*** — open `ports[0]` is a platform UART, not the USB CDC device. Always filter by VID.
- **`getPorts().length === 0`** — policy path wrong, Chromium not restarted, or `/dev/ttyACM0` still root-only.
- **Tap on the HMI does nothing visible** — Chromium permission dialogs don't render in the VNC stream. Use a visible debug strip on the page + CDP-via-SSH.
- **`octolux deploy push` times out** — SCP + chromium-restart + screencast-bounce shell sequence is the workaround.
- **`ps aux \| grep screencast` returns nothing on the device** — busybox `ps` truncates cmdlines. Use `/proc/[0-9]*/cmdline` matching.
- **DANGER: walking `/proc/[0-9]*/net/tcp` to find a port owner mass-kills system PIDs.** Lost SSH and Chromium during this session. Use cmdline matching instead.
- **`/tmp/screencast.js` or `/tmp/node_modules/ws/` missing after a bad kill** — both in tmpfs. SCP-restore from `~/ntx-embedded/apps/octolux/`.
- **Dashboard VNC tile frozen after Chromium restart** — screencast's CDP binding died with the old target. Bounce the screencast.
- **`error code: 502` no-body on the Adom proxy** — strips 5xx bodies. Return HTTP 200 with `{ok:false, error, hint}` instead. (Cross-ref: [octolux-app-server-debug](/caleb/octolux-app-server-debug).)

## Install

```bash
adompkg install caleb/octolux-web-serial-hmi
# or the whole NTX bundle:
adompkg install caleb/ntx-octolux-toolkit
```

Lands at `~/.claude/skills/octolux-web-serial-hmi/` and becomes discoverable to Claude on the next run.

## Full reference

Browse `SKILL.md` in the **Files** tab — Quick-start recipe for new HMI projects, Pico SDK firmware template, full Web Serial HMI template, Chromium policy install, udev rule, deploy sequence, CDP diagnostics, 12-row failure-mode table.