voltage_modbus 0.3.1

A high-performance Modbus library for Rust with TCP and RTU support
Documentation

Voltage Modbus

License: MIT Rust GitHub Crates.io docs.rs

High-Performance Modbus TCP/RTU/ASCII Library for Rust

Author: Evan Liu evan.liu@voltageenergy.com Version: 0.2.0 License: MIT

A comprehensive, high-performance Modbus TCP/RTU/ASCII implementation in pure Rust designed for industrial automation, IoT applications, and smart grid systems.

✨ Features

  • 🚀 High Performance: Async/await support with Tokio for maximum throughput
  • 🔧 Complete Protocol Support: Modbus TCP, RTU, and ASCII protocols
  • 🛡️ Memory Safe: Pure Rust implementation with zero unsafe code
  • ⚡ Zero-Copy Operations: Optimized for minimal memory allocations
  • 🔄 Concurrent Processing: Multi-client server support
  • 📊 Built-in Monitoring: Comprehensive statistics and metrics
  • 🏭 Production Ready: Extensive testing and error handling
  • 🎯 Smart Architecture: Generic client design eliminates code duplication
  • 🧩 Modular Design: Clean separation of transport and application layers

📋 Supported Function Codes

Code Function Client Server
0x01 Read Coils ✅ ✅
0x02 Read Discrete Inputs ✅ ✅
0x03 Read Holding Registers ✅ ✅
0x04 Read Input Registers ✅ ✅
0x05 Write Single Coil ✅ ✅
0x06 Write Single Register ✅ ✅
0x0F Write Multiple Coils ✅ ✅
0x10 Write Multiple Registers ✅ ✅

🚀 Quick Start

Add this to your Cargo.toml:

[dependencies]
voltage_modbus = "0.2.0"
tokio = { version = "1.0", features = ["full"] }

Client Examples

TCP Client

use voltage_modbus::{ModbusTcpClient, ModbusClient, ModbusResult};
use std::time::Duration;

#[tokio::main]
async fn main() -> ModbusResult<()> {
    // Connect to Modbus TCP server
    let mut client = ModbusTcpClient::with_timeout("127.0.0.1:502", Duration::from_secs(5)).await?;
    
    // Read holding registers
    let values = client.read_holding_registers(1, 0, 10).await?;
    println!("Read registers: {:?}", values);
    
    // Write single register
    client.write_single_register(1, 100, 0x1234).await?;
    
    client.close().await?;
    Ok(())
}

RTU Client

use voltage_modbus::{ModbusRtuClient, ModbusClient, ModbusResult};
use std::time::Duration;

#[tokio::main] 
async fn main() -> ModbusResult<()> {
    // Connect to Modbus RTU device
    let mut client = ModbusRtuClient::with_config(
        "/dev/ttyUSB0",
        9600,
        tokio_serial::DataBits::Eight,
        tokio_serial::StopBits::One,
        tokio_serial::Parity::None,
        Duration::from_secs(1),
    )?;
    
    // Read coils
    let coils = client.read_coils(1, 0, 8).await?;
    println!("Read coils: {:?}", coils);
    
    client.close().await?;
    Ok(())
}

Server Example

use voltage_modbus::{
    ModbusTcpServer, ModbusTcpServerConfig, ModbusServer, ModbusRegisterBank
};
use std::sync::Arc;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create server configuration
    let config = ModbusTcpServerConfig {
        bind_address: "127.0.0.1:502".parse().unwrap(),
        max_connections: 50,
        request_timeout: Duration::from_secs(30),
        register_bank: Some(Arc::new(ModbusRegisterBank::new())),
    };
    
    // Start server
    let mut server = ModbusTcpServer::with_config(config)?;
    server.start().await?;
    
    // Server is now running...
    Ok(())
}

📖 Documentation

🏗️ Architecture

Protocol Layer Insight

The library implements a key architectural insight: Modbus TCP and RTU share identical application layer messages (PDU), differing only in transport encapsulation:

TCP Frame: [MBAP Header (7 bytes)] + [PDU (Function Code + Data)]
RTU Frame: [Slave ID (1 byte)] + [PDU (Function Code + Data)] + [CRC (2 bytes)]

This enables code reuse through a generic client design:

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │ ModbusTcpClient │    │ ModbusRtuClient │                │
│  └─────────────────┘    └─────────────────┘                │
│           │                       │                        │
│  ┌─────────────────────────────────────────────────────────┐│
│  │           GenericModbusClient<T>                        ││
│  │         (Shared Application Logic)                      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────────────────────────────────────────┐
│                   Transport Layer                           │
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │   TcpTransport  │    │   RtuTransport  │                │
│  │  (TCP Sockets)  │    │ (Serial Ports)  │                │
│  └─────────────────┘    └─────────────────┘                │
└─────────────────────────────────────────────────────────────┘

Core Modules

  • error - Error types and result handling
  • protocol - Modbus protocol definitions and message handling
  • transport - Network transport layer for TCP, RTU, and ASCII communication
  • client - Generic and protocol-specific client implementations
  • server - Modbus server implementations with concurrent support
  • register_bank - Thread-safe register storage for server applications
  • utils - Utility functions, data conversion, and performance monitoring

🧪 Examples and Testing

Run Examples

# Start the demo server
cargo run --bin server_demo

# Run TCP client demo
cargo run --bin demo

# Test RTU functionality
cargo run --bin rtu_test

# Run performance benchmarks
cargo run --bin performance_test

# Test all function codes
cargo run --bin full_function_test

Test Coverage

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Integration tests
cargo test --test integration_tests

# Documentation tests
cargo test --doc

Test Results:

  • ✅ 34 unit tests passed
  • ✅ 9 integration tests passed
  • ✅ 22 documentation tests passed
  • ✅ All Modbus function codes tested
  • ✅ Error handling and recovery tested
  • ✅ Concurrent client connections tested

📈 Performance

Benchmarks

Metric Value
Latency < 1ms (local)
Throughput 1000+ requests/sec
Concurrent Connections 50+ clients
Memory Usage < 10MB (baseline)
CPU Usage < 5% (idle)

Optimization Features

  • Async I/O: Non-blocking operations with Tokio
  • Zero-Copy Operations: Minimal memory allocations
  • Generic Architecture: Code reuse eliminates duplication
  • Lock-Free Operations: Where possible
  • Configurable Timeouts: Adaptive timeout management

🔧 Configuration

Advanced Client Configuration

use voltage_modbus::{ModbusTcpClient, ModbusRtuClient};
use std::time::Duration;

// TCP with custom timeout
let mut tcp_client = ModbusTcpClient::with_timeout(
    "192.168.1.100:502", 
    Duration::from_secs(10)
).await?;

// RTU with full configuration
let mut rtu_client = ModbusRtuClient::with_config(
    "/dev/ttyUSB0",
    9600,                                // Baud rate
    tokio_serial::DataBits::Eight,      // Data bits
    tokio_serial::StopBits::One,        // Stop bits  
    tokio_serial::Parity::None,         // Parity
    Duration::from_secs(1),             // Timeout
)?;

Server Configuration

use voltage_modbus::{ModbusTcpServerConfig, ModbusRegisterBank};
use std::sync::Arc;

let config = ModbusTcpServerConfig {
    bind_address: "0.0.0.0:502".parse().unwrap(),
    max_connections: 100,
    request_timeout: Duration::from_secs(30),
    register_bank: Some(Arc::new(ModbusRegisterBank::with_sizes(
        10000, // coils
        10000, // discrete_inputs  
        10000, // holding_registers
        10000, // input_registers
    ))),
};

🛠️ Development

Building from Source

git clone https://github.com/voltage-llc/voltage_modbus.git
cd voltage_modbus
cargo build --release

Development Tools

# Check code
cargo check

# Format code
cargo fmt

# Run linter
cargo clippy

# Generate documentation
cargo doc --no-deps --open

🚀 Installation

From Crates.io

cargo add voltage_modbus

From Source

git clone https://github.com/voltage-llc/voltage_modbus.git
cd voltage_modbus
cargo install --path .

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

  1. Clone the repository
  2. Install Rust (latest stable)
  3. Install dependencies: cargo build
  4. Run tests: cargo test
  5. Check formatting: cargo fmt --check
  6. Run linter: cargo clippy

📝 Changelog

See CHANGELOG.md for detailed release notes.

Recent Updates (v0.2.0)

  • ✨ Generic Client Architecture: Eliminated code duplication between TCP/RTU clients
  • 🎯 Improved API: Cleaner, more intuitive client interfaces
  • 🔧 Enhanced RTU Support: Full RTU client and server implementations
  • 📊 Better Testing: Comprehensive test coverage with 43 total tests
  • 🏗️ Architectural Refinement: Clean separation of transport and application layers

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Modbus Organization for the protocol specification
  • Tokio Team for the excellent async runtime
  • Rust Community for the amazing ecosystem

📞 Support

Built with ❤️ by Evan Liu for the Rust and Industrial Automation communities.