A Rust client library for communicating with Victron Energy devices via Modbus TCP protocol.
This library provides a type-safe, async interface for interacting with Victron Energy devices including inverters, ESS (Energy Storage Systems), and battery monitors using the Modbus TCP protocol.
- Async/await support - Built on
tokio-modbus
for non-blocking I/O - Type-safe API - Strongly typed enums for all registers, modes, and states
- Multiple device types:
- VE.Bus Inverters (
VictronInverter
) - ESS Systems (
VictronESS
) - Battery Monitors (
VictronBattery
)
- VE.Bus Inverters (
- Comprehensive monitoring - Read voltage, current, frequency, power, SOC, alarms, and more
- Device control - Set inverter modes, ESS parameters, and power setpoints
Add this to your Cargo.toml
:
[dependencies]
victron_modbus_tcp = "0.1"
use victron_modbus_tcp::{VictronInverter, Line, Side, InverterMode};
use std::net::SocketAddr;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Connect to inverter (default unit ID is 246)
let addr: SocketAddr = "192.168.1.100:502".parse()?;
let mut inverter = VictronInverter::new(addr, 246).await?;
// Read inverter state and mode
let state = inverter.get_state().await?;
let mode = inverter.get_mode().await?;
println!("State: {}, Mode: {}", state, mode);
// Read battery state of charge
let soc = inverter.soc().await?;
println!("Battery SOC: {:.1}%", soc);
// Get AC line information
let line_info = inverter.get_line_info(Side::Input, Line::L1).await?;
println!("Input L1: {:.1}V, {:.1}A, {:.2}Hz, {:.0}W",
line_info.voltage, line_info.current,
line_info.frequency, line_info.power);
// Set inverter mode
inverter.set_mode(InverterMode::On).await?;
// Check alarms
let alarms = inverter.get_alarms().await?;
for alarm in alarms {
println!("{:?}", alarm);
}
Ok(())
}
use victron_modbus_tcp::{VictronESS, EssRegister, Line, Hub4Mode};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let addr = "192.168.1.100:502".parse()?;
let mut ess = VictronESS::new(addr, 100).await?;
// Get current ESS mode
let mode = ess.get_param(EssRegister::Mode(Hub4Mode::External)).await?;
println!("ESS Mode: {:?}", mode);
// Set power setpoint for L1 (positive = take from grid, negative = feed to grid)
ess.set_param(EssRegister::PowerSetPoint(Line::L1, 1000)).await?;
// Disable charging
ess.set_param(EssRegister::DisableCharge(true)).await?;
// Enable feed-in
ess.set_param(EssRegister::DisableFeedIn(false)).await?;
Ok(())
}
use victron_modbus_tcp::VictronBattery;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let addr = "192.168.1.100:502".parse()?;
let mut battery = VictronBattery::new(addr, 225).await?;
let capacity = battery.capacity().await?;
println!("Battery capacity: {:.1} Ah", capacity);
Ok(())
}
Supports VE.Bus inverters (com.victronenergy.vebus) with features including:
- Input/output AC measurements (voltage, current, frequency, power) for L1/L2/L3
- Battery voltage, current, and SOC monitoring
- State and mode reading/writing
- Comprehensive alarm monitoring
- Active input detection
Available modes: ChargerOnly
, InverterOnly
, On
, Off
Available states: Off
, LowPower
, Fault
, Bulk
, Absorption
, Float
, Storage
, Equalize
, Passthrough
, Inverting
, PowerAssist
, PowerSupply
, BulkProtection
Energy Storage System control with:
- Power setpoint control per phase (watts)
- Charge enable/disable
- Feed-in enable/disable
- ESS mode configuration
Available modes: WithPhaseCompensation
, WithoutPhaseCompensation
, External
Battery monitor support for reading capacity and other battery metrics.
This library uses the Victron Modbus TCP register mapping. For complete documentation, see: CCGX-Modbus-TCP-register-list
All async operations return Result<T, VictronError>
where VictronError
includes:
IO
- Standard I/O errorsModbusProtocol
- Modbus protocol errorsModbusError
- Modbus exception codes from serverGeneric
- Custom error messages
Common Victron device unit IDs:
100
- ESS/Hub-4 system225
- Battery monitor246
- VE.Bus inverter (default)
This project is licensed under the MIT License.
Contributions are welcome! Please feel free to submit a Pull Request.