Crate mabi_modbus 

trap-sim-modbus

Modbus TCP/RTU simulator for the TRAP protocol simulator.

This crate provides:

• A transport-independent Modbus core and datastore context layer
• TCP and RTU transport adapters over a shared request execution service
• Profile-driven virtual device construction for simulator scenarios
• Protocol-aware fault injection, metrics, and runtime integration

Architecture

The crate is organized in layers:

┌──────────────┐    ┌────────────────────┐    ┌────────────────────┐
│ tcp / rtu    │───▶│ ModbusService      │───▶│ ServerContext      │
│ adapters     │    │ request execution  │    │ DeviceContext      │
└──────────────┘    └────────────────────┘    │ AddressSpace       │
                                               └────────────────────┘
                                                         │
                                               ┌────────────────────┐
                                               │ dense / sparse     │
                                               │ datastore backends │
                                               └────────────────────┘

Canonical construction flows through Builder, Profile, and the transport adapters. Low-level modules remain available for specialized integration, while the root exports provide the stable architecture surface.

Builder Example

use mabi_core::types::{DataType, ModbusRegisterType};
use mabi_modbus::{Builder, Config, PointProfile, Profile, UnitProfile};

let profile = Profile::new().with_unit(
    UnitProfile::new(1, "Pump-A").with_point(PointProfile::new(
        "holding_temp",
        "Holding Temperature",
        ModbusRegisterType::HoldingRegister,
        0,
        DataType::UInt16,
    )),
);

let server = Builder::new().config(Config::default()).profile(profile).build()?;
assert_eq!(server.device_ids(), vec![1]);

TCP Server Example

use mabi_modbus::{Builder, Config};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = Builder::new()
        .config(Config::default())
        .generated_profile(2, 8)
        .build()?;
    server.run().await?;
    Ok(())
}

Optional Layers

• faults is enabled by default for protocol-aware chaos and disruption hooks
• testing enables load generation and profiling helpers
• experimental-scaling enables scalability-specific benches and utilities
• performance-tests enables release-grade performance threshold suites

Custom Extensions

Compatibility-oriented HandlerRegistry support remains available, but the canonical extension surface is ExtensionRegistry, which routes custom function codes through the shared semantic core.

You can still implement custom function handlers by implementing the FunctionHandler trait:

use mabi_modbus::handler::{FunctionHandler, HandlerContext, ExceptionCode};

pub struct MyCustomHandler;

impl FunctionHandler for MyCustomHandler {
    fn function_code(&self) -> u8 { 0x42 }

    fn handle(&self, pdu: &[u8], ctx: &HandlerContext) -> Result<Vec<u8>, ExceptionCode> {
        // Custom implementation
        Ok(vec![0x42, 0x00])
    }

    fn name(&self) -> &'static str { "My Custom Handler" }
}

Re-exports

pub use context::AddressSpace;

pub use context::BroadcastPolicy;

pub use context::DenseRegisterStore;

pub use context::DeviceContext;

pub use context::ServerContext;

pub use control::BehaviorSetPort;

pub use control::FaultPresetPort;

pub use control::ModbusControlSession;

pub use control::PointCatalogPort;

pub use control::PointCatalogQuery;

pub use control::PointDescriptor;

pub use control::PointTarget;

pub use control::RegisterControlPort;

pub use control::ResponseProfilePort;

pub use control::SessionControlPort;

pub use control::SessionMetadataPort;

pub use control::SessionSnapshot;

pub use control::SessionStatus;

pub use control::TraceEntry;

pub use control::TraceOperation;

pub use control::TracePort;

pub use control::TraceStatus;

pub use core::FunctionCode;

pub use core::RequestPdu;

pub use core::ResponsePdu;

pub use core::SemanticRequest;

pub use core::SemanticResponse;

pub use config::ModbusDeviceConfig;

pub use config::ModbusServerConfig;

pub use device::ModbusDevice;

pub use error::ModbusError;

pub use error::ModbusResult;

pub use profile::DatastoreKind;

pub use profile::GeneratedProfilePreset;

pub use profile::PointProfile;

pub use profile::SimulatorProfile;

pub use profile::UnitProfile;

pub use register::RegisterStore;

pub use register::RegisterType;

pub use server::ModbusTcpServer;

pub use service::ExtensionContext;

pub use service::ExtensionHandler;

pub use service::ExtensionMetadata;

pub use service::ExtensionRegistry;

pub use service::ExtensionRequest;

pub use service::ServiceOutcome;

pub use simulator::schema_summary;

pub use simulator::ActionBindingDefinition;

pub use simulator::ActionBindingSummary;

pub use simulator::ActionDefinition;

pub use simulator::ActionTrigger;

pub use simulator::BehaviorBindingSummary;

pub use simulator::BehaviorCondition;

pub use simulator::BehaviorConditionOperator;

pub use simulator::BehaviorDefinition;

pub use simulator::BehaviorSetDefinition;

pub use simulator::BehaviorTarget;

pub use simulator::BehaviorTrigger;

pub use simulator::CompiledModbusSession;

pub use simulator::CompiledPointMetadata;

pub use simulator::CompiledTransportKind;

pub use simulator::DatastoreAddressRange;

pub use simulator::DatastoreDefinition;

pub use simulator::DatastoreInitialization;

pub use simulator::DatastorePolicySummary;

pub use simulator::DatastoreRepeatPolicy;

pub use simulator::DatastoreSelector;

pub use simulator::DatastoreTypedBlock;

pub use simulator::DeviceBundleDefinition;

pub use simulator::GeneratedPresetDefinition;

pub use simulator::MalformedResponseDefinition;

pub use simulator::ModbusConfigSummary;

pub use simulator::ModbusSchemaSummary;

pub use simulator::ModbusServiceLaunchConfig;

pub use simulator::ModbusSimulatorConfig;

pub use simulator::ModbusTransportLaunch;

pub use simulator::PartialResponseDefinition;

pub use simulator::PointActionBinding;

pub use simulator::ResponseProfileDefinition;

pub use simulator::SchemaSection;

pub use simulator::SessionControlConfig;

pub use simulator::SessionDefinition;

pub use simulator::SessionResetPolicy;

pub use simulator::SessionSummary;

pub use simulator::SessionTraceConfig;

pub use simulator::SimulatorDefaults;

pub use simulator::SplitResponseDefinition;

pub use simulator::TransportDefinition;

pub use simulator::UnitDefinition;

pub use tcp::ModbusTcpServerV2;

pub use registers::AddressRange;

pub use registers::CallbackManager;

pub use registers::CallbackPriority;

pub use registers::DefaultValue;

pub use registers::InitializationMode;

pub use registers::ReadCallback;

pub use registers::ReadCallbackFn;

pub use registers::RegisterRangeConfig;

pub use registers::RegisterStoreConfig;

pub use registers::RegisterValue;

pub use registers::SparseRegisterStore;

pub use registers::WriteCallback;

pub use registers::WriteCallbackFn;

pub use rtu::ModbusRtuServer;

pub use rtu::RtuCodec;

pub use rtu::RtuFrame;

pub use rtu::RtuServerConfig;

pub use rtu::RtuTiming;

pub use rtu::SerialConfig;

pub use rtu::VirtualSerial;

pub use rtu::VirtualSerialConfig;

pub use types::RegisterConverter;

pub use types::RegisterDataType;

pub use types::TypedValue;

pub use types::WordOrder;

pub use unit::BroadcastMode;

pub use unit::MultiUnitManager;

pub use unit::UnitConfig;

pub use unit::UnitInfo;

pub use unit::UnitManagerConfig;

pub use fault_injection::CrcCorruptionFault;

pub use fault_injection::DelayedResponseFault;

pub use fault_injection::ExceptionInjectionFault;

pub use fault_injection::ExtraDataFault;

pub use fault_injection::FaultAction;

pub use fault_injection::FaultConfig;

pub use fault_injection::FaultInjectionConfig;

pub use fault_injection::FaultPipeline;

pub use fault_injection::FaultStats;

pub use fault_injection::FaultStatsSnapshot;

pub use fault_injection::FaultTarget;

pub use fault_injection::FaultType;

pub use fault_injection::ModbusFault;

pub use fault_injection::ModbusFaultContext;

pub use fault_injection::NoResponseFault;

pub use fault_injection::PartialFrameFault;

pub use fault_injection::TransportKind;

pub use fault_injection::TruncatedResponseFault;

pub use fault_injection::WrongFunctionCodeFault;

pub use fault_injection::WrongTransactionIdFault;

pub use fault_injection::WrongUnitIdFault;

pub use fault_injection::connection_disruption::ConnectionDisruptionConfig;

pub use fault_injection::connection_disruption::ConnectionDisruptionState;

pub use fault_injection::connection_disruption::DisruptionAction;

pub use fault_injection::rtu_timing::BusCollisionConfig;

pub use fault_injection::rtu_timing::ByteJitterConfig;

pub use fault_injection::rtu_timing::CollisionMode;

pub use fault_injection::rtu_timing::GapPosition;

pub use fault_injection::rtu_timing::InterCharGapConfig;

pub use fault_injection::rtu_timing::RtuTimingFaultConfig;

pub use fault_injection::rtu_timing::TimingPlan;

pub use fault_injection::rtu_timing::TimingSegment;

pub use runtime::descriptor;

pub use runtime::driver;

Modules

config

Modbus configuration types.

context

Shared datastore and server context abstractions.

control

In-process control-plane ports for DX-oriented simulator workflows.

core

Protocol-level Modbus core types and semantic request parsing.

device

Modbus device implementation.

error

Modbus error types.

fault_injection

Modbus-specific fault injection framework.

handler

Modbus function code handlers.

profile

Profile-driven simulator configuration.

register

Modbus register storage.

registers

High-performance register storage for large-scale Modbus simulation.

rtu

Modbus RTU simulation module.

runtime

Runtime configuration management for Modbus simulator.

server

Modbus TCP server implementation.

service

Transport-independent request execution services.

simulator

Session-centric simulator configuration and DX-oriented inspection helpers.

tcp

Modbus TCP server components.

types

Data types and byte order support for Modbus register conversions.

unit

Multi-Unit Management for Modbus Simulation.

Structs

Builder

Canonical server builder.

Factory

Canonical factory helpers.

Type Aliases

Config

Canonical server configuration surface for architecture-level composition.

Device

Canonical device surface for architecture-level composition.

Error

Canonical error surface for architecture-level composition.

Profile

Canonical simulator profile surface for architecture-level composition.

Result

Canonical result surface for architecture-level composition.

Server

Canonical server surface for architecture-level composition.

Stats

Canonical stats surface for architecture-level composition.