Arvak - Personal Solar System Monitor

Arvak is a personal solar monitoring system designed specifically for my off-grid solar power setup. This tool collects, processes, and visualizes real-time data from various components of my solar system, providing insights into energy production, consumption, and system health.

Note

: This project is tailored specifically for my personal solar system configuration and is not intended for general use. The code, configuration, and hardware interfaces are customized to work with my particular setup.

Overview

Arvak continuously monitors solar chargers, inverters, and environmental sensors to provide:

• Real-time energy production and consumption metrics
• Historical data tracking and visualization
• Automated reporting to PVOutput.org
• Local MQTT publishing for home automation integration
• Health monitoring and alerting
• Rich terminal-based dashboard

System Components

My solar system includes the following components that Arvak monitors:

Energy Sources

• Morningstar Solar Chargers (Front & Rear arrays) - Modbus TCP communication
• Selectronic SP PRO Inverter - HTTP API for status monitoring

Monitoring & Integration

• Local Temperature Sensors - MQTT-based environmental monitoring
• PVOutput.org Integration - Daily energy production reporting
• Uptime Kuma - Locally hosted system uptime and component health monitoring
• Local MQTT Broker - Home automation integration

Features

Data Collection

• Solar Charger Monitoring: Real-time voltage, current, and power readings from Morningstar charge controllers
• Inverter Monitoring: AC power output, battery status, and system parameters from Selectronic inverter
• Environmental Data: Temperature monitoring via MQTT sensors
• Weather Integration: Visual Crossing API for weather correlation

Data Processing

• Virtual Charger: Aggregates data from multiple solar arrays
• Energy Calculations: Computes AC solar energy from DC inputs
• Time-based Analysis: Daily energy summaries and trends

Output & Integration

• PVOutput.org: Automated daily energy reporting
• MQTT Publishing: Real-time data for home automation systems
• Health Monitoring: Component health checks and alerting
• Local Persistence: Data caching and recovery

Visualization

• Rich Terminal Dashboard: Real-time display of system status
• Historical Tracking: Energy production and consumption trends
• Error Logging: Comprehensive error tracking and display

Project Structure

arvak/
├── src/arvak/
│ ├── main.py # Main application logic
│ ├── config.py # Configuration classes
│ ├── chargers.py # Morningstar charger communication
│ ├── inverter.py # Selectronic inverter communication
│ ├── mqtt.py # MQTT client and publishing
│ ├── pvoutput.py # PVOutput.org integration
│ ├── healthchecks.py # Uptime Kuma health monitoring integration
│ ├── display.py # Terminal dashboard
│ ├── persistence.py # Data persistence
│ └── __init__.py # Package constants and types
├── tests/ # Test suite
├── pyproject.toml # Project dependencies and metadata
├── config.json # Personal system configuration (not included in repo)
├── Containerfile # Container build definition
├── entry-point.sh # Container entry point script
├── .woodpecker/ # CI/CD pipeline configuration
└── README.md # This file

Configuration

Arvak requires a config.json file with personalized settings for:

• Hardware Addresses: IP addresses and ports for chargers and inverter
• API Keys: PVOutput.org, Visual Crossing
• Monitoring Endpoints: Uptime Kuma URLs for component health monitoring
• MQTT Settings: Local broker configuration
• Monitoring: Health check endpoints
• Persistence: Local data storage paths

Important: The configuration is specific to my hardware setup and network environment. The configuration structure is defined in src/arvak/config.py, but the actual config.json file with personal settings (API keys, IP addresses, Uptime Kuma endpoints, etc.) is not included in the repository for security reasons. Note: The healthchecks.py module is used for Uptime Kuma integration despite its name.

Installation & Usage

Prerequisites

• Python 3.12+
• UV package manager
• Access to solar system hardware components
• Appropriate network configuration

Installation

# Clone the repository
git clone <repository-url>
cd arvak
# Install dependencies
uv sync
# Create personal configuration
# Create a config.json file based on the structure in src/arvak/config.py
# Edit config.json with your specific hardware settings and API keys

Running

# Start the monitoring system (default config path is ./config.json)
uv run arvak
# Or with a custom config path
uv run arvak --config /path/to/your/config.json
# Or directly via Python
python -m arvak.main --config ./config.json

Development

This project uses modern Python development practices:

Code Quality

• Ruff: Fast Python linter and formatter
• mypy: Static type checking
• pre-commit: Git hook management
• pytest: Comprehensive test suite

Development Commands

# Run tests
uv run nox -s test
# Type checking
uv run nox -s mypy
# Linting and formatting
uv run nox -s ruff
# All checks
uv run nox

CI/CD Pipeline

Arvak uses Woodpecker CI for automated testing and container building:

• Automated Testing: Runs on every push and pull request
• Dependency Management: Uses UV for fast, reliable dependency resolution
• Container Building: Automated container image builds with Kaniko
• Multi-architecture: Supports both linux/arm64 and linux/amd64

Container Deployment

Arvak can be deployed as a container for easier management and isolation:

# Build the container
uv build
docker build -t arvak:latest .
# Run with volume mounts for config and data
docker run -d \
 --name arvak \
 -v /path/to/your/config:/config \
 -v /path/to/data:/data \
 -e CONFIG_FILE=/config/config.json \
 arvak:latest

The container expects:

• Config Volume: Mounted at /config containing your config.json
• Data Volume: Mounted at /data for persistence files
• Environment Variable: CONFIG_FILE pointing to your config file

Versioning

Arvak uses calendar versioning (YYYY.M.D) to track changes. The version is automatically derived from the current date when changes are made.

Personal Notes

This project serves several personal needs:

1. Energy Awareness: Understanding daily energy production and consumption patterns
2. System Health: Early detection of issues with solar components
3. Data Historical: Long-term tracking of solar system performance
4. Home Automation: Integration with other smart home systems
5. Learning Project: Experimentation with async Python, hardware interfaces, and data visualization

Limitations & Customization

As a personal project, Arvak has several limitations:

• Hardware Specific: Code assumes specific models of chargers and inverters
• Network Configuration: Assumes particular network topology and IP addresses
• Location Specific: Configured for Queensland, Australia timezone and location
• Personal Workflows: Integration points match my specific usage patterns

Configuration Structure

The configuration uses JSON format with the following structure (as defined in src/arvak/config.py):

{
 "persistence": {"file_path": "data", "file_name": "state.json"},
 "pvoutput": {"system_id": "YOUR_SYSTEM_ID", "api_key": "YOUR_API_KEY"},
 "mqtt": {"broker": "localhost", "port": 1883, "charger_topic": "...", ...},
 "inverter": {"ip": "192.168.x.x", "port": 80, "status_path": "/path"},
 "chargers": [{"host": "192.168.x.x", "port": 502, "name": "Front"}, ...],
 "visualcrossing": {"api_key": "YOUR_KEY", "url": "https://..."},
 "monitoring": {"base_url": "http://localhost:3001", "pv_uuid": "/api/push/...", ...}, # Uptime Kuma endpoints
 "poll_interval": 60
}

Modification for other systems would require:

1. Updating hardware communication modules for different charger/inverter models
2. Adjusting data processing logic for different system configurations
3. Creating a personalized config.json file with your specific settings
4. Potentially changing visualization outputs and integration endpoints

License

AGPL-3.0-or-later - See LICENSE file for details.

Security Note

As a personal project containing sensitive configuration (API keys, network addresses, etc.):

• The config.json file is excluded from version control
• Container deployment isolates the application from the host system
• MQTT and API communications should use secure channels where possible
• Regular updates are applied to address security vulnerabilities in dependencies

Acknowledgments

• Morningstar Corporation for their solar charge controllers and Modbus protocol documentation
• Selectronic Australia for their inverter API and support
• PVOutput.org for providing free solar energy tracking services
• Uptime Kuma for self-hosted uptime monitoring
• The Python ecosystem for excellent async and data processing libraries

Last Updated: 2026年2月15日 | Version: 2026年2月8日