pigway-console-adapter-frame-flow/README.md

PIGWay Console Adapter — Frame Flow

简体中文 | English

An independent, read-only ZIP adapter for PIGWay Device Console, using adapter protocol v1 and the Python standard library. It connects to Frame Flow over HTTP; no Frame Flow package or extra service is required at runtime.

Installation

1. Build the ZIP below, upload it under Console Machine management, and enable it.
2. Add a PIGWay Frame Flow device with the HTTP(S) origin (without /api/v1) and a Frame Flow API token, not a KoKonna key or browser password.
3. Restricted API clients need devices:read and jobs:read. The default FRAME_FLOW_TOKEN is also supported. Use HTTPS across untrusted networks.
4. View cards, alerts and history. Collection defaults to 60 seconds; labels follow the Console language and resource names come from the API or Console display settings.

The adapter reads /health, /ready, /api/v1/devices and /api/v1/jobs. It never refreshes a frame or runs a job. Device reads may use Frame Flow's existing vendor read-only status cache.

Status semantics

Reports readiness, device/job counts, frame connectivity and available battery levels, and job enablement/latest terminal result. FAILED and UNKNOWN produce distinct alerts; pending or running jobs are not reported as successful. A disabled job retains its last failure until a successful result replaces it.

HTTP 503 from /ready means not ready. Authentication, timeout and malformed-response failures preserve the previous Console snapshot and mark collection as unsuccessful. Only a complete successful snapshot confirms recovery. History starts with collection; an API status is not proof that a physical display refreshed. Mock status remains mock status.

Development

Install pytest and ruff in a virtual environment, then run python -m pytest -q. Optional Frame Flow API contract tests require Frame Flow and its dependencies; otherwise they are skipped. With a sibling Frame Flow environment, use PYTHONPATH=../pigway-frame-flow ../pigway-frame-flow/.venv/bin/python -m pytest -q. Optional browser checks use Playwright and node tests/ui.cjs.

For development, set PIGWAY_ADAPTER_PATH to this repository's absolute plugin path. Newly installed ZIPs are disabled by default. Additional history label translations require matching Console support.

Build

Current adapter version: 1.0.5.

mkdir -p dist
python3 package.py plugin dist/pigway-frame-flow-1.0.5.zip

Documentation

Use System configuration → Frame Flow → Frame Flow connection to edit the service URL, API token and optional management URL. The overview link defaults to the service URL. A blank token preserves the existing credential.