Configuration¶

Overview¶

The Wine Platform uses a layered configuration system shared across the manual lane and the automated vision lane.

Configuration is split across:

shared environment variables
worker-specific environment overrides
INI-based vision geometry and runtime settings
Python path/bootstrap helpers
service and scheduler definitions

The key files and modules are:

Type	File / Module	Role
Shared env	`shared/config/shared.env`	platform-wide variables
Worker env	`shared/config/pince_shelf.env`	vision-worker-specific overrides
Vision INI	`shared/config/pince_shelf.ini`	shelf geometry, runtime path entries, tracking settings
Path bootstrap	`pince_shelf/utils/paths.py`	base path constants and config directory discovery
Settings loader	`pince_shelf/config/settings.py`	merges env + ini and resolves final runtime config
Services	`/etc/systemd/system/*.service`	backend / kiosk runtime definition
Scheduler	systemd timers (wine-inventory-stock.timer, wine-platform-backup.timer)	scheduled execution

Configuration Layers¶

flowchart TD

SHARED["shared.env"]
PINCEENV["pince_shelf.env"]
INI["pince_shelf.ini"]

PATHS["paths.py"]
SETTINGS["settings.py"]

API["FastAPI backend"]
KIOSK["Qt kiosk"]
WORKERS["Vision workers"]

SHARED --> SETTINGS
PINCEENV --> SETTINGS
INI --> SETTINGS
PATHS --> SETTINGS

SETTINGS --> WORKERS
SETTINGS --> API
SETTINGS --> KIOSK

The practical split is:

paths.py provides base filesystem anchors
settings.py loads and merges env + ini
workers use the resulting PinceConfig

Shared Environment File¶

Location¶

/home/pi/wine_platform/shared/config/shared.env

This file contains platform-wide settings shared across the project.

Typical uses include:

API-related variables
common data roots
shared runtime paths
values consumed by backend and kiosk services

This file is loaded first by the worker settings layer. Later files may override it. :contentReference[oaicite:8]{index=8}

Worker Environment File¶

Location¶

/home/pi/wine_platform/shared/config/pince_shelf.env

This file contains vision-worker-specific configuration.

It is loaded after shared.env, so its values override shared defaults. :contentReference[oaicite:9]{index=9}

This file is especially important for values such as:

PINCE_RTSP_URL
PINCE_RTSP_URL1
PINCE_DATA_DIR
PINCE_DATA_DIR_DARWIN
PINCE_TAPO_PLUG_IP
PINCE_TAPO_USERNAME
PINCE_TAPO_PASSWORD
PINCE_TAPO_ALIAS
PINCE_TAPO_LIGHT_STABILIZE_SECONDS
PINCE_ONVIF_USER
PINCE_ONVIF_PASSWORD
PINCE_ONVIF_PORT
PINCE_PROPOSALS_OUT_DIR
PINCE_PROPOSALS_EVIDENCE_DIR
motion-runtime parameters such as PINCE_MOTION_*

Load order¶

settings.py explicitly loads env files in this order:

shared.env
pince_shelf.env

Later overrides earlier. This makes pince_shelf.env the correct place for worker-only runtime overrides. :contentReference[oaicite:11]{index=11}

Vision INI File¶

Location¶

/home/pi/wine_platform/shared/config/pince_shelf.ini

This file stores vision pipeline structure and calibration data.

Important areas include:

[main_points] for shelf-corner geometry
[paths] for snapshot / crop / model directories
tracking and calibration parameters

The ROI calibration UI writes the authoritative corner points into [main_points]. :contentReference[oaicite:12]{index=12}

Example:

[main_points]
top_left = 120,65
top_right = 1015,60
bottom_right = 1020,720
bottom_left = 110,735

`paths.py` — Base Path Bootstrap¶

Module:

workers/wine_inventory/src/pince_shelf/utils/paths.py

This module provides the base path constants used by the worker lane:

PROJECT_ROOT
WINE_PLATFORM_ROOT
CONF_DIR
DATA_DIR :contentReference[oaicite:13]{index=13}

Main roles¶

`PROJECT_ROOT`¶

Root of the worker project:

workers/wine_inventory

`WINE_PLATFORM_ROOT`¶

Root of the monorepo:

wine_platform

`CONF_DIR`¶

Shared configuration directory, resolved using this priority:

WINE_PLATFORM_CONF_DIR
/home/pi/wine_platform/shared/config
<repo>/shared/config fallback for dev/Mac layouts :contentReference[oaicite:14]{index=14}

`DATA_DIR`¶

Optional worker-local data root, based on:

PINCE_DATA_DIR
or fallback to <PROJECT_ROOT>/data :contentReference[oaicite:15]{index=15}

This module exists so worker scripts do not need hard-coded Pi-only paths.

`settings.py` — Unified Worker Config Loader¶

Module:

workers/wine_inventory/src/pince_shelf/config/settings.py

This is the main loader for worker configuration. It:

loads env files
loads pince_shelf.ini
parses calibration points
resolves runtime paths
returns a structured PinceConfig object

Path Resolution Rules¶

A critical behavior of settings.py is path resolution.

Linux / Raspberry Pi¶

Uses:

_resolve_path(raw)

This anchors data/... paths to:

PINCE_DATA_DIR

if defined, otherwise to:

<PROJECT_ROOT>/data

:contentReference[oaicite:17]{index=17}

macOS / Darwin¶

Uses:

_resolve_path_darwin(raw)

This anchors data/... paths to:

PINCE_DATA_DIR_DARWIN

Shared rule set¶

_resolve_path_base() applies these rules:

absolute paths remain unchanged
data/... paths are redirected to configured data root
other relative paths are anchored to PROJECT_ROOT :contentReference[oaicite:19]{index=19}

This is what allows the same pince_shelf.ini to work across Pi and Mac.

Main Runtime Paths From `settings.py`¶

The worker config builds these key path entries from the INI [paths] section:

crop_out
det_out
snapshot
model_dir :contentReference[oaicite:20]{index=20}

Defaults are:

data/cells_runtime
data/cells_runtime_res
data/snapshots
data/models

Because of the path resolver, these can transparently map to NAS-backed storage.

Additional Runtime Config Produced By `settings.py`¶

Besides paths, settings.py also builds structured runtime config for:

Camera¶

rtsp_url
rtsp_url1

Tapo light control¶

plug IP
username
password
alias
stabilization seconds

ONVIF access¶

username
password
port

API integration¶

api_base

Proposal pipeline¶

output dir
evidence dir
confidence threshold
model metadata

Motion runtime¶

session file
delays
retry intervals
camera index

Why `shared.env` and `pince_shelf.env` Both Exist¶

This split is intentional.

`shared.env`¶

Use for: - platform-wide defaults - values relevant beyond one worker - shared infrastructure variables

`pince_shelf.env`¶

Use for: - worker-only secrets and overrides - camera URLs - light-control values - Mac/Pi data-root differences - motion runtime tuning

This keeps the worker lane configurable without polluting global settings. :contentReference[oaicite:22]{index=22}

Practical Multi-Environment Model¶

The same logical data may be addressed from different machines:

Environment	Typical data root
Synology NAS	`/volume2/web/web_images/Stock_vision`
Raspberry Pi	`/mnt/nasWeb/web_images/Stock_vision`
macOS	`/Volumes/web/web_images/Stock_vision`

The combination of:

paths.py
PINCE_DATA_DIR
PINCE_DATA_DIR_DARWIN
load_pince_config_darwin()

is what makes this portable.

Operational Guidance¶

When to edit `shared.env`¶

Edit when changing shared platform settings.

When to edit `pince_shelf.env`¶

Edit when changing worker-specific runtime behavior, camera/light config, or Pi/Mac data roots.

When to edit `pince_shelf.ini`¶

Edit when changing calibration points, vision paths, or shelf/tracking configuration.

When to check `paths.py`¶

Check when configuration lookup or config directory discovery behaves differently across Pi and Mac.

Backup Priority¶

The most important config artifacts to back up are:

shared/config/shared.env
shared/config/pince_shelf.env
shared/config/pince_shelf.ini

These three files together define the worker lane’s effective runtime configuration.

Configuration (UPDATED)¶

Docs Environment¶

The documentation environment has been decoupled from the repository.

Previous (deprecated)¶

wine_platform/.venv-docs

Current (recommended)¶

/home/pi/venvs/docs

Activate Docs Environment¶

source /home/pi/venvs/docs/bin/activate

Build Documentation¶

cd /home/pi/wine_platform mkdocs build

This generates static HTML in: /home/pi/wine_platform/site

Serve Documentation (systemd)¶

Docs are now served via systemd service:

wine-platform-docs.service

Access: http://:8088

No need to run mkdocs serve.

Rebuild Workflow¶

After modifying docs: /home/pi/wine_platform/tools/rebuild_docs.sh

Then refresh browser.

Notes¶

.venv-docs must NOT exist in repo
virtual environments must be outside repo
site/ is generated and not version-controlled

Summary¶

The worker configuration system is not just:

.env + .ini

It is actually a four-part configuration architecture:

shared.env — shared platform defaults
pince_shelf.env — worker overrides
pince_shelf.ini — shelf and pipeline structure
paths.py + settings.py — platform-aware resolution and assembly

That combination is what allows the same vision codebase to run consistently across:

Raspberry Pi production
Synology-backed storage
Mac-based calibration and development

Backup Configuration¶

Overview¶

The Wine Platform uses a versioned rsync backup strategy from Raspberry Pi to Synology NAS.

Structure¶

/mnt/nasData/wine_platform_backup/ ├── daily/ │ ├── YYYY-MM-DD/ └── safe/

Rules¶

daily is automated
only last 5 days are kept
safe is manual only
safe is NEVER modified by automation

Systemd Units¶

Service: wine-platform-backup.service

Timer: wine-platform-backup.timer

Behavior¶

creates daily snapshot folder
performs rsync copy
rotates old backups (>5 days)
logs locally

Configuration¶

Overview¶

Configuration Layers¶

Shared Environment File¶

Location¶

Worker Environment File¶

Location¶

Load order¶

Vision INI File¶

Location¶

paths.py — Base Path Bootstrap¶

Main roles¶

PROJECT_ROOT¶

WINE_PLATFORM_ROOT¶

CONF_DIR¶

DATA_DIR¶

settings.py — Unified Worker Config Loader¶

Path Resolution Rules¶

Linux / Raspberry Pi¶

macOS / Darwin¶

Shared rule set¶

Main Runtime Paths From settings.py¶

Additional Runtime Config Produced By settings.py¶

Camera¶

Tapo light control¶

ONVIF access¶

API integration¶

Proposal pipeline¶

Motion runtime¶

Why shared.env and pince_shelf.env Both Exist¶

shared.env¶

pince_shelf.env¶

Practical Multi-Environment Model¶

Operational Guidance¶

When to edit shared.env¶

When to edit pince_shelf.env¶

When to edit pince_shelf.ini¶

When to check paths.py¶

Backup Priority¶

Configuration (UPDATED)¶

Docs Environment¶

Previous (deprecated)¶

Current (recommended)¶

Activate Docs Environment¶

Build Documentation¶

Serve Documentation (systemd)¶

Rebuild Workflow¶

Notes¶

Summary¶

Backup Configuration¶

Overview¶

Structure¶

Rules¶

Systemd Units¶

Behavior¶

`paths.py` — Base Path Bootstrap¶

`PROJECT_ROOT`¶

`WINE_PLATFORM_ROOT`¶

`CONF_DIR`¶

`DATA_DIR`¶

`settings.py` — Unified Worker Config Loader¶

Main Runtime Paths From `settings.py`¶

Additional Runtime Config Produced By `settings.py`¶

Why `shared.env` and `pince_shelf.env` Both Exist¶

`shared.env`¶

`pince_shelf.env`¶

When to edit `shared.env`¶

When to edit `pince_shelf.env`¶

When to edit `pince_shelf.ini`¶

When to check `paths.py`¶