A Venus OS addon that dynamically controls the inverter/charger input current limit when running on generator power, preventing generator overload through intelligent ramping, automatic rollback, and adaptive learning.

Features

Preemptive Protection: Sets 40A limit when generator warm-up is detected
Gradual Ramp: Increases from 40A to 50A over 30 minutes
Overload Detection: Monitors power fluctuations to detect generator stress
Fast Recovery: Quickly ramps back to near-overload point, then slow ramps from there
Rapid Overload Protection: Increases safety margins when overloads occur in quick succession
Output Power Correlation: Learns relationship between output loads and safe input current
Persistent Learning: Model survives reboots, continuously improves over time

How It Works

Basic Flow

Generator Starts → Warm-up (40A) → AC Connects → Ramp 40A→50A → Stable
                                                        ↓
                                                  Overload detected
                                                        ↓
                                                  Rollback to 40A
                                                        ↓
                                                  5 min cooldown
                                                        ↓
                                         FAST ramp to (overload - 4A)
                                                        ↓
                                         SLOW ramp to recovery target

Fast Recovery Algorithm

When overload is detected, instead of slowly ramping from 40A all the way back up:

Immediate rollback to 40A (safety)
5-minute cooldown to let generator stabilize
Fast ramp phase: Quickly ramp at 5 A/min to (overload_point - 4A)
Slow ramp phase: Then ramp at 0.5 A/min to the recovery target

Example: Overload at 48A

Fast ramp: 40A → 44A in ~48 seconds
Slow ramp: 44A → 46A (recovery target) in ~4 minutes

Rapid Overload Protection

If overload occurs again within 2 minutes, margins increase:

Overload	Fast Ramp Margin	Recovery Margin
1st	4A	2A
2nd (rapid)	6A	4A
3rd (rapid)	8A	6A

This prevents repeated overload cycles by being progressively more conservative.

Output Power Correlation Learning

The system learns that higher output loads allow higher input current.

Why? When external loads (AC output) are high, power flows directly through to loads. When loads are low, all input power goes to battery charging, stressing the inverter more.

Model: max_input_current = base + (slope × output_power) + zone_offset

Output Power	Zone	Offset	Example Max Input
0-2000W	LOW	-2A	44 + 1 - 2 = 43A
2000-4000W	MED	0A	44 + 3 + 0 = 47A
4000-8000W	HIGH	+4A	44 + 6 + 4 = 54A

The model learns from:

Overload events: Strong signal that limit was too high for that output level
Stable operation: Confirms current limit is safe at that output level

Model parameters persist to /data/dbus-generator-ramp/learned_model.json.

State Machine

State	Description
IDLE	Waiting for generator to start
WARMUP	Generator warming up, AC not connected, limit set to 40A
RAMPING	Gradually increasing current from 40A to target
COOLDOWN	Waiting at 40A after overload (5 minutes)
RECOVERY	Fast ramp then slow ramp back up after overload
STABLE	At target, monitoring for overload

Overload Detection

The detector uses two methods that must both agree:

Rate-of-Change Reversals: Counts rapid sign changes in power derivative
Detrended Standard Deviation: Measures oscillation amplitude after removing smooth trends

This combination:

✅ Detects: Erratic oscillations (generator overload)
❌ Ignores: Smooth load increases/decreases (normal operation)

Installation

Prerequisites

Venus OS v3.10 or later (for warm-up/cool-down support)
VE.Bus firmware 415 or later
SSH/root access to the Cerbo GX

Steps

Copy files to Venus OS:

 # From your local machine
 scp -r dbus-generator-ramp root@<cerbo-ip>:/data/

Make scripts executable:

 ssh root@<cerbo-ip>
 chmod +x /data/dbus-generator-ramp/service/run
 chmod +x /data/dbus-generator-ramp/service/log/run

Create symlink to velib_python:

 ln -s /opt/victronenergy/velib_python /data/dbus-generator-ramp/ext/velib_python

Create service symlink:

 ln -s /data/dbus-generator-ramp/service /opt/victronenergy/service/dbus-generator-ramp

The service will start automatically (managed by daemontools)

Persistence Across Firmware Updates

Add to /data/rc.local:

#!/bin/bash

# Restore generator ramp controller service link
if [ ! -L /opt/victronenergy/service/dbus-generator-ramp ]; then
    ln -s /data/dbus-generator-ramp/service /opt/victronenergy/service/dbus-generator-ramp
fi

Configuration

Edit /data/dbus-generator-ramp/config.py to adjust:

D-Bus Services

DBUS_CONFIG = {
    'vebus_service': 'com.victronenergy.vebus.ttyS4',  # Your VE.Bus service
    'generator_service': 'com.victronenergy.generator.startstop0',
}

Current Limits

RAMP_CONFIG = {
    'initial_current': 40.0,      # Starting current (A)
    'target_current': 50.0,       # Target current (A)
    'initial_ramp_rate': 0.333,   # A/min (10A over 30 min)
    'recovery_ramp_rate': 0.5,    # A/min during recovery
    'cooldown_duration': 300,     # Seconds at 40A after overload

    # Fast recovery settings
    'fast_recovery_margin': 4.0,  # Amps below overload point
    'fast_ramp_rate': 5.0,        # A/min during fast recovery
    'rapid_overload_threshold': 120,  # Seconds - rapid if within this
    'rapid_overload_extra_margin': 2.0,  # Extra margin per rapid overload
}

Output Power Learning

LEARNING_CONFIG = {
    'enabled': True,
    'power_zones': {
        'LOW': (0, 2000, -2.0),       # (min_W, max_W, offset_A)
        'MEDIUM': (2000, 4000, 0.0),
        'HIGH': (4000, 8000, 4.0),
    },
    'initial_base_current': 44.0,  # Starting base for model
    'initial_slope': 0.001,        # Amps per Watt
    'learning_rate': 0.1,          # How fast model adapts
    'min_confidence': 5,           # Data points before using model
}

Overload Detection

OVERLOAD_CONFIG = {
    'derivative_threshold': 150,   # Min power change to count (W)
    'reversal_threshold': 5,       # Reversals to trigger
    'std_dev_threshold': 250,      # Std dev threshold (W)
    'confirmation_threshold': 6,   # Confirmations needed
}

Monitoring

D-Bus Paths

The service publishes status to com.victronenergy.generatorramp:

Core Status

Path	Description
`/State`	Current state (0=Idle, 1=Warmup, 2=Ramping, 3=Cooldown, 4=Recovery, 5=Stable)
`/CurrentLimit`	Current input limit (A)
`/TargetLimit`	Target for current ramp (A)
`/RecoveryTarget`	Conservative target after overload (A)
`/OverloadCount`	Total overloads this session

Power Monitoring

Path	Description
`/Power/L1`, `/L2`, `/Total`	Input power (W)
`/OutputPower/L1`, `/L2`, `/Total`	Output power / loads (W)

Fast Recovery Status

Path	Description
`/Recovery/InFastRamp`	1 if currently in fast ramp phase
`/Recovery/FastRampTarget`	Target for fast ramp (A)
`/Recovery/RapidOverloadCount`	Count of rapid successive overloads

Learning Model Status

Path	Description
`/Learning/Confidence`	Model confidence (data points)
`/Learning/ConfidenceLevel`	LOW, MEDIUM, or HIGH
`/Learning/BaseCurrent`	Learned base current (A)
`/Learning/SuggestedLimit`	Model's suggested limit for current output (A)
`/Learning/DataPoints`	Number of stable operation data points
`/Learning/OverloadPoints`	Number of recorded overload events

View Logs

# Live log
tail -F /var/log/dbus-generator-ramp/current | tai64nlocal

# Recent log
cat /var/log/dbus-generator-ramp/current | tai64nlocal

Service Control

# Stop service
svc -d /service/dbus-generator-ramp

# Start service
svc -u /service/dbus-generator-ramp

# Restart service
svc -t /service/dbus-generator-ramp

# Check status
svstat /service/dbus-generator-ramp

Manual Testing

# Check generator state
dbus -y com.victronenergy.generator.startstop0 /State GetValue

# Check current limit
dbus -y com.victronenergy.vebus.ttyS4 /Ac/In/1/CurrentLimit GetValue

# Check input power
dbus -y com.victronenergy.vebus.ttyS4 /Ac/ActiveIn/L1/P GetValue
dbus -y com.victronenergy.vebus.ttyS4 /Ac/ActiveIn/L2/P GetValue

# Check output power (loads)
dbus -y com.victronenergy.vebus.ttyS4 /Ac/Out/L1/P GetValue
dbus -y com.victronenergy.vebus.ttyS4 /Ac/Out/L2/P GetValue

# Check learning model status
dbus -y com.victronenergy.generatorramp /Learning/SuggestedLimit GetValue
dbus -y com.victronenergy.generatorramp /Learning/Confidence GetValue

Native GUI Integration (Optional)

Add a menu item to the Cerbo's built-in GUI:

# Install GUI modifications
./install_gui.sh

# Remove GUI modifications
./install_gui.sh --remove

This adds Settings → Generator start/stop → Dynamic current ramp with:

Enable/disable toggle
Current status display
All configurable settings

Note: GUI changes are lost on firmware update. Run ./install_gui.sh again after updating.

Tuning

Overload Detection

The default thresholds may need adjustment for your specific generator:

Collect Data: Log power readings during normal operation and overload

 # Add to config.py: LOGGING_CONFIG['level'] = 'DEBUG'

Analyze Patterns:

Normal: Low std dev, few reversals
Overload: High std dev, many reversals

Adjust Thresholds:

If false positives: Increase thresholds
If missed overloads: Decrease thresholds

Learning Model

To tune the power correlation model based on your system:

Observe stable operation at different output power levels
Record what input current works at each level
Adjust LEARNING_CONFIG:

initial_base_current: Max input at 0W output
initial_slope: How much more input per Watt of output
power_zones: Offsets for different load ranges

Example tuning: If you can run 54A stable at 6kW output:

54 = base + (0.001 × 6000) + 4 (HIGH zone)
54 = base + 6 + 4
base = 44A

Troubleshooting

Service Won't Start

# Check for Python errors
python3 /data/dbus-generator-ramp/dbus-generator-ramp.py

# Check D-Bus services exist
dbus -y | grep vebus
dbus -y | grep generator

Current Limit Not Changing

# Check if adjustable
dbus -y com.victronenergy.vebus.ttyS4 /Ac/In/1/CurrentLimitIsAdjustable GetValue
# Should return 1

Generator State Not Detected

# Monitor generator state changes
watch -n 1 'dbus -y com.victronenergy.generator.startstop0 /State GetValue'

Reset Learning Model

# Delete the learned model to start fresh
rm /data/dbus-generator-ramp/learned_model.json
svc -t /service/dbus-generator-ramp

Development

Local Testing (without Venus OS)

# Build development environment
docker-compose build

# Run component tests
docker-compose run --rm dev python overload_detector.py
docker-compose run --rm dev python ramp_controller.py

# Interactive shell
docker-compose run --rm dev bash

Running Tests

python3 overload_detector.py  # Runs built-in tests
python3 ramp_controller.py    # Runs built-in tests (includes fast recovery)

File Structure

/data/dbus-generator-ramp/
├── dbus-generator-ramp.py    # Main application
├── config.py                  # Configuration
├── overload_detector.py       # Power fluctuation analysis
├── ramp_controller.py         # Current ramping + learning model
├── learned_model.json         # Persisted learning data (created at runtime)
├── service/
│   ├── run                    # daemontools run script
│   └── log/
│       └── run                # multilog script
├── ext/
│   └── velib_python/          # Symlink to Venus library
├── Dockerfile                 # Development environment
├── docker-compose.yml         # Development compose
└── README.md                  # This file

License

MIT License - See LICENSE file

Acknowledgments

Victron Energy for Venus OS and the excellent D-Bus API
The Victron Community modifications forum

README.md Unescape Escape

Generator Current Ramp Controller for Venus OS

Features

How It Works

Basic Flow

Fast Recovery Algorithm

Rapid Overload Protection

Output Power Correlation Learning

State Machine

Overload Detection

Installation

Prerequisites

Steps

Persistence Across Firmware Updates

Configuration

D-Bus Services

Current Limits

Output Power Learning

Overload Detection

Monitoring

D-Bus Paths

View Logs

Service Control

Manual Testing

Native GUI Integration (Optional)

Tuning

Overload Detection

Learning Model

Troubleshooting

Service Won't Start

Current Limit Not Changing

Generator State Not Detected

Reset Learning Model

Development

Local Testing (without Venus OS)

Running Tests

File Structure

License

Acknowledgments

README.md