Edge Quick Start - Pyvorin Docs

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.

This article is a complete, copy-paste-friendly walkthrough. By the end, you will have a running Pyvorin Edge Agent that simulates a temperature sensor, stores readings locally, and exposes a health endpoint you can query with curl. Every command is shown. Every expected output is shown. If something does not match, check the Troubleshooting article.

Prerequisites

Before you begin, ensure you have:

A Raspberry Pi 4 or 5 (or equivalent ARM64 gateway) powered on and connected to your network.
Python 3.12+ installed.
The Pyvorin Edge runtime installed in a virtual environment at ~/pyvorin-edge.

If you have not completed installation yet, follow the Edge Installation article first.

Step 1: Activate Your Environment

Every command in this walkthrough assumes your virtual environment is active.


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

Expected prompt change: your shell prefix should now show (.venv) or similar.

Step 2: Write a Minimal Pipeline Config

We will create a configuration file that defines one simulated temperature sensor. The simulator generates realistic readings with Gaussian noise around a baseline of 21 °C.


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

[[sensors.devices]]
name = "kitchen_temp"
ingest_type = "simulator"
sensor_type = "temperature"
unit = "°C"
min_value = -10.0
max_value = 50.0
noise_std = 0.3
baseline = 21.0

[windows]
default_size = 100
default_dtype = "float"

[rules]
evaluation_interval_seconds = 10.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

This config tells the agent to:

Poll every 5 seconds (poll_interval_seconds).
Create one simulated sensor named kitchen_temp.
Store up to 100 readings in a ring buffer per device.
Disable cloud sync.
Enable the privacy firewall with no rules (everything allowed).
Start a health HTTP server on port 8080.

Step 3: Run the Agent in Foreground Mode

Start the agent so you can watch the logs in real time.


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

Expected Output (First 30 Seconds)


{"ts": 1717001234.56, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "Health server listening on port 8080"}
{"ts": 1717001234.57, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "EdgeAgent started"}
{"ts": 1717001234.58, "level": "INFO", "logger": "pyv_edge_agent.local_store.sqlite_store", "msg": "Schema initialized (version 1)"}
{"ts": 1717001239.60, "level": "INFO", "logger": "pyv_edge_agent.main", "msg": "Initialized simulator adapter for device kitchen_temp"}

After this, the agent enters its main loop. Every 5 seconds it collects a reading, evaluates privacy rules, stores it in SQLite, and enqueues it (though cloud sync is disabled, the queue still records locally).

Step 4: Query the Health Endpoint

Open a second SSH session to your Pi (or use a local terminal if you are working directly on the Pi). Leave the first session running the agent.


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

Expected Health Response


{
    "status": "healthy",
    "timestamp": 1717001245.123,
    "metrics": {
        "cpu_percent": 2.5,
        "ram_percent": 18.4,
        "disk_percent": 34.1,
        "thermal_celsius": 42.3,
        "uptime_seconds": 86450.0,
        "timestamp": 1717001245.12
    },
    "agent": {
        "running": true,
        "buffer_count": 1,
        "readings_processed": 12,
        "events_triggered": 0
    },
    "cloud": {
        "queue_depth": 12,
        "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
    }
}

Key fields to observe:

agent.readings_processed — increases by 1 every 5 seconds.
cloud.queue_depth — increases because cloud sync is disabled and items accumulate in the local queue.
metrics.thermal_celsius — the Pi's CPU temperature. If this exceeds 80 °C, add a heatsink or fan.

Step 5: Inspect Stored Readings in SQLite

The agent stores every reading in an SQLite database. You can query it directly.


cd ~/pyvorin-edge
sqlite3 data/edge_store.db "SELECT sensor_name, timestamp, value, unit FROM readings ORDER BY timestamp DESC LIMIT 5;"

Expected SQLite Output


kitchen_temp|1717001245.12|21.34|°C
kitchen_temp|1717001240.11|20.89|°C
kitchen_temp|1717001235.10|21.15|°C
kitchen_temp|1717001230.09|21.02|°C
kitchen_temp|1717001225.08|20.76|°C

Notice the values fluctuate around the 21.0 baseline due to the Gaussian noise model in the simulator.

Step 6: Query Metrics Directly

The health server also exposes a /metrics endpoint with raw system metrics.


curl -s http://localhost:8080/metrics | python3 -m json.tool

Expected Metrics Response


{
    "cpu_percent": 3.1,
    "ram_percent": 18.6,
    "disk_percent": 34.1,
    "thermal_celsius": 42.5,
    "uptime_seconds": 86460.0,
    "timestamp": 1717001255.45
}

Step 7: Stop the Agent

In the terminal where the agent is running, press Ctrl+C.


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

The agent catches SIGINT, shuts down the health server cleanly, closes the SQLite connection pool, and exits with code 0.

Step 8: Run as a Single Iteration

For testing and cron jobs, you can run exactly one collection cycle and then exit.


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

This is useful for integration tests or for triggering data collection from external schedulers.

Step 9: Add a Second Sensor

To prove the system scales to multiple devices, add a humidity sensor to the same config.


cat >> ~/pyvorin-edge/config.toml << 'EOF'

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

Restart the agent:


pyv-edge --config config.toml

Now query health again and observe agent.buffer_count is 2 and ingest.devices_configured is 2.


curl -s http://localhost:8080/health | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['agent']['buffer_count'], d['ingest']['devices_configured'])"
# Expected: 2 2

Step 10: Run a Pipeline Programmatically

Instead of running the daemon, you can use the SDK directly in a Python script. This is useful for batch processing, simulations, or testing rules.


# ~/pyvorin-edge/demo_pipeline.py
from pyvorin_edge.pipeline import Pipeline, WindowConfig, RuleConfig
from pyvorin_edge.sensors import Sensor

# Build a pipeline
pipeline = Pipeline(name="demo_pipeline")
pipeline.add_sensor(Sensor(name="kitchen_temp", sensor_type="temperature", unit="°C"))
pipeline.add_window(WindowConfig(duration_seconds=60.0, window_type="rolling"))
pipeline.add_rule(RuleConfig(name="too_hot", condition_expr="ctx.value > 25.0"))

# Run a built-in simulation
result = pipeline.run_simulation(duration_seconds=300.0, interval_seconds=10.0, seed=42)
print("Readings generated:", result["readings_generated"])
print("Events triggered:", len(result["events"]))


cd ~/pyvorin-edge
source .venv/bin/activate
python3 demo_pipeline.py

Expected Output


Readings generated: 30
Events triggered: 2

Summary

In this walkthrough you:

Created a configuration file with one simulated temperature sensor.
Started the Pyvorin Edge Agent and watched it collect readings every 5 seconds.
Queried the /health and /metrics HTTP endpoints.
Inspected stored readings in the SQLite database.
Added a second sensor and verified multi-device support.
Ran a standalone pipeline simulation using the SDK.

Your gateway is now ingesting, storing, and serving data locally. Next, learn what is happening under the hood by reading Understanding the EdgeAgent.