voltage_modbus-0.3.0 has been yanked.

Voltage Modbus

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

API Reference - Complete API documentation
Crates.io - Package information
GitHub Repository - Source code and issues

🏗️ 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

Clone the repository
Install Rust (latest stable)
Install dependencies: cargo build
Run tests: cargo test
Check formatting: cargo fmt --check
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

Documentation: https://docs.rs/voltage_modbus
Package: https://crates.io/crates/voltage_modbus
Issues: https://github.com/voltage-llc/voltage_modbus/issues
Discussions: https://github.com/voltage-llc/voltage_modbus/discussions
Email: evan.liu@voltageenergy.com

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

voltage_modbus 0.3.0