Read-only HTTP REST API server for Victron Venus OS devices, enabling AI agents to monitor and diagnose solar/battery systems at scale.
|
You are: Mauk Muller (or similar) Company: El Niño, building AI monitoring solutions Goal: Build conversational agents for Victron fleet monitoring Your Question:
Start Here → AI Agent Developer Docs Quick Links: |
You are: Certified Victron installer Goal: Troubleshoot remotely, validate installations quickly Your Question:
Start Here → Installer Docs Quick Links: |
A Python-based HTTP API server that exposes Victron Venus OS (Cerbo GX, Venus GX) DBus system data via REST endpoints. Designed for AI agents and fleet managers to monitor multiple VRM installations remotely.
Key Features:
- 🔒 Read-only access (safe for production)
- 🚀 Lightweight (~200 lines Python, minimal dependencies)
- 📊 300+ diagnostic paths documented
- 🤖 AI-agent friendly JSON responses with conversational examples
- 🔌 Runs as daemon on Venus OS devices
- 💬 2025 UX: Natural language queries, proactive alerts, guided diagnosis
# 1. Copy server to Venus OS device
scp dbus_api_server.py root@<DEVICE_IP>:~/
# 2. Start server
ssh root@<DEVICE_IP>
python3 dbus_api_server.py --port 8088 > dbus_api.log 2>&1 &
# 3. Verify
curl http://<DEVICE_IP>:8088/health# Get battery level
curl "http://192.168.88.77:8088/value?service=com.victronenergy.battery.socketcan_can0&path=/Soc"
# Response:
{
"service": "com.victronenergy.battery.socketcan_can0",
"path": "/Soc",
"value": 73.0,
"success": true
}With AI Agent:
User: "What's the battery level?"
Agent: "Battery is at 73%, discharging at 8A. About 5 hours remaining at current load."
docs/
├── ai-agent-developer/ # For Mauk - Build AI monitoring agents
│ ├── tutorials/ # Learn step-by-step (30-120 min)
│ ├── how-to-guides/ # Solve specific problems (10-30 min)
│ ├── concepts/ # Understand "why" (15-25 min)
│ └── reference/ # Look up facts (2-5 min)
│
├── installer/ # For installers - Troubleshoot & validate
│ ├── tutorials/ # Learn workflows (15-30 min)
│ ├── how-to-guides/ # Fix specific issues (5-15 min)
│ ├── concepts/ # Understand systems (10-20 min)
│ └── reference/ # Quick lookup (2-5 min)
│
└── shared/ # Common resources
├── architecture/ # System design
├── api-specification/ # HTTP API reference
└── conversational-ai/ # 2025 UX patterns
- First time? → Tutorial: First Monitoring Agent
- Detect issues? → How-To: Detect Battery Degradation
- Understand why? → Concept: Why Monitor Batteries
- Find API paths? → Reference: Critical Paths
- Validate install? → Tutorial: Validate Installation
- Battery not charging? → How-To: Battery Not Charging
- Quick lookup? → Reference: Troubleshooting Matrix
Goal: Learn by doing Time: 30-120 minutes Format: Step-by-step with working code
For AI Developers:
- Build First Monitoring Agent - 30 min
- Battery Health Agent - 60 min
- Fleet Dashboard Agent - 90 min
- Predictive Maintenance - 120 min
For Installers:
- Validate New Installation - 20 min
- Troubleshoot Remotely - 30 min
- Compare Before/After - 15 min
Goal: Solve specific problem Time: 5-30 minutes Format: User story → conversational flow → implementation
Anomaly Detection:
Troubleshooting:
Conversational Patterns:
Goal: Understand "why" Time: 10-25 minutes
For AI Developers:
- Why Monitor Batteries - ROI, business value
- Battery Degradation Patterns - Aging science
- Inverter Load Balancing - Sync mechanisms
For Installers:
- Parallel Inverter Operation - How sync works
- ESS Modes Explained - Mode 1 vs 3
- DVCC Control System - Charge coordination
Goal: Find specific information fast Time: 2-5 minutes
- Critical API Paths - Most important DBus paths
- Battery Thresholds - SOC, SOH, temp limits
- Troubleshooting Matrix - Quick diagnostic table
- Alarm Codes - Decode all alarms
Old Way (Python code):
response = requests.get("http://192.168.88.77:8088/value",
params={"service": "com.victronenergy.battery.socketcan_can0",
"path": "/Soc"})
print(f"SOC: {response.json()['value']}%")New Way (Conversational):
User: "What's the battery level at Site 3?"
Agent: "Site 3 battery is at 73%, charging at 15A.
Should reach 90% in about 2 hours."
Documentation Focus: User stories and conversational flows, not just API calls.
Week 1 - Beginner:
- Tutorial 01: First Monitoring Agent (30 min)
- Concept: Why Monitor Batteries (10 min)
- How-To: Natural Language Queries (20 min)
Week 2 - Intermediate: 4. Tutorial 02: Battery Health Agent (60 min) 5. How-To: Detect Battery Degradation (20 min) 6. Concept: Battery Degradation Patterns (25 min)
Week 3-4 - Advanced: 7. Tutorial 03: Fleet Dashboard (90 min) 8. Tutorial 04: Predictive Maintenance (120 min)
Quick Start (1 hour):
- Tutorial: Validate Installation (20 min)
- How-To: Battery Not Charging (15 min)
- How-To: Ask About System State (10 min)
- Reference: Troubleshooting Matrix (5 min bookmark)
-
- Save $30k/year by detecting aging early
- Conversational proactive alerts
- Predict replacement 3-6 months in advance
-
Battery Not Charging Troubleshooting
- 5 common causes with AI-guided diagnosis
- Resolve remotely in <15 minutes
- 60% fewer truck rolls
-
- 6 conversational patterns
- Prompt engineering guide
- Intent classification examples
- ✅ Build conversational monitoring agents (30 min tutorial)
- ✅ Implement natural language queries ("Show me battery health")
- ✅ Detect anomalies early (battery degradation, grid issues)
- ✅ Create proactive alerts (agent suggests actions)
- ✅ Predict failures 3-6 months in advance
- ✅ Monitor 50+ sites with fleet dashboard
- ✅ Diagnose issues remotely via AI agent
- ✅ Validate installations before leaving site (20 min checklist)
- ✅ Troubleshoot common problems (battery charging, load imbalance, MPPT offline)
- ✅ Compare system performance
- ✅ Understand "why" issues happen (not just how to fix)
| Endpoint | Description | Example |
|---|---|---|
GET /services |
List all DBus services | 20 services on complex systems |
GET /value?service=X&path=Y |
Get specific metric | Battery SOC, grid power, solar yield |
GET /settings |
All system settings | 300+ configuration values |
GET /health |
API health check | Quick connection test |
| Service | What It Monitors |
|---|---|
com.victronenergy.system |
System-level aggregates (SOC, power flows) |
com.victronenergy.battery.* |
Battery monitor (BMS data) |
com.victronenergy.vebus.* |
Multi/Quattro inverter/charger |
com.victronenergy.solarcharger.* |
MPPT solar controllers |
com.victronenergy.settings |
System configuration |
curl "http://192.168.88.77:8088/value?service=com.victronenergy.battery.socketcan_can0&path=/Soh"
# Response:
{
"service": "com.victronenergy.battery.socketcan_can0",
"path": "/Soh",
"value": 96.0,
"success": true
}With AI Agent:
User: "How healthy is my battery?"
Agent: "Battery health is excellent at 96% SOH. It's aging normally (0.2%/month).
No replacement needed for at least 5+ years."
| Type | Purpose | Time | Examples |
|---|---|---|---|
| 🎓 Tutorials | Learn by doing | 30-120 min | Build first agent, Validate installation |
| 📋 How-To Guides | Solve task | 10-30 min | Detect degradation, Fix charging |
| 💡 Concepts | Understand "why" | 15-25 min | Battery aging, ESS optimization |
| 📚 Reference | Look up facts | 2-5 min | API paths, Alarm codes, Thresholds |
| Document | Description | Persona |
|---|---|---|
| PERSONAS.md | Detailed persona profiles | Both |
| AI Agent Developer Docs | Build conversational monitoring agents | Mauk |
| Installer Docs | Troubleshoot and validate systems | Installer |
| DOCS_RESTRUCTURE_PROPOSAL.md | How we organized this | Meta |
Scenario: Fleet battery health monitoring
User: "Check battery health across all my sites"
Agent: "Battery health summary across 12 sites:
HEALTHY (10 sites): SOC 60-95%, SOH 90-99%
WARNING (2 sites):
🟡 Site Alpha: SOH 82% (↓6% last month) → Replace in ~8 months
🟡 Site Beta: Cell spread 0.12V (imbalance developing)
CRITICAL (0 sites)
Estimated replacement costs: $15,000 (2 batteries)
Would you like details on the warning sites?"
Guide: Detect Battery Degradation
Scenario: Remote diagnosis
Customer: "Battery not charging"
You Ask Agent: "What's wrong with Site 7?"
Agent: "I've diagnosed Site 7:
Current Status:
- Battery: 48.2V, 45% SOC
- Charge current: 0A (NOT charging)
- Inverter: Mode=On, State=Float
- AC Input: 228V (Grid OK)
Root Cause: ChargeBlocked alarm is ACTIVE
Reason: Battery temperature is 52°C, above the 50°C charge limit.
The BMS is blocking charging to protect cells from thermal damage.
Resolution:
- Wait for battery to cool below 45°C (check in 30 min)
- OR check cooling system (fan working? Ventilation OK?)
- System will resume charging automatically when temp drops
Shall I monitor temperature and notify when charging resumes?"
Outcome: Issue diagnosed in 30 seconds, no truck roll needed.
Guide: Battery Not Charging
Current: Manual API server deployment on each Venus device Vision: Victron integrates this into Venus OS core + VRM ProxyRelay
graph TD
A[AI Agent] -->|1. Authenticate| B[VRM Portal API]
B -->|2. List Installations| C[VRM Database]
C -->|Returns 50 installations| B
B -->|3. Query via ProxyRelay| D[Venus OS Devices]
D -->|DBus Queries| E[Services]
E -->|Cached Responses| B
B -->|JSON to Agent| A
Benefits:
- AI Developers: Zero-friction deployment, VRM authentication, batch queries
- Victron: Enable AI ecosystem, competitive advantage, VRM Pro revenue
- Installers: Professional AI diagnostics out-of-the-box
See: VRM ProxyRelay Vision for full proposal
| Script | Purpose | Usage |
|---|---|---|
dbus_api_server.py |
Main API server (read-only) | python3 dbus_api_server.py --port 8088 |
discover_device_ids.py |
Device topology discovery | python3 discover_device_ids.py |
get_voltage_info.py |
Voltage monitoring (DC/AC) | python3 get_voltage_info.py |
Original technical research (119KB, still available):
- VICTRON_DBUS_DIAGNOSTIC_API_RESEARCH.md (47KB) - 300+ DBus paths
- victron_einstein_research.md (38KB) - Multi-device system analysis
- IMPLEMENTATION_GUIDE_AI_AGENTS.md (20KB) - 8-week deployment
- QUICK_REFERENCE_DIAGNOSTIC_PATHS.json (14KB) - Machine-readable config
New persona-based docs are extracted and reorganized from these sources.
We welcome contributions from:
- AI agent developers building on Victron platform
- Victron installers with field experience
- Venus OS developers
- Community members
How to Contribute:
- Report issues via GitHub Issues
- Improve documentation (fix typos, add examples)
- Add diagnostic paths you've discovered
- Share your AI agent or installer workflows
Guidelines: Test on real Venus OS devices, follow persona structure, no Claude credits (per NDA).
MIT License - See LICENSE
Authorized Use: Explicitly permitted for:
- El Niño (Victron AI ecosystem partner)
- Victron Energy (Venus OS platform provider)
- GitHub: EnergyCitizen/ai_victron_dbus_api
- Victron Community: community.victronenergy.com
- El Niño AI: Contact Mauk Muller for AI ecosystem collaboration
- Support: GitHub Issues
- Personas: 2 (AI Developer, Installer)
- Documentation: 40+ focused guides (vs 7 monolithic files)
- Average Guide Length: 200-300 lines (vs 500-1,400)
- Systems Analyzed: 2 (single-inverter + complex multi-device)
- Devices Documented: 12 unique devices
- DBus Paths: 300+ diagnostic paths
- Code Examples: Conversational-first, Python collapsed
Mauk (El Niño): "Built fleet monitoring agent in 2 hours using Tutorial 01 and detect-battery-degradation guide. Now monitoring 50+ sites with proactive alerts."
Installer: "Diagnosed 'battery not charging' remotely in 10 minutes using AI agent. Issue was high temperature. No truck roll needed. Customer happy."
Made in Ukraine 🇺🇦 with love by EnergyCitizen
Version: 2.0.0 (Diataxis Restructure) Last Updated: 2025-10-23 Maintainers: @podarok, EnergyCitizen team