"Frequently Asked Questions"

Installation

What are the minimum system requirements?

A Raspberry Pi 4 (2 GB RAM) or any ARM64/AArch64 Linux board with Python 3.11+, 1 GB of free disk space, and kernel 5.10 or newer. The compiler backend requires a C++17 toolchain (g++ or clang++) for native hot-path generation.

How do I install the Edge SDK and Runtime?

pip install pyvorin-edge
python3 -c "from pyvorin_edge.pipeline import Pipeline; print(Pipeline)"
  

Can I run the Edge Agent on x86_64 for development?

Yes. Install the SDK on your workstation and use the simulator adapters. When you compile hot-paths with CompilerBridge.compile_hotpath(), the resulting .so is architecture-specific. Re-compile on the target device or use a cross-compilation environment.

The agent fails to start with "Permission denied" on port 8080.

Ports below 1024 require CAP_NET_BIND_SERVICE or root. The safest fix is to use a high port in config.toml:

[health]
port = 18080
  

How do I uninstall everything cleanly?

pip uninstall pyvorin-edge pyvorin
rm -rf /var/lib/pyvorin /var/log/pyvorin ~/.cache/pyvorin
  

Configuration

Where does the Edge Agent look for config.toml?

It defaults to ./edge_config.toml in the working directory. Override with:

python3 -m pyv_edge_agent --config /etc/pyvorin/config.toml
  

How do I add a new sensor without restarting the agent?

Edit config.toml and call agent.reload_config(). The agent re-initialises adapters and ring buffers without dropping the sync queue. See EdgeAgent.reload_config() in edge_runtime/pyv_edge_agent/main.py.

from pyv_edge_agent.main import EdgeAgent

agent = EdgeAgent(config_path="/etc/pyvorin/config.toml")
agent.start()
# ... later ...
agent.reload_config()
  

Can I use environment variables in config.toml?

Yes. The runtime expands ${VAR} syntax at load time. For example:

[cloud]
api_key = "${PYVORIN_API_KEY}"
endpoint = "https://api.pyvorin.com/v1/ingest"
  

How do I change the default rolling window size?

[windows]
default_size = 200
default_dtype = "float"
  

What is the difference between rolling and tumbling windows?

RollingWindow (defined in edge_sdk/pyvorin_edge/windows.py) overlaps with adjacent windows and is useful for trend detection. TumblingWindow partitions time into disjoint buckets and is useful for hourly or daily summaries.

Performance

How do I reduce CPU usage on a Raspberry Pi 4?

Three levers: increase poll_interval_seconds, compile rule conditions to native code with CompilerBridge.compile_hotpath(), and reduce the number of active adapters.

What is the expected latency per reading?

Interpreted rules average ~0.05 ms per reading on a Pi 4. Compiled hot-paths reduce this to ~0.005 ms. Measure your own pipeline with:

from pyvorin_edge.pipeline import Pipeline
result = pipeline.run(readings)
print(f"Avg latency: {result.latency_ms:.4f} ms")
  

My pipeline drops readings under heavy load.

Check the RingBuffer capacity in config.toml. If the buffer is full, old readings are overwritten. Increase default_size or use a dedicated buffer per sensor with a larger capacity.

How do I benchmark my pipeline?

from pyvorin_edge.pipeline import Pipeline

pipeline = Pipeline(name="benchmark")
# ... add sensors and rules ...
report = pipeline.run_simulation(duration_seconds=3600.0, interval_seconds=1.0, seed=42)
print(f"Generated {report['readings_generated']} readings")
print(f"Events: {len(report['events'])}")
  

Why does cpu_percent() return 0.0 on the first call?

SystemMetrics.cpu_percent() in edge_runtime/pyv_edge_agent/health_monitor/metrics.py computes a delta between two /proc/stat samples. The first call establishes the baseline; the second call returns the true utilisation. Use metrics.snapshot() in a loop to get continuous readings.

Privacy & Security

How do I redact a field before it leaves the device?

from pyvorin_edge.policies import PrivacyPolicy

privacy = PrivacyPolicy(
    redact_fields=["patient_id", "ssn"],
    retain_hours=72.0,
)
pipeline.add_policy(privacy)
  

What hashing algorithm does BundleSigner use?

Ed25519 for cryptographic signatures and SHA-256 for per-file integrity digests. See edge_sdk/pyvorin_edge/packaging/signer.py for the implementation.

How can I verify the audit chain has not been tampered with?

from pyv_edge_agent.privacy_firewall.audit import PrivacyAudit

audit = PrivacyAudit(db_path="edge_store.db")
assert audit.verify_chain(), "Audit chain integrity check failed!"
  

Can I disable cloud sync entirely for a GDPR-sensitive deployment?

Yes. Set enabled = false under [cloud] in config.toml and add sensitive sensors to local_only_sensors in the privacy policy. No data will leave the device.

Is SNMP v3 supported for custom adapters?

Yes. The example SNMP adapter in the telecom tower tutorial uses pysnmp, which supports SNMP v3 with UsmUserData, auth protocols (MD5, SHA), and priv protocols (DES, AES).

Cloud Sync

How does the agent behave when the cloud is unreachable?

Items are persisted in CloudSyncQueue (SQLite-backed) and retried with exponential backoff. No data is lost during outages. See edge_runtime/pyv_edge_agent/cloud_sync/queue.py.

Can I prioritise critical alerts over telemetry?

from pyv_edge_agent.cloud_sync.queue import CloudSyncQueue, Priority

queue = CloudSyncQueue(db_path="sync_queue.db")
queue.enqueue(payload, priority=Priority.CRITICAL, ttl_seconds=86400)
  

How do I flush the queue manually?

from pyv_edge_agent.cloud_sync.uploader import HTTPCloudUploader

uploader = HTTPCloudUploader(endpoint="...", api_key="...")
flushed = queue.maybe_flush(uploader=uploader)
print(f"Flushed {flushed} items")
  

What happens when the queue grows beyond disk capacity?

Items expire based on ttl_seconds. When a record's TTL is reached, it is silently skipped during dequeue. Critical events should use short TTLs (hours) and telemetry can use long TTLs (days), so that low-priority data is shed first.

Can I sync to multiple cloud endpoints?

The built-in agent supports one primary endpoint. For multi-destination sync, instantiate multiple HTTPCloudUploader objects and call maybe_flush() with each uploader in sequence.

Licensing

Do I need a licence to run the Edge Agent?

The open-source runtime is Apache-2.0 licensed. Advanced compiler backends and cloud analytics dashboards require a valid Pyvorin licence key.

Where do I enter my licence key?

Set the environment variable PYVORIN_LICENSE_KEY or add it to config.toml:

[license]
key = "${PYVORIN_LICENSE_KEY}"
  

What happens if the licence expires while the agent is running?

The agent continues to ingest, evaluate rules, and store data locally. Compiler hot-path generation and cloud analytics are disabled until the licence is renewed.

Can I transfer a licence between devices?

Yes. Deactivate the old device in the Pyvorin portal, then activate the new device within 24 hours. The licence is bound to a hardware fingerprint, not a user account.

Is there a free tier for development?

Yes. The Community tier includes the full SDK, simulator adapters, local pipeline execution, and health endpoints. Cloud egress and native compilation are limited to 1,000 events/month.

Still Stuck?

If your question is not answered above, check the Troubleshooting Installation guide, read the Understanding the Agent article, or open an issue on the Pyvorin GitHub repository with your config.toml, agent version, and the output of curl http://localhost:8080/health.