Skip to content

v0l/victron_modbus_tcp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

victron_modbus_tcp

A Rust client library for communicating with Victron Energy devices via Modbus TCP protocol.

Overview

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.

Features

  • 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)
  • Comprehensive monitoring - Read voltage, current, frequency, power, SOC, alarms, and more
  • Device control - Set inverter modes, ESS parameters, and power setpoints

Installation

Add this to your Cargo.toml:

[dependencies]
victron_modbus_tcp = "0.1"

Usage

Inverter Example

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(())
}

ESS Example

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(())
}

Battery Monitor Example

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(())
}

Device Types

VictronInverter

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

VictronESS

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

VictronBattery

Battery monitor support for reading capacity and other battery metrics.

Register Mapping

This library uses the Victron Modbus TCP register mapping. For complete documentation, see: CCGX-Modbus-TCP-register-list

Error Handling

All async operations return Result<T, VictronError> where VictronError includes:

  • IO - Standard I/O errors
  • ModbusProtocol - Modbus protocol errors
  • ModbusError - Modbus exception codes from server
  • Generic - Custom error messages

Unit IDs

Common Victron device unit IDs:

  • 100 - ESS/Hub-4 system
  • 225 - Battery monitor
  • 246 - VE.Bus inverter (default)

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

About

Victron ModbusTCP client code

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages