skill

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

Public Unreviewed

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
skill / octolux-web-serial-hmi

Install

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 12-row failure-mode table.

adom-wiki pkg install caleb/octolux-web-serial-hmi

Latest: v0.1.4, published

Contents

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.