94 lines
7.4 KiB
Markdown
94 lines
7.4 KiB
Markdown
# Pigway Frame Flow
|
||
|
||
[简体中文](README.zh-CN.md) | 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:
|
||
|
||
```bash
|
||
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:18787` 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](docs/NAS.md), [build mirrors and caching](docs/BUILDING.md), and [Gitea deployment/rollback](docs/deployment/GITEA_CD.md). No firewall, router or reverse-proxy settings are changed automatically.
|
||
|
||
For a local mock demo, use Python 3.14:
|
||
|
||
```bash
|
||
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.
|
||
|
||
### 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.
|
||
- Read-only NAS folders, Synology Photos person filtering, WebDAV and optional cloud-drive connectors. Each source has its own configuration and authorization.
|
||
- 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](docs/PHOTO_SOURCES.md), [automatic collages](docs/AUTOMATIC_COLLAGE.md) and [integration setup/limits](docs/EXTENSIONS.md).
|
||
|
||
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
|
||
|
||
```text
|
||
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](docs/integrations/TICKTAR.md).
|
||
|
||
### 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](docs/PUBLICATION.md), [LICENSE](LICENSE) and [NOTICE](NOTICE.md).
|
||
|
||
KoKonna is a supported integration. This project is not affiliated with or endorsed by KoKonna.
|
||
|
||
### Development and known limitations
|
||
|
||
```bash
|
||
.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](https://tea.pigway.com/way/pigway-raspberry-pi-agent) · [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console) · [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)
|