PIGWay Frame Flow
Development currently supports Python 3.14.x. See contributing and security reporting.
简体中文 | English
PIGWay Frame Flow is a lightweight, self-hosted platform for programmable smart-frame automation. It runs independently on a NAS or server, with its own Web UI, image library, rendering, scheduler and REST API. KoKonna is a supported device integration; external applications do not need its credentials or SDK.
Installation
Deploy with Docker Compose. The current default configuration and verified platform are AMD64:
cp .env.example .env
# Set a strong FRAME_FLOW_TOKEN; keep mock=true and writes=false initially.
chmod 600 .env
mkdir -p data/images data/generated data/cache config
sudo chown -R 10333:10333 data config
./scripts/build-verify.sh
# Create the browser administrator account; enter its password interactively.
docker compose run --rm --no-deps -e PYTHONPATH=/app \
-v "$PWD/scripts:/bootstrap:ro" --entrypoint python pigway-frame-flow \
/bootstrap/create-account.py --username admin --config-dir /config
docker compose up -d
Open http://127.0.0.1:6005 and sign in with the account you created. The browser uses an HttpOnly session cookie; it does not require an API token. Remembered sessions last 30 days. Change the password or sign out in Settings. FRAME_FLOW_TOKEN authenticates external API clients and is separate from the KoKonna API key.
The published interface defaults to loopback. For LAN access, explicitly set WEB_BIND to your NAS LAN address and choose an available WEB_PORT. See Synology deployment, build mirrors and caching. No firewall, router or reverse-proxy settings are changed automatically.
For a local mock demo, use Python 3.14:
python3.14 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python scripts/create-account.py --username admin
.venv/bin/python scripts/run_local.py
The demo forces mock mode and disables device writes. Data and configuration remain in data/ and config/ across restarts.
Synology Photos API sources work without /photos or NFS mounts, with shared/current-account personal spaces, people filters and bounded on-demand XL preview caching. Original downloads are not supported by this verified implementation. See Photos API and Ubuntu migration candidate.
Features and boundaries
- Chinese and English Web UI, light/dark themes, account login, device dashboard and image previews.
- Local staging and KoKonna cloud gallery, uploads, image switching, stars, source/task filters and batch actions.
- Aspect-ratio-preserving contain/cover/smart conversion, color/grayscale profiles and orientation selection for photo sources.
- Seven templates: Daily Dashboard, Weather, Calendar, Quote, Photo + Text, Daily Poetry and System Alert.
- Layout Studio for collages/posters with 1–12 images; optional OpenAI-compatible layout planning and source-driven automatic collages.
- Device-bound schedules, ordered/random playlists, temporary priority overrides, restore and persistent operation history.
- Synology Photos person filtering, WebDAV and optional cloud-drive connectors. Each source has its own folder and filter settings. People filtering uses one shared Synology Photos sign-in; WebDAV and cloud-drive credentials belong to their respective sources.
- Optional weather, calendar, monitoring, AI, MQTT and webhook integrations. Provider configuration is required; an unconnected provider is not a working connection.
Templates render images, including text-only templates. Choose a template, edit its data, generate a preview, then display it. Preview generation and saving template settings do not update the frame. Photo + Text and Daily Dashboard can include a selected local photo; other templates do not automatically choose one. Scheduled template jobs render afresh on each run. See photo sources, automatic collages and integration setup/limits.
Real weather uses the configured provider/location and is refreshed when rendered; it does not update an already displayed image by itself. Official KoKonna widgets are separate from Frame Flow templates and require optional vendor-account authorization. API-key access remains independent.
Device integration and API
Providers → Templates / Renderers → Generated image
Web UI / Scheduler / REST API → DisplayService → FrameDeviceDriver → KoKonna
↓
SQLite: jobs, operations, history, overrides, assets
Configure the device key privately through .env or a secret file. Start with KOKONNA_MOCK=true and KOKONNA_WRITE_ENABLED=false; after mock verification, connect read-only before explicitly enabling writes. Multi-device definitions use config/devices.yml and device-specific key references. Vendor code stays in drivers/kokonna; other applications use the same service API as the Web UI.
The public API is /api/v1, with OpenAPI at /openapi.json and Swagger UI at /docs. Display/render/upload operations return HTTP 202 and an operation ID; poll /api/v1/operations/{id} for the outcome. Idempotency-Key prevents duplicate dispatch, and X-Request-ID links requests to history. An uncertain write blocks subsequent mutations until read-only reconciliation or explicit administrator acknowledgement; it is never automatically replayed.
Ticktar integration is optional. Frame Flow has no runtime dependency on Ticktar and never accesses its database. See the external integration contract.
Storage and security
Docker persists /data/frameflow.db, images/generated/cache under /data, and private configuration/session files under /config. It runs as UID/GID 10333 with a read-only root filesystem, its own bridge network, unless-stopped restart policy and bounded stdout/stderr logs. No privileged mode, host network or Docker socket is required.
Passwords are hashed; browser mutations require CSRF protection. API keys and provider credentials stay server-side and must never enter Git or logs. CORS is disabled unless origins are explicitly configured. /health checks the service; /ready checks local dependencies without making cloud availability a restart trigger. See public repository privacy, LICENSE and NOTICE.
KoKonna is a supported integration. This project is not affiliated with or endorsed by KoKonna.
Development and known limitations
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/python -m ruff check pigway_frame_flow tests scripts
.venv/bin/python -m ruff format --check pigway_frame_flow tests scripts
.venv/bin/python -m mypy pigway_frame_flow
.venv/bin/python -m pytest -q
.venv/bin/python -m pip_audit -r requirements.lock --no-deps --disable-pip
Tests mock cloud/device calls. CI also verifies an isolated Docker build, readiness, smoke tests, restart and cleanup. External fork PRs do not execute on the production-capable NAS runner.
Cloud synchronization does not prove the physical pixels refreshed. KoKonna cloud uploads activate immediately, so upload-only uses local staging. Native slideshow membership editing is unavailable; avoid running native and Frame Flow playback simultaneously. Smart cropping is a saliency heuristic, not guaranteed face detection. The service uses one worker and is not designed for multiple replicas. Browser OAuth, AI daily-art scheduling, additional calendar recurrence features and more device drivers remain roadmap items.
Related projects: PIGWay Raspberry Pi Agent · PIGWay Device Console · PIGWay Yahboom Cooling HAT