<div align="center">
<img width="500px" alt="Truthound Banner" src="https://github.com/user-attachments/assets/34faf6ca-1ae7-4989-9468-1ea00eb00345" />
</div>
<h1 align="center">Mabinogion</h1>
<p align="center">
<strong>Industrial Protocol Simulator Server</strong>
</p>
<p align="center">
<em>"Spawn protocols at will"</em>
</p>
[](https://crates.io/crates/mabi-cli)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.rust-lang.org/)
[](https://crates.io/crates/mabi-cli)
---
## What is Mabinogion?
**Mabinogion** is an industrial protocol simulator server written in Rust. It creates virtual devices that speak real industrial protocols, allowing you to develop and test client software without physical hardware.
### Why Use It?
- **No Hardware Required**: Simulate PLCs, sensors, and building automation systems
- **Realistic Testing**: Virtual devices respond exactly like real equipment
- **Scale Testing**: Spawn 10,000+ devices to stress test your client
- **Chaos Engineering**: Inject network delays, packet loss, and device failures
### The Name
**Mabinogion** comes from Welsh mythology — ancient tales of magical forges where legendary weapons were crafted.
Your protocol clients are forged here too.
> *And yes, I spent way too many hours playing [Mabinogi](https://mabinogi.nexon.com/page/main/index.asp) back in the day.*
---
## Quick Example
```bash
# Start a Modbus server with 10 virtual devices
mabi modbus --port 5020 --devices 10
# Connect with any Modbus client
mbpoll -a 1 -r 1 -c 10 -p 5020 127.0.0.1
```
---
## Installation
### For Simulator Users (Recommended)
```bash
cargo install mabi-cli
```
All protocols, scenario engine, and chaos engineering built-in.
### For Library Developers (Optional)
```toml
[dependencies]
mabi-core = "1.0" # Core abstractions (required)
mabi-modbus = "1.0" # Modbus TCP/RTU (optional)
mabi-opcua = "1.0" # OPC UA (optional)
mabi-bacnet = "1.0" # BACnet/IP (optional)
mabi-knx = "1.0" # KNXnet/IP (optional)
mabi-scenario = "1.0" # Scenario engine (optional)
mabi-chaos = "1.0" # Chaos engineering (optional)
```
---
## Quick Start
```bash
mabi modbus --port 502 --devices 10 --points 100
mabi opcua --port 4840 --nodes 1000
mabi bacnet --port 47808 --instance 1234
mabi knx --port 3671 --address 1.1.1
mabi run scenario.yaml --time-scale 2.0 --duration 10m
```
---
## Documentation
All detailed documentation lives in the [`docs/`](../../docs/) directory. Each module has a comprehensive guide covering architecture, API reference, configuration, and usage examples.
### Protocol Simulators
| **Modbus TCP/RTU** | Factory automation, PLCs, sensors | TCP/RTU dual mode, handler registry, sparse registers, multi-unit, fault injection | [docs/modbus-simulator](../../docs/modbus-simulator/README.md) |
| **OPC UA** | Industrial IoT, SCADA systems | Address space, subscriptions, historical access, 22+ aggregates, security policies | [docs/opcua-simulator](../../docs/opcua-simulator/README.md) |
| **BACnet/IP** | Building automation (HVAC, lighting) | 9 object types, COV subscriptions, priority array, BBMD, APDU segmentation | [docs/bacnet-simulator](../../docs/bacnet-simulator/README.md) |
| **KNXnet/IP** | Smart home/building systems | Tunneling, 25+ datapoint types, group addressing, DPT codec system | [docs/knx-simulator](../../docs/knx-simulator/README.md) |
### Core & Infrastructure
| **Core** | Common abstractions and utilities | Device trait, SimulatorEngine, factory system, metrics, capabilities, lifecycle | [docs/core](../../docs/core/README.md) |
| **Scenario Engine** | Declarative time-based simulation | 9 pattern types, event triggers/actions, time scaling, YAML schema, replay | [docs/scenario-engine](../../docs/scenario-engine/README.md) |
| **Chaos Engine** | Fault injection framework | Network/device/protocol faults, latency models, scheduler, middleware, config | [docs/chaos-engine](../../docs/chaos-engine/README.md) |
| **CLI** | Command-line interface | All commands, global options, output formats, exit codes, validation | [docs/cli](../../docs/cli/README.md) |
### API Reference
| [mabi-core](https://crates.io/crates/mabi-core) | [](https://crates.io/crates/mabi-core) | [docs.rs](https://docs.rs/mabi-core) |
| [mabi-modbus](https://crates.io/crates/mabi-modbus) | [](https://crates.io/crates/mabi-modbus) | [docs.rs](https://docs.rs/mabi-modbus) |
| [mabi-opcua](https://crates.io/crates/mabi-opcua) | [](https://crates.io/crates/mabi-opcua) | [docs.rs](https://docs.rs/mabi-opcua) |
| [mabi-bacnet](https://crates.io/crates/mabi-bacnet) | [](https://crates.io/crates/mabi-bacnet) | [docs.rs](https://docs.rs/mabi-bacnet) |
| [mabi-knx](https://crates.io/crates/mabi-knx) | [](https://crates.io/crates/mabi-knx) | [docs.rs](https://docs.rs/mabi-knx) |
| [mabi-scenario](https://crates.io/crates/mabi-scenario) | [](https://crates.io/crates/mabi-scenario) | [docs.rs](https://docs.rs/mabi-scenario) |
| [mabi-chaos](https://crates.io/crates/mabi-chaos) | [](https://crates.io/crates/mabi-chaos) | [docs.rs](https://docs.rs/mabi-chaos) |
| [mabi-cli](https://crates.io/crates/mabi-cli) | [](https://crates.io/crates/mabi-cli) | [docs.rs](https://docs.rs/mabi-cli) |
---
## Performance Targets
| Concurrent Devices | 10,000+ |
| Data Points | 1,000,000+ |
| Message Throughput | 100,000 msg/s |
| Memory (10K devices) | < 2GB |
| Latency (p99) | < 10ms |
---
## Project Structure
```
mabinogion/
├── crates/
│ ├── mabi-core/ # Core abstractions and utilities
│ ├── mabi-modbus/ # Modbus TCP/RTU simulator
│ ├── mabi-opcua/ # OPC UA server simulator
│ ├── mabi-bacnet/ # BACnet/IP simulator
│ ├── mabi-knx/ # KNXnet/IP simulator
│ ├── mabi-scenario/ # Scenario engine
│ ├── mabi-chaos/ # Chaos engineering
│ └── mabi-cli/ # CLI (mabi)
├── docs/ # Detailed documentation
├── scenarios/ # Scenario files
└── tests/ # Integration/E2E tests
```
---
## Development
```bash
cargo build --workspace # Build
cargo test --workspace # Full test suite
cargo test --test integration_tests # Integration tests
cargo test --test e2e_protocol_tests # E2E tests
cargo bench # Benchmarks
```
**Requirements**: Rust 1.75+, Tokio async runtime
---
## License
Licensed under the Apache License, Version 2.0.
---
<p align="center">
<sub>
<em>"Your protocols are forged in the crucible of mythology"</em>
</sub>
</p>