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.
Metadata
Release files for divoom-agent 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| divoom_agent-0.1.0.tar.gz | 65.1 kB | Without provenance | Details for divoom_agent-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| divoom_agent-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for divoom_agent-0.1.0-py3-none-any.whl |
Total release size: 121.7 kB
Release files / divoom_agent-0.1.0.tar.gz
| Download URL | divoom_agent-0.1.0.tar.gz |
|---|---|
| Size | 65.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3121378ab8d3908af8b10690070ca4fd0e7f64e8d3a957c9d75ec5688587676a
|
|
BLAKE2b-256 checksum How to use checksums |
0a845eb5c04b62aaae2c41f541455dccb9a37c379e067355f0a7381e58f9af80
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / divoom_agent-0.1.0-py3-none-any.whl
| Download URL | divoom_agent-0.1.0-py3-none-any.whl |
|---|---|
| Size | 56.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
48d8c184f7faa0b90304c553d309f22e3e8858da1d4f9d5ba6a390eb9bfa77d3
|
|
BLAKE2b-256 checksum How to use checksums |
40cf2e441627cc4894d8bee62ba2b5621ce9e9b7e2648f25a3f9283118fb28e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for divoom-agent 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.