divoom-agent

Opinionated semantic ambient API for Divoom pixel panels. Translates concepts like "the agent is thinking" or "the build shipped" into visual patterns (color + animation).

This is the middle layer of a three-library stack:

divoom-protocol  ← bytes/BLE/encoder. No AI, no opinions.
divoom-agent     ← THIS PACKAGE. Semantic API. Opinions about color and motion live here.
divoom-agent-mcp ← MCP server. Exposes the agent to LLMs as tools.

Status

Alpha. APIs may shift before 1.0. Built and validated against the v0.2 divoom-protocol BLE decode.

Install

pip install -e .[dev]
pytest                              # run pattern unit tests
python examples/status_demo.py      # walk through the status vocabulary on a real panel

API

from divoom_agent import DivoomAgent

async with await DivoomAgent.create() as agent:
    # Ambient status — loops until replaced or stopped
    await agent.status_thinking()       # slow blue breath
    await agent.status_working()        # amber pulse
    await agent.status_success()        # green flash → dim green hold
    await agent.status_error()          # red flash → dim red hold
    await agent.status_alert(level=2)   # severity 1=yellow / 2=orange / 3=red

    # Discrete notifications
    await agent.notify_shipped()        # green checkmark
    await agent.notify_celebrate()      # rainbow burst
    await agent.notify_message()        # blue dot pulse

    # Progress
    await agent.progress_percentage(50) # static fill bar
    await agent.progress_indeterminate()# orbiting comet

    # Direct/raw escape hatches
    await agent.paint(pixels_16x16)     # 256 RGB tuples, your own pixel art
    await agent.color(255, 0, 255)      # solid Lighting magenta
    await agent.brightness(50)
    await agent.clear()                 # black panel
    await agent.clock()                 # built-in clock channel

    # Generative
    await agent.start_mondrian(fps=2.0) # ambient Mondrian cycle

    # Streaming control
    await agent.start_stream(frames, fps=4.0)
    await agent.stop_animation()        # cancel any running animation

Each method that starts an animation cancels the previous one — you don't need to manually stop before switching status. paint(), color(), and clear() also stop animations.

Design philosophy

• Small visual vocabulary, recognizable from across a room. Blue=thinking, green=success, red=error, amber=working, yellow→orange→red for severity. Same conventions as traffic lights and OS notification badges.
• Loops, not one-shots. Status patterns loop indefinitely because ambient state is ambient — the panel keeps showing it until something changes.
• Calm by default. Thinking is a slow 2s breath, not a frantic flash. The panel should not demand attention; you should be able to glance at it.
• Notifications are still loops. A "shipped" notification holds the dim green so you don't miss it if you weren't looking when the flash happened. Move to a different status to clear.

Customization

Visual patterns live in divoom_agent/patterns.py. Each is a small pure function that returns a list of 16x16 frames. Edit colors, brightness curves, or pulse rates there — no need to touch the agent state machine.

License

MIT.