agentcube-feed

HTTP feed server for AgentCube desk cubes.

The cube stores a URL in config, periodically GETs it, and renders the JSON response.
All business logic lives here — no firmware flash to change what the cube shows.

┌─────────┐   GET /v1/feed    ┌──────────────────┐
│ AgentCube│ ───────────────► │ agentcube-feed   │
│ firmware │ ◄─────────────── │ (your logic)     │
└─────────┘   JSON scene /    └──────────────────┘
              draw commands

Part of CubeFW / AgentCube (GeekMagic-class desk cubes).

Quick start

cd agentcube-feed
python3 server/app.py
# http://0.0.0.0:8787/

curl -s http://127.0.0.1:8787/v1/feed | python3 -m json.tool
curl -s 'http://127.0.0.1:8787/v1/feed?feed=clock'
curl -s http://127.0.0.1:8787/v1/feed/agent

Cube config (future firmware)

{
  "feed_url": "http://192.168.1.10:8787/v1/feed",
  "feed_enabled": true
}

Use a LAN IP the cube can reach (not 127.0.0.1 from the device’s point of view).

Protocol

See PROTOCOL.md — versioned JSON: scene and/or commands, plus poll_ms.

Endpoint	Purpose
GET /health	Liveness
GET /v1/feed	Default feed (?feed=name)
GET /v1/feed/<name>	Named feed
GET /v1/protocol	Protocol markdown

Built-in feeds (scaffold)

Name	What
demo	Rotating message / status / progress / agent
clock	Time via raw draw commands
agent	Stub agent state (replace with real backend)

Add a feed: create server/feeds/myfeed.py with build(ctx) -> dict, register in server/app.py → FEEDS.

Design

• Stateless GET — easy to mock, cache, or replace with nginx + static JSON for trivial cases
• Scenes for common UIs; commands for full control (same primitives as draw API)
• Server decides poll_ms so busy feeds can refresh faster

Layout

agentcube-feed/
  PROTOCOL.md          # contract for firmware + server
  README.md
  server/
    app.py             # HTTP server
    feeds/             # pluggable builders
  examples/
    sample_responses.json

Requirements

Python 3.9+ standard library only.

License

MIT