@openbrt/weclawctl

Unified WeClaw device, audio/voice, display, and VM app management CLI.

This package is the 0.1.56 development preview for testing the audioctl capability model through the long-term weclawctl command name. It does not wrap audioctl at runtime; it ports the agent-facing queue, feedback, light, wakeword, VM app, and inspect surfaces into the unified CLI.

Current Scope

• device profiles exposes four first-class weclawVM contract profiles: ESP32-S3 e-ink, ESP32-S3 RLCD, ESP32-C3, and Rokid A113. Profiles separate deployability from hardware verification so a planned adapter is never reported as hardware-proven.
• The canonical RLCD hardware profile follows weclaw-商品英文全称-vm: profile:weclaw-waveshare-esp32-s3-rlcd-4.2-vm for Waveshare ESP32-S3-RLCD-4.2. Legacy profile:esp32-s3-rlcd and profile:weclaw-waveshare-esp32-s3-rlcd-4-2-vm remain aliases only.
• Generic network App deployment: app install mqtt:... BUNDLE --profile PROFILE --instance INSTANCE.json. The CLI validates the v2 draft bundle, selects a standard/tiny/micro target, adapts canonical capabilities to the current Host-v0 manifest, publishes one weclaw.control.v1 / app_install, and waits for the correlated lifecycle result.
• bind, device inspect, and doctor for BYOA pairing and draft Device Profiles.
• ESP32-S3 RLCD serial adapter through WEC:GET, WEC:VM_STATUS, WEC:VM_INSTALL, WEC:VM_RUN, WEC:VM_REMOVE, and WEC:AUDIO_TEST.
• Audioctl-style queue screen preview: reads a weclaw.playable_queue.v1 queue and installs a one-call VM app that renders now-playing, lyric, and app-defined display data on the RLCD screen. On updated ESP32-S3 RLCD firmware, queue --play --screen also requests audio.play_preview, which plays a short device-local synth preview through ES8311. Older firmware returns a degraded playback result.
• audio play-url for ESP32-S3 RLCD autonomous playback: over a network mqtt: target it sends an authorized HTTP(S) audio URL to the device so firmware fetches, decodes, and plays it through ES8311/I2S without local conversion. The serial form exists only for near-field development checks.
• audio play-list for ESP32-S3 RLCD autonomous playlist playback: it can start a device-side MP3 URL queue over MQTT. Its built-in rlcd-music-effects-panel is only a smoke/demo scene for simple queues: it renders a canned display.kind="scene" text/rect panel with object height bindings to audio.pcm_level. Do not use that demo panel as the answer to a custom vinyl, cover-art, or product UI request. For creative UI, use audio play-list --no-screen to start the queue and install a separate agent-authored VM app, or create one VM app that owns both audio and display. Music controls should still be device-side input.button.bind: RLCD screen-top-left short release toggles play/stop, and screen-top-right short release skips to the next track. The demo scene now requires explicit --demo-screen; plain audio play-list defaults to audio-only queue control. Firmware 0.1.117+ also reserves RLCD screen-top-left hold for about 8 seconds as the user physical reset-to-binding-code action; VM apps must not claim that hold gesture. Screen-top-right long press is intentionally not bound on the current RLCD unit because GPIO0/BOOT has reset-window risk. Use --scene-fps only together with --demo-screen; the firmware may throttle it by power state.
• Realtime lyrics sync is a VM app responsibility. Start the device-side MP3 queue with audio play-list --no-screen, pass legal LRC/timeline and duration metadata through the queue or app instance, then let the app's on_frame read audio.state.read (position_ms, monotonic_ms, duration_ms, position_source) and render highlighted/scrolling lyrics as app-owned WCF2 pixels. Do not use frame counting, host-side polling, audio now-playing text replacement, serial streaming, or a firmware/ weclawctl lyrics template.
• Screen layout is owned by the selected VM app, not by weclawctl or the firmware as a platform-wide fixed template. Agents should first read examples/RLCD_PIXEL_APP_METHOD.md, then pick or create a VM app bundle/request that declares its own display objects, pixel frames, input bindings, and live-data reads. Do not call unsupported display override commands or claim the firmware hardcodes a particular app's layout.
• RLCD VM apps can go below convenience text/rect/circle/line scene objects: use on_frame with display.frame.write / display.canvas.write to push app-authored 1bpp pixel frames for album covers, black-hole art, typography, charts, pets, games, particle fields, oscilloscopes, equalizers, or any other form the agent programs. Full-screen WCF1 frames remain supported as a compatibility fallback; newer RLCD firmware also accepts WCF2 dirty-rect raw 1bpp packets on the same operation so apps can update only dynamic regions.
• audio play-list --scene is demo-only and now requires --demo-screen. It can carry static bitmap/circle/line primitives and audio bindings for diagnostics, but it will not rotate album art and must not be used as custom UI delivery. Scene bitmap/canvas/frame primitives accept raw monochrome 1bpp base64 pixels with explicit x/y/width/height/stride; they do not fetch HTTP(S) image URLs, decode PNG/JPG data URIs, or apply transform strings. The bundled pixel-frame examples are write-path samples, not design requirements. Use them only after reading the method guide: WECLAW_EXAMPLES_DIR=<installed-package-or-local-plugin>/examples. Current verified WCF2 write-path sample is rlcd-wcf2-turntable-v3 (artifact_bytes=128809, artifact_sha256=01c8d278e4436dda8afe889bd74566a16a7dfc323c8f45d3d2a97751077ad601). It teaches WCF2 dirty-rect emission; it is not a recommended gramophone UI. The older rlcd-grand-turntable-v8 full-screen WCF1 sample remains a compatibility fallback only. Do not use superseded partial-frame v7/v6 bundles, bundles with artifact_bytes=51697, sha starting 0770, or sha starting ffd142.
• builtin:calendar is the default switchable built-in VM app for home and recovery; it keeps the calendar surface and floating pet, but it does not constrain what other pushed VM apps may render.
• audio stream for ESP32-S3 RLCD serial PCM diagnostics: uses local ffmpeg to decode a URL or file to pcm_s16le_16000_mono, then streams it over WEC:AUDIO_PCM_*. This is a development bridge, not the autonomous path.
• audio now-playing, light describe/set/timeline/bind/clear, feedback beep, and wakeword status/configure/bind/trigger/clear for agent-side testing of audio/voice/display capability discovery. audio now-playing --effect spectrum installs a VM-owned scene with 12 rect objects bound to audio.pcm_level and the same device-side left/right music button bindings; it must not be treated as a text-only replacement for an active music panel.
• app validate for weclaw.app.v2.draft bundles and weclaw.app_instance.v1.draft instances.
• Fake-host lifecycle commands: install / list / status / logs / update / rollback / stop / start / remove.
• Deterministic JSON envelope and exit-code model for applied, rejected, offline, timeout, and user-action-required outcomes.
• version / --version so agents can verify the installed package without inspecting node_modules internals.

Hardware writes are consent-gated. Commands that change the RLCD screen, play or stop audio, beep, run/remove VM apps, or write light/wakeword state must include --yes after explicit user approval, or run with WEC_HARDWARE_CONSENT=1. Read-only commands such as device inspect, vm status, audio url-status, light describe, and wakeword status remain available without the gate. --dry-run never opens the hardware.

The RLCD serial adapter currently proves screen/feedback/VM control. Updated firmware supports speaker beeps, a short local synth preview for queue play requests, serial PCM diagnostics via audio stream, and device-side HTTP(S) audio URL playback via audio play-url, and VM-app-backed playlist playback via audio play-list --no-screen. Agents should prefer the network form audio play-list mqtt:default QUEUE.json --no-screen for playlists and audio play-url mqtt:default URL for single tracks on remote RLCD devices: they provide authorized direct MP3 platform/CDN URLs, while the ESP32 fetches and decodes the stream itself. Other audio containers stay behind firmware resource/e2e validation. MQTT and binding command results intentionally do not expose the local binding agent name, so agents do not confuse a credentials label for their own identity. Platform queue refreshing, credential renewal, and long-running playback recovery remain runtime features to migrate from audioctl. Light timelines can be previewed on the RLCD as a VM media surface, and wakeword configuration/binding is accepted as logical control state; raw PCM capture is still reported as disabled on the current RLCD firmware.

For serial RLCD testing, agents should not run bind, wait for a pairing code, read .quarantine, use agent-mqtt.json, install the mqtt package, or publish raw MQTT control messages. For a remote RLCD already paired to the current agent, use mqtt:default or mqtt:<credentials-file> as the device target; MQTT is still hidden inside weclawctl, not agent-authored scripts.

For MQTT communication issues, use read-only status commands before asking the user for a physical reset. device inspect mqtt:default, vm status mqtt:default, app status mqtt:default, and audio url-status mqtt:default all go through weclawctl and do not require --yes. A single device_status_timeout means the status probe did not receive a correlated reply in time; it is not proof that the ESP32 needs RST or USB replug.

Agents must not create local Python/Node polling daemons for RLCD music buttons. Custom music UI apps should install input.button.bind bindings themselves; audio play-list --demo-screen installs demo-panel bindings only for smoke tests.

Examples

npm run check
node bin/weclawctl.mjs version --json
node bin/weclawctl.mjs manifest --json
node bin/weclawctl.mjs device profiles --json
node bin/weclawctl.mjs bind 123456 --name codex --json
node bin/weclawctl.mjs device inspect profile:weclaw-waveshare-esp32-s3-rlcd-4.2-vm --json
node bin/weclawctl.mjs device inspect serial:/dev/cu.usbmodem212201 --json
node bin/weclawctl.mjs light describe serial:/dev/cu.usbmodem212201 --json
node bin/weclawctl.mjs light timeline serial:/dev/cu.usbmodem212201 \
  examples/lights/rlcd-spectrum.light.json \
  --yes \
  --json
node bin/weclawctl.mjs light bind serial:/dev/cu.usbmodem212201 \
  examples/lights/rlcd-media.light-bindings.json \
  --yes \
  --json
node bin/weclawctl.mjs feedback beep serial:/dev/cu.usbmodem212201 --yes --json
node bin/weclawctl.mjs wakeword configure serial:/dev/cu.usbmodem212201 \
  examples/wakeword/rlcd-agent.wakeword.json \
  --yes \
  --json
node bin/weclawctl.mjs wakeword trigger serial:/dev/cu.usbmodem212201 \
  market_music \
  --source agent \
  --beep \
  --yes \
  --json
node bin/weclawctl.mjs audio now-playing serial:/dev/cu.usbmodem212201 \
  --title "Stocks + Music" \
  --artist "WeClaw Agent" \
  --lyric "行情在跳动，音乐继续往前走" \
  --effect spectrum \
  --beep \
  --yes \
  --json
node bin/weclawctl.mjs queue serial:/dev/cu.usbmodem212201 \
  examples/queues/rlcd-now-playing.queue.json \
  --play \
  --screen \
  --yes \
  --json
node bin/weclawctl.mjs audio play-url serial:/dev/cu.usbmodem212201 \
  "https://music.163.com/song/media/outer/url?id=123456" \
  --format mp3 \
  --duration 30 \
  --yes \
  --json
node bin/weclawctl.mjs audio now-playing mqtt:default \
  --title "Stocks + Music" \
  --artist "WeClaw Agent" \
  --lyric "远程 RLCD 通过 MQTT 控制面更新屏幕" \
  --yes \
  --json
node bin/weclawctl.mjs audio play-url mqtt:default \
  "https://music.163.com/song/media/outer/url?id=123456" \
  --format mp3 \
  --duration 30 \
  --yes \
  --json
node bin/weclawctl.mjs audio play-list mqtt:default \
  /tmp/weclaw-interstellar-netease.queue.json \
  --format mp3 \
  --duration 0 \
  --no-screen \
  --yes \
  --json
node bin/weclawctl.mjs audio url-status mqtt:default --json
node bin/weclawctl.mjs audio url-status serial:/dev/cu.usbmodem212201 --json
node bin/weclawctl.mjs audio stop-url serial:/dev/cu.usbmodem212201 --yes --json
node bin/weclawctl.mjs audio stream serial:/dev/cu.usbmodem212201 \
  ~/Music/authorized-preview.mp3 \
  --duration 15 \
  --yes \
  --json
node bin/weclawctl.mjs app validate examples/bundles/subscription-smoke \
  --device profile:weclaw-waveshare-esp32-s3-rlcd-4.2-vm \
  --instance examples/instances/subscription-smoke.instance.json \
  --json
node bin/weclawctl.mjs app validate examples/bundles/weclawvm-smoke \
  --device profile:rokid-a113 \
  --instance examples/instances/weclawvm-smoke.instance.json \
  --json
node bin/weclawctl.mjs app install mqtt:default \
  examples/bundles/weclawvm-smoke \
  --profile profile:rokid-a113 \
  --instance examples/instances/weclawvm-smoke.instance.json \
  --yes \
  --json
node bin/weclawctl.mjs app install profile:weclaw-waveshare-esp32-s3-rlcd-4.2-vm \
  examples/bundles/subscription-smoke \
  --instance examples/instances/subscription-smoke.instance.json \
  --json
node bin/weclawctl.mjs app install serial:/dev/cu.usbmodem212201 \
  examples/bundles/subscription-smoke \
  --yes \
  --json
node bin/weclawctl.mjs app status serial:/dev/cu.usbmodem212201 --json

Draft Schemas

• weclaw.device_profile.v0.draft
• weclaw.capability_registry.v0.draft
• weclaw.control.v1
• weclaw.app.v2.draft
• weclaw.app_instance.v1.draft
• weclaw.playable_queue.v1
• weclaw.light.timeline.v1
• weclaw.light.bind.v1
• weclaw.wakeword.config.v1
• weclaw.host.v0
• weclaw.lifecycle.result.v0.draft

These names intentionally remain draft until live Device Profile discovery, version negotiation, rollback, and the remaining e-ink/C3 hardware lifecycle checks are complete.

The generic MQTT install envelope is accepted by the current ESP32-S3 and A113 Host implementations, but hardware verification remains profile-specific: RLCD and A113 have existing hardware evidence; ESP32-S3 e-ink still needs the autonomous MQTT App e2e, and ESP32-C3 still needs a Host build and device test.

Compatibility

Use weclawctl bind CODE --name AGENT for BYOA pairing. The package intentionally publishes only the weclawctl executable.