Edge Configuration Reference

Introduction

The config.toml file is the single source of truth for how your Pyvorin Edge Agent behaves. Every sensor, every privacy rule, every cloud endpoint, and every logging preference is declared here. This article is a comprehensive reference. We explain every top-level section, every key, every valid value, and the defaults that apply when a key is omitted. We finish with a full, heavily annotated example config that you can copy and adapt.

Configuration Basics

Pyvorin Edge uses TOML (Tom's Obvious Minimal Language) because it is human-readable, supports comments, and maps cleanly to Python dictionaries. The Config class in pyv_edge_agent/config.py parses the file, substitutes environment variables, merges your values over built-in defaults, and validates required sections.

Environment Variable Substitution

Any value can reference an environment variable using ${VAR} or ${VAR:-default} syntax:

[cloud]
endpoint = "${CLOUD_ENDPOINT}"
api_key = "${CLOUD_API_KEY:-}"  # empty string if unset
  

This is evaluated at load time, not at runtime, so changes to environment variables after startup require a config reload.

Validation

Calling Config.validate() checks for:

• Presence of required sections: sensors, windows, rules, policies, cloud, privacy.
• That sensors.devices is a list.
• That windows.default_size is an integer.
• That cloud.endpoint is non-empty when cloud.enabled is true.

Section: [sensors]

Defines how often the agent polls devices and what devices exist.

Device Table Keys

Each [[sensors.devices]] entry configures one adapter instance.

Example: Three Simulated Sensors

[sensors]
poll_interval_seconds = 5.0

[[sensors.devices]]
name = "office_temp"
ingest_type = "simulator"
sensor_type = "temperature"
unit = "°C"
min_value = 10.0
max_value = 40.0
noise_std = 0.5
baseline = 22.0

[[sensors.devices]]
name = "office_humidity"
ingest_type = "simulator"
sensor_type = "humidity"
unit = "%"
min_value = 0.0
max_value = 100.0
noise_std = 2.0
baseline = 45.0

[[sensors.devices]]
name = "server_room_leak"
ingest_type = "simulator"
sensor_type = "leak"
unit = "bool"
min_value = 0.0
max_value = 1.0
noise_std = 0.0
baseline = 0.0
  

Section: [windows]

Configures ring buffers that hold recent readings in memory for fast rule evaluation.

Section: [rules]

Declares event rules that trigger when conditions are met. Rules are evaluated during each run_once() cycle for every reading.

Rule Item Keys

Example: Temperature and Humidity Rules

[rules]
evaluation_interval_seconds = 10.0

[[rules.items]]
name = "office_overheat"
condition_expr = "ctx.value > 28.0"
severity = "warning"
cooldown_seconds = 300.0

[[rules.items]]
name = "humidity_too_high"
condition_expr = "ctx.value > 70.0"
severity = "critical"
cooldown_seconds = 60.0
  

Section: [policies]

Defines high-level policy defaults. Note that fine-grained privacy rules live in the [privacy] section instead.

Section: [cloud]

Controls outbound cloud synchronisation. When disabled, data stays entirely on the gateway.

Example: Enabled Cloud Sync

[cloud]
enabled = true
endpoint = "https://api.pyvorin.com/v1/ingest"
api_key = "${PYV_API_KEY}"
batch_size = 50
flush_interval_seconds = 30.0
db_path = "/home/pi/pyvorin-edge/data/sync_queue.db"
  

Section: [privacy]

The privacy firewall. Every reading is evaluated against these rules before storage and cloud sync.

Privacy Rule Keys

Example: Privacy Rules

[privacy]
enabled = true
default_action = "allow"

[[privacy.rules]]
sensor_pattern = "camera_*"
action = "drop"

[[privacy.rules]]
sensor_pattern = "badge_*"
action = "hash"

[[privacy.rules]]
sensor_pattern = "internal_*"
action = "mask"
  

Section: [logging]

Controls how the agent writes diagnostic output.

Section: [health]

Configures the built-in HTTP health server.

Section: [store] (Optional)

Controls the SQLite evidence store path.

Complete Annotated Example Config

# /home/pi/pyvorin-edge/config.toml
# Pyvorin Edge Agent Configuration
# ================================

# [sensors] defines what data sources the agent monitors and how often.
[sensors]
poll_interval_seconds = 5.0

# Device 1: Simulated office temperature sensor
[[sensors.devices]]
name = "office_temp"
ingest_type = "simulator"
sensor_type = "temperature"
unit = "°C"
min_value = 10.0
max_value = 40.0
noise_std = 0.5
baseline = 22.0

# Device 2: Simulated office humidity sensor
[[sensors.devices]]
name = "office_humidity"
ingest_type = "simulator"
sensor_type = "humidity"
unit = "%"
min_value = 0.0
max_value = 100.0
noise_std = 2.0
baseline = 45.0

# Device 3: Simulated leak detector (boolean)
[[sensors.devices]]
name = "server_room_leak"
ingest_type = "simulator"
sensor_type = "leak"
unit = "bool"
min_value = 0.0
max_value = 1.0
noise_std = 0.0
baseline = 0.0

# [windows] configures in-memory ring buffers for fast access.
[windows]
default_size = 200          # Keep last 200 readings per device
default_dtype = "float"     # Storage type hint

# [rules] defines event conditions that trigger alerts.
[rules]
evaluation_interval_seconds = 10.0

[[rules.items]]
name = "office_overheat"
condition_expr = "ctx.value > 28.0"
severity = "warning"
cooldown_seconds = 300.0

[[rules.items]]
name = "server_room_leak_detected"
condition_expr = "ctx.value >= 0.5"
severity = "critical"
cooldown_seconds = 60.0

# [policies] sets high-level defaults.
[policies]
default_action = "allow"
rules = []

# [cloud] controls outbound synchronisation.
[cloud]
enabled = false             # Set to true and configure endpoint to enable
endpoint = ""
api_key = ""
batch_size = 100
flush_interval_seconds = 60.0

# [privacy] filters sensitive data before storage or upload.
[privacy]
enabled = true
default_action = "allow"

[[privacy.rules]]
sensor_pattern = "camera_*"
action = "drop"

[[privacy.rules]]
sensor_pattern = "badge_*"
action = "hash"

# [logging] controls diagnostic output.
[logging]
level = "INFO"
format = "json"             # Use "text" for human-readable output during debugging

# [health] exposes /health and /metrics over HTTP.
[health]
port = 8080
enabled = true

# [store] sets the SQLite evidence database path.
[store]
path = "/home/pi/pyvorin-edge/data/edge_store.db"
  

Config Reload at Runtime

The EdgeAgent supports reloading configuration without restarting the process, but be aware that reload_config() only updates the _config object. Some components (adapters, buffers, logging) are only created during _init_components(), which runs at startup. For deep changes (adding sensors, changing ports), a full restart is recommended.

# Programmatic reload
agent.reload_config()
  

Summary

The config.toml file controls every aspect of Pyvorin Edge behaviour. Use the tables above as a quick reference, copy the annotated example as a starting template, and remember that absolute paths and environment variable substitution make your configuration portable and secure.