# PIGWay Console Adapter — Frame Flow

[简体中文](README.zh-CN.md) | 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.2**.

```sh
mkdir -p dist
python3 package.py plugin dist/pigway-frame-flow-1.0.2.zip
```

[Documentation](docs/README.md)