Modbus Device Simulator 🏭

English | 中文

---

📋 Project Introduction

A powerful Modbus device simulator designed for industrial automation testing, teaching demonstrations, and system integration testing. This project provides a complete solution including Modbus server, Web monitoring interface, and real-time data updates.

✨ Key Features

Feature	Description	Icon
🚀 High Performance	Async IO implementation, high concurrency support	⚡
🔄 Real-time	WebSocket data push, millisecond updates	🕒
📊 Visualization	Intuitive Web interface, real-time data display	📈
🔌 Multi-device	Support for 7 common industrial devices	🏭
🛠 Extensible	Modular design, easy to add new devices	🔧
🐳 Docker Support	Supports Docker deployment, one-click startup	🐳

Core Features

🚀 High Performance

• Async IO implementation
• High concurrency support
• Low latency data updates
• Optimized data processing

🔄 Real-time

• WebSocket real-time data push
• Millisecond-level updates
• Multi-client synchronization
• Reliable data transmission

📊 Visualization

• Intuitive Web interface
• Real-time data display
• Device status monitoring
• Data trend analysis

🐳 Docker Support

• One-click deployment
• Environment isolation
• Quick startup
• Easy maintenance

🚀 Quick Start

Requirements

Requirement	Description
Python	3.8+
OS	Windows/Linux/MacOS
Network	TCP/IP support
Memory	2GB+ recommended
Storage	1GB+ recommended
Docker	Optional, for containerized deployment

Installation

Method 1: Direct Run

1. Clone the repository

git clone https://github.com/prairie-spark-iot/modbus-simulator.git
cd modbus-simulator

2. Create virtual environment

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/MacOS
python -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Run the project

python -m src.main

Method 2: Docker Deployment

1. Clone the repository

git clone https://github.com/prairie-spark-iot/modbus-simulator.git
cd modbus-simulator

2. Build and start container

# Using docker-compose (recommended)
docker-compose up -d

# Or using docker commands
docker build -t modbus-simulator .
docker run -d -p 8000:8000 -p 502:502 --name modbus-simulator modbus-simulator

3. Check container status

docker-compose ps
# or
docker ps

4. View logs

docker-compose logs -f
# or
docker logs -f modbus-simulator

5. Stop service

docker-compose down
# or
docker stop modbus-simulator

Access

Service	Address	Description
🌐 Web Interface	http://localhost:8000	Device monitoring interface
📡 Modbus Server	localhost:502	Modbus communication service
📚 API Docs	http://localhost:8000/docs	API documentation

📦 Device Support

Device Type	Slave ID	Main Features	Icon
Temperature & Humidity Sensor	1	Temperature, humidity data	🌡️
Energy Meter	2	Voltage, current, power, energy	⚡
AC Controller	3	Temperature, mode, switch status	❄️
Air Quality Sensor	4	PM2.5, CO2, TVOC data	🌫️
PLC/IO Module	5	Digital/Analog I/O	🔌
Smart Light Controller	6	Brightness, color temp, switch	💡
Smart Socket	7	Power, switch status, timing	🔋

🏗 System Architecture

Tech Stack

Layer	Technology	Description
Backend	Python 3.8+	Core language
Backend	pymodbus	Modbus implementation
Backend	FastAPI	Web framework
Backend	WebSocket	Real-time communication
Backend	asyncio	Async processing
Frontend	HTML5/CSS3	Interface structure
Frontend	JavaScript	Interaction logic
Frontend	Bootstrap 5	UI framework
Frontend	Chart.js	Data visualization

System Layers

1. Modbus Server Layer

• Modbus protocol communication
• Device data management
• Read/write request handling
• Data validation

2. Data Management Layer

• Data generation and simulation
• Cache mechanism
• State management
• Data persistence

3. Web Service Layer

• RESTful API
• WebSocket service
• Static resource service
• Security authentication

4. Frontend Layer

• Real-time data display
• Device control interface
• Status monitoring
• Data visualization

📚 Development Documentation

Project Structure

modbus-simulator/
├── src/                    # Source code directory
│   ├── core/              # Core functionality modules
│   │   ├── config.py      # Configuration management
│   │   └── logger.py      # Logging management
│   ├── modbus/            # Modbus related modules
│   │   ├── modbus_cache.py        # Data caching
│   │   └── modbus_data_generator.py # Data generation
│   ├── web/               # Web related modules
│   │   ├── modbus_client.py      # Modbus client
│   │   ├── routes.py             # Route definitions
│   │   ├── tasks.py              # Background tasks
│   │   └── websocket_manager.py  # WebSocket management
│   ├── __init__.py        # Package initialization
│   └── main.py            # Main program entry
├── static/                # Static resources
│   ├── css/              # CSS style files
│   │   └── style.css     # Main style file
│   └── js/               # JavaScript files
│       └── app.js        # Main script file
├── templates/             # Template files
│   └── index.html        # Main page template
├── logs/                  # Log directory
├── docs/                  # Documentation directory
├── .editorconfig         # Editor configuration
├── .gitignore            # Git ignore file
├── .dockerignore         # Docker ignore file
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── docker-compose.yml    # Docker compose configuration
├── Dockerfile            # Docker build file
├── LICENSE               # License file
├── mypy.ini             # Type checking configuration
├── pyproject.toml       # Project configuration
├── README.md            # Project documentation (Chinese)
├── README_EN.md         # Project documentation (English)
├── requirements.txt     # Dependencies list
└── uv.lock              # Dependencies lock file

❓ FAQ

Connection Issues

Q: Cannot connect to Modbus server?

• Check if port 502 is available
• Verify firewall settings
• Check network connection

Display Issues

Q: Web interface not showing data?

• Check WebSocket connection
• Verify device ID configuration
• Check browser console

Performance Issues

Q: Data updates not timely?

• Check device update interval
• Verify WebSocket connection
• Check server load

⚠️ Notes

No.	Note	Description
1	Port	Ensure port 502 is available
2	Firewall	Check firewall settings
3	Python	Ensure correct Python environment
4	Virtual Env	Run in virtual environment
5	Logs	Check logs regularly
6	Security	Pay attention to data security

📄 License

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

👥 Contributing

We welcome contributions! Please ensure:

1. Code follows project standards
2. Add necessary tests
3. Update documentation
4. Provide clear commit messages

📞 Contact

Method	Content
Author	Your Name
Email	your.email@example.com
GitHub	prairie-spark-iot
Project	modbus-simulator

🙏 Acknowledgments

Thanks to all contributors!

---

If this project helps you, please give it a ⭐️ Star!