@openbrt/weclawbotctl

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

This package is the 0.1.39 preview for testing the audioctl capability model through the long-term weclawbotctl 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

• 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 weclawbot.playable_queue.v1 queue and installs a one-call VM app that renders now-playing, lyric, and audio visualizer 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 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.
• app validate for weclawbot.app.v2.draft bundles and weclawbot.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. Agents should prefer the network form audio play-url mqtt:default URL for music on remote RLCD devices: they provide an authorized direct MP3 platform/CDN URL, 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 weclawbotctl, not agent-authored scripts.

Examples

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

Draft Schemas

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

These names intentionally remain draft until real A113 and ESP32-S3 validation exists.

Compatibility

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