modbusua

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 10 Open GitHub ↗

modbusua is a cross‑platform (Windows, Linux) gateway that bridges data between the Modbus and OPC UA

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# modbusua Gateway

## Overview

`modbusua Gateway` is a cross‑platform (Windows, Linux) I/O server that bridges data
between the Modbus protocol and OPC UA (Open Platform Communications Unified Architecture).
It is implemented in C++ as an open‑source server and can run as a console application
or a background service/daemon.

The gateway collects data from existing industrial PLCs or other Modbus devices
(industrial sensors, meters, etc.) via Modbus, processes it, and exposes it through the
widely adopted OPC UA protocol.

The project is built on two open‑source libraries:
- Modbus (client side): https://github.com/serhmarch/ModbusLib
- OPC UA (server side): https://github.com/open62541/open62541

Address Space Example:

![](https://raw.githubusercontent.com/serhmarch/modbusua/main/doc/images/modbusua_address_space.png)

## Key Features

- Modern C++ implementation (C++17 and above)
- Cross‑platform support (Windows, Linux)
- Configuration via a plain CONF/INI file
- Logging to file with rotation and to the OS system log (Windows/Linux)
- Runs as a console app or Windows service/Linux daemon
- Multithreaded architecture for performance
- Modular design for easy extensibility
- Built‑in OPC UA server with configurable address space
- Modbus TCP/RTU/ASCII support for a wide range of devices
- Connection parameters, timeouts, retries configurable via the config file
- Hot configuration reload without stopping the server
- Support for common data types (bits, integers, floating‑point)
- Scalable to many devices and tags
- Built‑in diagnostics and monitoring of server and connections
- Robust error handling and reconnection logic
- Easy integration with existing SCADA systems and other upper‑level software

## System Architecture

## Build and Run

### Build From Source

#### Requirements
- **CMake** 3.20 or newer
- **C++17** compliant compiler
- **Git** to clone the repository

#### Windows Build

```bat
git clone --recursive https://github.com/serhmarch/modbusua.git
cd modbusua
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release
```

#### Linux Build

```bash
git clone --recursive https://github.com/serhmarch/modbusua.git
cd modbusua
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release
```

### Windows Installation

#### Install using `cmake --install`

Next `cmake --install` commands are identical:

```bat
cd <build_directory> 
cmake --install .
cmake --install . --prefix "C:\Program Files\modbusua"
```

Build directory is where `cmake_install.cmake` is located.

#### As a Windows Service

```bat
:: Install as a service (requires Administrator)
modbusuas.bat -i modbusuaService

:: Uninstall the service
modbusuas.bat -u -modbusuaService
```

#### MSI Installer

Build an MSI installer using the WiX Toolset:
```bat
cd install/windows
cmake --build . --target modbusua-msi
```

### Linux Installation

#### Install using `cmake --install`

Next `cmake --install` commands are identical:

```bash
cd <build_directory> 
cmake --install .
cmake --install . --prefix /
```

Build directory is where `cmake_install.cmake` is located.

#### systemd Service

```bash
# Install as a service (requires Administrator)
modbusuas.sh -i mymodbusua

# Uninstall the service
modbusuas.sh -u -mymodbusua
```

Next example shows how to install and enable the `modbusua` service manually:
```bash
# Copy files
sudo cp modbusua /usr/bin/
sudo cp modbusua.conf /etc/modbusua/
sudo cp modbusua.service /etc/systemd/system/

# Enable the service
sudo systemctl enable modbusua
sudo systemctl start modbusua

# Check status
sudo systemctl status modbusua
```

#### DEB/RPM Packages

Build DEB/RPM packages:
```bash
# Build a DEB package
cmake --build . --target modbusua-deb

# Build an RPM package
cmake --build . --target modbusua-rpm
```

Install the generated `.deb` package:
```bash
sudo dpkg -i modbusua-0.4.0_amd64.deb
# or
sudo apt install ./modbusua-0.4.0_amd64.deb
```

Remove previously installed `modbusua` package:
```bash
sudo dpkg -r modbusua # remove package (but not conffiles)
sudo dpkg -P modbusua # remove everything (even conffiles)
# or
sudo apt remove modbusua
```

Install the generated `.rpm` package:
```bash
sudo rpm -i modbusua-0.4.0_amd64.rpm
# or
sudo dnf install ./modbusua-0.4.0_amd64.rpm
```

Remove previously installed `modbusua` package:
```bash
sudo rpm -e modbusua # remove package (but not conffiles)
sudo rpm -e --noscripts modbusua # remove everything (even conffiles)
# or
sudo dnf remove modbusua
```

Add `modbusua` to the autostart and immediately run:
```bash
sudo systemctl enable --now modbusua
```

## Configuration

Configuration is done via the `modbusua.conf` file. Main configuration objects:

### Port Object

```ini
[Port]
Type=TCP
Host=192.168.1.100
Port=502
Timeout=5000
```

### Device Object

```ini
[Device]
Port=Port1
ModbusUnit=1
```

### Logging Settings

```ini
[SYSTEM]
Log.flags="Error|Warning|Info|TraceDetails"
Log.output="system file console"
Log.default.format="[%time] %cat %src. %text"
Log.default.timeformat="%Y-%M-%D %h:%m:%s.%f"
Log.concole.format="[%time] %src. %text"
Log.console.timeformat="%h:%m:%s.%f"
Log.file.format="%time;%cat;%src;%text"
Log.file.timeformat="%h:%m:%s.%f"
Log.file.path="log.csv"
Log.file.maxcount=10
Log.file.maxsize=1MB

[PORT]
Log.flags="Error|Warning|Info|TraceDetails"
Log.output="file"
Log.file.format="%time;%cat;%src;%text"
Log.file.timeformat="%h:%m:%s.%f"
Log.file.path="logport.csv"
Log.file.maxcount=10
Log.file.maxsize=1MB

[DEVICE]
Log.flags="Error|Warning|Info|TraceDetails"
Log.output="file"
Log.file.format="%time;%cat;%src;%text"
Log.file.timeformat="%h:%m:%s.%f"
Log.file.path="logdevice.csv"
Log.file.maxcount=10
Log.file.maxsize=1MB
```

## Command‑Line Options

| Option             | Short | Parameter    | Description                                    |
|:-------------------|:------|:-------------|:-----------------------------------------------|
| `--version`       | `-v`      | `-`           | Program version                               
| `--help`          | `-h/-?`   | `-`           | Help                                          
| `--file`          | `-f`      | `<filename>`  | Specify configuration file (default `modbusua.conf`)
| `--service-name`  | `-s`      | `<name>`      | Specify service name (default `modbusua`)
| `--logdir`        |           | `<dir>`       | Specify log directory (default `log`)

## Usage Examples

### Basic Configuration

```ini
# modbusua.conf
[System]
Name=modbusua Gateway
Description=OPC UA to Modbus Gateway

[Port.MainPort]
Name=MainPort
Type=TCP
Host=192.168.1.10
Port=502
Timeout=3000

[Device.Station1]
PortName=MainPort
Name=PLC1
ModbusUnit=1

[OpcUa]
Port=4840
```

### Connecting to a Controller
```bash
# Run with a configuration file
./modbusua -f /etc/modbusua/modbusua.conf

# Check connectivity
tail -f /var/log/modbusua.log
```

## Logging and Diagnostics

### Logging Levels

| Category          | Purpose                                                                            |
|:------------------|:-----------------------------------------------------------------------------------|
| Error             | Critical failures that may cause stoppage or incorrect operation                   |
| Warning           | Non‑critical issues that do not stop the program                                   |
| Info              | General diagnostic messages                                                        |
| Trace             | Detailed diagnostic messages                                                       |
| TraceDetails      | Extra‑detailed diagnostic messages                                                 |
| CtorDtor          | Creation/destruction of key program components                                     |
| EntryExit         | Entry/exit of major functions                                                      |
| ThreadStartStop   | Start/stop of system threads                                                       |
| Connection        | Connect/disconnect events to remote objects over the network                       |
| Item              | Creation/execution of individual ItemReference variables                           |
| Message           | Creation/execution of message objects (packets)                                    |
| Protocol          | Modbus‑specific protocol messages                                                  |
| Receive           | Incoming Modbus network frames                                                     |
| Send              | Outgoing Modbus network frames                                                     |

### Monitoring

```bash
# Linux - systemd logs
journalctl -u modbusua -f

# Windows - Event Viewer
# Applications and Services Logs → modbusua

# Log file
tail -f modbusua.log | grep Error
```

## Development and Contribution

### Project Structure
```
modbusua/
├── src/                   # Source code
│   ├── core/              # Common classes: string, variant, thread, etc.
│   ├── ua/                # OPC UA server
│   ├── port/              # Modbus ports
│   └── device/            # Modbus devices
├── install/               # Installation scripts
│   ├── windows/           # WiX MSI installer
│   └── linux/             # DEB/RPM packages
├── doc/                   # Documentation
├── examples/              # Configuration examples
└── tests/                 # Unit tests
```

### Testing

```bash
# Run tests
cmake --build . --target test
ctest --output-on-failure

# Code coverage (enable tests)
cmake .. -DCMAKE_BUILD_TYPE=Debug -DCN_TESTS_ENABLED=ON
```

## License

This project is licensed under the [MIT License](LICENSE).

```
MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...
```

## Links

- Source code: https://github.com/serhmarch/modbusua
- Documentation: doc/pages/
- Issue tracking: https://github.com/serhmarch/modbusua/issues
- Modbus library: https://github.com/serhmarch/ModbusLib
- OPC UA library: https://github.com/open62541/open62541
- OPC UA standard: https://opcfoundation.org/

## Author

**serhmarch** — development and project support.

Homepage: https://github.com/serhmarch

---
modbusua Gateway — OPC UA to Modbus Gateway

modbusua

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README