piglow-signal

name	piglow-signal
description	Communicate agent status to the user via the PiGlow LED board on the Raspberry Pi. Use to show "working", "done", "problem", or "ready" without saying it in chat. Only applies when PiGlow is attached and the host PiGlow service is running.
metadata	{"openclaw":{"emoji":"💡","requires":{"bins":["curl","bash"]}}}

PiGlow signal — status via LED (never crash, silent if unavailable)

The PiGlow is a multi-colour LED board on the Pi. This skill lets the agent set its status visually so the user can see "I'm on it" or "Done" at a glance. All calls are silent and never fail the run: if the service or hardware is missing, nothing happens and the agent continues.

When to use

• Start of a task (e.g. user asked for something that will take a moment): set thinking so the Pi shows blue.
• Task completed successfully: set success so the Pi shows a short green confirmation.
• Task failed or error: set error so the Pi shows red.
• Warning / partial failure: set warning (amber).
• Need to draw attention (e.g. reminder, alert): set attention (yellow double-flash).
• Back to idle (ready for next request): set idle (dim white) or off.
• Open for business (bot just started or user sent /reset): set ready — three green flashes then idle. Use for startup signal and when handling /reset.

Use this in addition to your normal reply. Do not mention "PiGlow" or "LED" in the user-facing message.

Pipeline (execute in order)

STEP 1 — When you start working on a request that will take more than a few seconds

Run once at the start of your work (optional but recommended):

exec: bash /home/openclaw/.openclaw/workspace/skills/piglow-signal/scripts/signal.sh thinking

No need to check return value. Continue with your tools and skills as usual.

STEP 2 — When you finish (success or failure)

Before or after sending your reply, set the outcome:

• Success:
  exec: bash /home/openclaw/.openclaw/workspace/skills/piglow-signal/scripts/signal.sh success
• Error / failed:
  exec: bash /home/openclaw/.openclaw/workspace/skills/piglow-signal/scripts/signal.sh error
• Warning / partial:
  exec: bash /home/openclaw/.openclaw/workspace/skills/piglow-signal/scripts/signal.sh warning

You can run this in the same run as your final message. Do not wait for or interpret the script output.

STEP 3 — Optional: back to idle

When the conversation is idle and you are ready for the next request:

exec: bash /home/openclaw/.openclaw/workspace/skills/piglow-signal/scripts/signal.sh idle

Or off to turn all LEDs off.

Best-practice colour semantics (do not expose in chat)

State	Colour	Meaning (UX)
idle	Dim white	Ready; low attention
thinking	Blue	Working / loading
success	Green (brief)	Task completed successfully
warning	Orange	Caution / partial issue
error	Red	Failure / error
attention	Yellow (double-flash)	Needs user attention
ready	Green (triple flash → idle)	Bot up / open for business; use for startup and /reset
off	Off	LEDs off

Keep signals consistent: same state = same meaning every time. Avoid rapid flashing; the service uses short, clear patterns.

Rules

• Never crash the agent: The script always exits 0. If the PiGlow service or hardware is missing, the exec succeeds and does nothing.
• Never mention PiGlow or LEDs in the user-facing reply. The user sees the light; they do not need to hear "I set the LED to success."
• Use thinking when you start a multi-step or slow task; use success or error when you finish, so the user gets visual feedback even before reading the message.
• Optional: use idle when you are done and waiting for the next request, so the Pi shows "ready" instead of staying on the last state.

Host setup (for the human)

The PiGlow service must run on the Pi host (not in the container), on port 18793. Start it with:

python3 /path/to/agents/pibot/workspace/piglow/piglow_service.py

Or use a systemd unit. I2C must be enabled (e.g. raspi-config → Interface Options → I2C). If PiGlow is not attached or I2C is off, the service still runs and returns piglow_available: false; the skill continues to work and simply does not change any LEDs.