Five-Minute Tour

Introduction

Tested with: Python 3.12.3, GCC 13.3.0, Pyvorin Edge SDK 1.0.5-edge, Ubuntu 24.04 LTS (x86_64 & ARM64). Run python3 --version and gcc --version to verify your environment.

Sometimes the best way to learn is to follow a story. In this article, you are Alex, a facilities engineer who just received a Raspberry Pi 5 to monitor a server room. You have five minutes before a meeting, and you want to see live sensor data on your screen. This walkthrough takes you from a blank Pi to a working dashboard with a triggered event, every command included, every output shown.

Minute 0: The Blank Pi

You SSH into your Pi. It is running Raspberry Pi OS 64-bit, Python 3.12 is installed, and you have already created the virtual environment during a previous coffee break. You just need to get moving.


ssh pi@192.168.1.50
cd ~/pyvorin-edge
source .venv/bin/activate

The prompt now shows (.venv). You are ready.

Minute 1: Install and Configure

You already installed Pyvorin Edge, but today you want a fresh config for the server room. You write a minimal config.toml with one simulated temperature sensor. In the real world, this would be a physical sensor on GPIO or MQTT; for the tour, the simulator lets us see data immediately without extra hardware.


cat > ~/pyvorin-edge/config.toml << 'EOF'
[sensors]
poll_interval_seconds = 2.0

[[sensors.devices]]
name = "server_room_temp"
ingest_type = "simulator"
sensor_type = "temperature"
unit = "°C"
min_value = 10.0
max_value = 50.0
noise_std = 0.5
baseline = 24.0

[windows]
default_size = 50
default_dtype = "float"

[rules]
evaluation_interval_seconds = 5.0
items = []

[policies]
default_action = "allow"
rules = []

[cloud]
enabled = false
endpoint = ""
api_key = ""
batch_size = 100
flush_interval_seconds = 60.0

[privacy]
enabled = true
rules = []

[logging]
level = "INFO"
format = "json"

[health]
port = 8080
enabled = true
EOF

You chose a 2-second poll interval so the data feels lively. The baseline temperature is 24 °C, typical for a well-cooled server room.

Minute 2: Start the Agent

You start the agent in the foreground so you can watch the logs scroll by.


cd ~/pyvorin-edge
pyv-edge --config config.toml

What You See


{"ts": 1717100000.00, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "Health server listening on port 8080"}
{"ts": 1717100000.01, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "EdgeAgent started"}
{"ts": 1717100000.02, "level": "INFO", "logger": "pyv_edge_agent.local_store.sqlite_store", "msg": "Schema initialized (version 1)"}
{"ts": 1717100002.10, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "Initialized simulator adapter for device server_room_temp"}

The agent is alive. Every 2 seconds it collects a temperature reading. You open a second terminal to peek at the health endpoint while the first one keeps running.

Minute 3: Open the Dashboard and See Live Data

In the second terminal, you query the health endpoint.


ssh pi@192.168.1.50
curl -s http://localhost:8080/health | python3 -m json.tool

The Response


{
    "status": "healthy",
    "timestamp": 1717100010.50,
    "metrics": {
        "cpu_percent": 1.2,
        "ram_percent": 12.5,
        "disk_percent": 28.0,
        "thermal_celsius": 38.5,
        "uptime_seconds": 43200.0,
        "timestamp": 1717100010.48
    },
    "agent": {
        "running": true,
        "buffer_count": 1,
        "readings_processed": 5,
        "events_triggered": 0
    },
    "cloud": {
        "queue_depth": 5,
        "last_flush_time": 0.0,
        "messages_sent_today": 0,
        "endpoint": ""
    },
    "privacy": {
        "enabled": true,
        "rules_active": 0,
        "fields_redacted": [],
        "fields_hashed": []
    },
    "ingest": {
        "adapters_connected": ["simulator"],
        "devices_configured": 1
    }
}

Five readings already processed. The Pi is cool and quiet at 38.5 °C. You switch to your laptop, open Chrome, and navigate to the dashboard you set up earlier at http://192.168.1.50:3000. The Overview page shows a green health card, a live temperature graph climbing gently around 24 °C, and a queue depth counter ticking up by one every two seconds.

Minute 4: Add a Rule

You remember that the server room's air conditioning failed last summer, and temperatures spiked to 35 °C before anyone noticed. You want the agent to detect that immediately. While the agent is still running, you edit the config to add a rule.


# In a third terminal, edit the config
cat >> ~/pyvorin-edge/config.toml << 'EOF'

[[rules.items]]
name = "server_room_overheat"
condition_expr = "ctx.value > 30.0"
severity = "critical"
cooldown_seconds = 60.0
EOF

You know that the agent only reads config at startup, so you perform a quick restart. In the first terminal, you press Ctrl+C:


{"ts": 1717100020.00, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "EdgeAgent stopping..."}
{"ts": 1717100020.05, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "EdgeAgent stopped"}

Then start it again:


pyv-edge --config config.toml

The agent restarts cleanly. This time, the rule is loaded. You can verify it by querying health and checking that no events have fired yet — the temperature is still hovering around 24 °C, well below the 30 °C threshold.

Minute 5: Trigger an Event

You want to see the rule in action without waiting for a real air-conditioning failure. You write a tiny Python script that uses the SDK to run a simulation with an elevated baseline, forcing the temperature above 30 °C.


# /home/pi/pyvorin-edge/trigger_event.py
from pyvorin_edge.pipeline import Pipeline, RuleConfig
from pyvorin_edge.sensors import Sensor

# Build a mini pipeline with the same rule
pipeline = Pipeline(name="server_room")
pipeline.add_sensor(Sensor(name="server_room_temp", sensor_type="temperature", unit="°C"))
pipeline.add_rule(RuleConfig(
    name="server_room_overheat",
    condition_expr="ctx.value > 30.0",
    severity="critical",
    cooldown_seconds=60.0
))

# Simulate 60 seconds of readings with a high baseline
result = pipeline.run_simulation(duration_seconds=60.0, interval_seconds=2.0, seed=42)

print("Readings:", result["readings_generated"])
print("Events:", len(result["events"]))
for ev in result["events"]:
    print("  -", ev["rule_name"], "at", ev["timestamp"], "severity", ev["severity"])

You run it:


python3 ~/pyvorin-edge/trigger_event.py

The Output


Readings: 30
Events: 1
  - server_room_overheat at 1717100050.12 severity critical

The rule fired exactly once thanks to the 60-second cooldown. In the dashboard, a red notification badge appears on the Pipeline view. The Events table shows a new row: server_room_overheat, severity critical, timestamp just seconds ago. If cloud sync were enabled, this event would be enqueued with Priority.ANOMALY and flushed ahead of routine telemetry.

The Story Continues

Your five minutes are up, but your gateway is now doing real work. Here is what you have built:

A running EdgeAgent collecting simulated temperature data every 2 seconds.
A SQLite database at ~/pyvorin-edge/data/edge_store.db containing historical readings.
A health endpoint on port 8080 serving live metrics and status.
A dashboard visualising the data in real time.
An event rule that detects temperatures above 30 °C and triggers a critical alert.

What Alex Does Next

After the meeting, Alex comes back and makes three improvements:

1. Replace the Simulator with a Real Sensor

Alex edits the config to ingest from an MQTT broker that receives data from a physical DHT22 sensor:


[[sensors.devices]]
name = "server_room_temp"
ingest_type = "mqtt"
# The MQTTAdapter is initialised here; broker details are configured
# programmatically or via extended config in future versions.

2. Add a Humidity Sensor


[[sensors.devices]]
name = "server_room_humidity"
ingest_type = "simulator"
sensor_type = "humidity"
unit = "%"
min_value = 0.0
max_value = 100.0
noise_std = 1.0
baseline = 40.0

3. Enable Cloud Sync for Alerts Only

Alex enables cloud sync so critical events are forwarded to the central ops team, but adds a privacy rule to drop routine telemetry:


[cloud]
enabled = true
endpoint = "https://alerts.facilities.example.com/ingest"
api_key = "${ALERT_API_KEY}"
batch_size = 10
flush_interval_seconds = 10.0

[privacy]
enabled = true

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

Wait — that would drop everything! Alex realises the mistake and instead uses the SDK's pipeline to filter only high-severity events before they reach the queue. The exact implementation depends on the organisation's cloud schema, but the building blocks are all present in CloudSyncQueue, PrivacyPolicy, and Pipeline.

Key Takeaways

Pyvorin Edge goes from zero to live data in minutes, not hours.
The simulator lets you prototype rules and dashboards without physical sensors.
Restarting the agent is fast and safe; config changes take effect on the next start.
Rules with cooldowns prevent alert storms while still catching genuine issues.
The health endpoint and dashboard give you immediate visibility into every layer of the system.

Congratulations, Alex. Your server room is now watched by a vigilant, privacy-first, edge-native agent that costs less per year than a single month of cloud egress fees.