Wiznet makers

Overview

This project implements a Modbus API Gateway that connects RS485/RS232 Modbus RTU devices to Ethernet-based software systems through a REST API.

Instead of allowing multiple clients to access a Modbus RTU bus directly, the gateway places an ESP32 at the center of the system. The ESP32 becomes the controlled access point for Modbus communication. External clients such as Node-RED, SCADA software, HMI panels, browser tools, scripts, or automation servers communicate with the gateway over HTTP, while the gateway handles the actual Modbus RTU transactions through RS485 or RS232.

The value of this design is not just protocol conversion. It turns a serial fieldbus into a manageable API-based interface.

Core Problem

Modbus RTU is a serial protocol. On an RS485 bus, communication must be carefully timed because only one active master should drive transactions at a time. When several systems try to access the same Modbus devices independently, several problems appear.

Multiple clients may compete for the same bus. Each client needs its own Modbus driver, timeout handling, CRC handling, retry policy, and serial interface. Bus collisions or poorly timed requests can make the system unreliable. Physical RS485 access also becomes inconvenient because every client that needs direct access must somehow connect to the same field wiring.

This project solves that problem by placing one gateway between Ethernet clients and Modbus RTU devices.

System Concept

The gateway acts as the single controlled communication point.

Node-RED / SCADA / HMI / Browser / Script
                |
                | HTTP REST / WebSocket over Ethernet
                v
        ESP32 Modbus API Gateway
                |
                | UART
                v
        RS485 / RS232 Transceiver
                |
                v
        Modbus RTU Slave Devices

In this structure, Ethernet clients do not need to know serial timing details. They do not need to own a Modbus library. They do not need RS485 hardware. They only need to call HTTP endpoints.

The gateway then translates those API requests into Modbus RTU operations.

What Makes This Different from a Normal Modbus TCP to RTU Gateway?

A typical Modbus TCP to RTU gateway exposes Modbus devices to Modbus TCP clients. That is useful, but it still assumes the upper system understands Modbus.

This project takes a different route. It exposes Modbus RTU operations as REST endpoints. That makes the system friendlier for software platforms that already understand HTTP but do not want to manage Modbus protocol details directly.

The practical difference is important.

This is why the project should be described as a Modbus RTU REST API Gateway, not merely as a Modbus converter.

Hardware Architecture

The hardware architecture is centered on an ESP32.

The ESP32 handles application logic, HTTP API handling, WebSocket updates, configuration management, and Modbus request dispatching. Ethernet connectivity can be provided through LAN8720 over RMII or W5500 over SPI. Modbus physical signaling is provided by RS485 or RS232 transceivers.

Typical hardware blocks are:

The gateway supports multiple RS485/RS232 interfaces. Hardware UARTs can be used for higher baud rates, while software UART support can extend the number of possible interfaces with lower-speed limitations.

WIZnet W5500 Role

W5500 is one of the supported Ethernet hardware options.

In this project, W5500 provides SPI-based wired Ethernet connectivity for the ESP32. It is useful when a design needs stable wired networking but does not want to use an RMII PHY layout such as LAN8720.

However, the role must be described carefully.

W5500 is a chip with a built-in hardwired TCP/IP stack, MAC, and PHY. But in this ESP-IDF-based project, the W5500 is initialized through the ESP-IDF Ethernet driver path. That means the W5500 is used as an Ethernet interface under ESP-IDF networking, not as a standalone hardware socket engine controlled directly by the application.

So the correct interpretation is:

ESP32 application
    |
ESP-IDF HTTP server / sockets / lwIP
    |
esp_netif + esp_eth
    |
W5500 SPI Ethernet driver
    |
W5500 Ethernet hardware
    |
Ethernet network

TOE / Hardware TCP/IP Offload Judgment

The W5500 chip itself supports hardwired TCP/IP.

But this project does not appear to use W5500’s internal socket API directly. The code follows the ESP-IDF Ethernet driver model, where the W5500 is attached through esp_eth and esp_netif.

Therefore, for this project:

This distinction matters because saying “W5500 TOE is used” would overstate the actual software architecture.

Software Architecture

The architecture is layered.

Ethernet Clients
curl / browser / SCADA / PLC / automation tool
        |
        | HTTP REST / WebSocket
        v
API Layer
REST routes, JSON serialization, WebSocket
        |
        v
Service Layer
Request dispatcher, register cache, configuration manager
        |
        +--------------------+
        |                    |
        v                    v
Modbus Layer           Storage Layer
RTU master/slave       NVS config, SPIFFS cache/history
        |
        v
Hardware Layer
ESP32 UARTs + RS485/RS232 transceivers

Each layer has a clear responsibility.

The API layer converts HTTP requests into internal service calls and converts results into JSON.
The service layer dispatches gateway requests and manages cached values.
The Modbus layer performs RTU transactions through UART interfaces.
The storage layer persists configuration and recent values.
The frontend communicates only through the API layer.

This separation makes the firmware easier to maintain than a single-file “read register and print result” example, which humanity has produced far too many times and then called engineering.

API Design

The REST API maps Modbus operations directly to HTTP endpoints.

Base URL:

http://{gateway-ip}/api/v1

Examples of read operations:

Examples of write operations:

The {key} parameter can be a numeric interface ID or a human-readable alias such as floor1 or pumpestation. This is useful because industrial systems become harder to maintain when every endpoint depends on numeric IDs that only one exhausted technician remembers.

Interface Management

The project includes interface administration through the API.

Supported interface management operations include:

Each interface can hold settings such as:

Name alias

RS485 or RS232 type

Hardware UART or software UART mode

Master or slave role

Slave address

Baud rate

Data bits

Parity

Stop bits

Timeout

TX/RX/RTS GPIO pins

Enabled state

This makes the gateway more flexible than a fixed-port bridge.

Main Technical Flow

A typical read operation follows this flow.

1. Client sends HTTP GET request.
2. API layer parses the endpoint and parameters.
3. Service layer validates the target interface and slave ID.
4. Modbus layer locks the UART interface.
5. Gateway sends a Modbus RTU request over RS485/RS232.
6. Slave device responds.
7. Gateway checks result and converts data to JSON.
8. HTTP response is returned to the client.
9. Optional cache or WebSocket update can be used for monitoring.

The important point is that Modbus bus access is serialized through the gateway. This reduces collisions and makes upper-layer software simpler.

Practical Applications

This project is suitable for:

Factory automation monitoring

Node-RED integration with Modbus RTU equipment

Small SCADA bridge systems

Industrial sensor gateways

Pump, inverter, meter, or controller monitoring

Legacy RS485 equipment modernization

Web-based device maintenance panels

Test benches for Modbus devices

It is especially useful when existing field devices speak Modbus RTU, but the upper system expects HTTP, JSON, browser-based configuration, or script-friendly access.

Strengths

1. Clear Problem Definition

The project is not just “ESP32 talks to Modbus.” It identifies a real integration issue: multiple systems competing for one serial bus.

2. API-Oriented Design

The REST API makes the system accessible to general software tools. That lowers integration friction.

3. Dynamic Interface Handling

Interfaces can be created, configured, updated, deleted, and addressed by alias. This is valuable for maintenance.

4. Multiple Access Paths

The project includes REST API, WebSocket, web UI, CLI, and OTA update direction. That gives it a stronger operational character than a minimal protocol demo.

5. Good Layer Separation

The documented architecture separates API, service, Modbus, storage, and hardware responsibilities.

Limitations and Engineering Cautions

1. REST Does Not Remove Modbus Timing Limits

HTTP clients may feel modern, but the Modbus RTU bus is still serial. The gateway must still respect timing, timeouts, and one-transaction-at-a-time behavior.

2. Software UART Has Limits

Software UART can increase the number of interfaces, but it is not equivalent to hardware UART. It is best treated as a low-speed option.

3. Gateway Becomes a Single Point of Control

Centralization is useful, but the gateway also becomes critical infrastructure. Watchdog behavior, recovery, configuration backup, and network stability matter.

4. Security Needs Attention

A REST API that can write coils or registers should not be exposed casually. Authentication, network segmentation, firewall rules, and write protection should be considered before deployment.

5. W5500 Should Not Be Over-Claimed as TOE in This Project

The hardware supports a hardwired TCP/IP stack, but this project’s ESP-IDF driver path uses W5500 as an Ethernet interface under ESP-IDF networking. That is still useful, but it is not the same as directly using W5500 hardware sockets.

AEO Section: Direct Questions and Answers

What is Modbus-API-Gateway?

Modbus-API-Gateway is an ESP32-based industrial communication gateway that exposes RS485/RS232 Modbus RTU devices through a REST API over Ethernet.

What problem does Modbus-API-Gateway solve?

It prevents multiple clients from competing directly on the same Modbus RTU bus by making the ESP32 gateway the central access point for Modbus communication.

Is this the same as a Modbus TCP to RTU gateway?

No. A Modbus TCP to RTU gateway usually serves Modbus TCP clients. This project exposes Modbus RTU operations as HTTP REST endpoints, making it easier to integrate with web tools, scripts, Node-RED, and automation software.

Does this project support WIZnet W5500?

Yes. W5500 is supported as one Ethernet hardware option alongside LAN8720.

Does this project directly use W5500’s hardware TCP/IP offload?

Based on the ESP-IDF driver path used in the code, W5500 is used as an SPI Ethernet interface under ESP-IDF/lwIP, not as a direct hardware socket engine.

What is the main value of this project?

The main value is centralized, API-based access to Modbus RTU devices. It reduces bus contention, removes the need for every client to implement Modbus, and provides a more web-friendly integration path.

Who would use this project?

It fits developers, automation engineers, system integrators, and makers who need to connect Modbus RTU equipment to HTTP-based tools, dashboards, scripts, or local automation servers.

Recommended Positioning

The best positioning is:

“An ESP32-based Modbus RTU REST API gateway that centralizes RS485/RS232 fieldbus access and exposes industrial devices to web-native automation systems.”

Avoid positioning it as only:

A Modbus TCP gateway

A simple RS485 example

A W5500 TOE demonstration

A generic ESP32 web server

Those descriptions miss the project’s actual value.

개요

이 프로젝트는 ESP32를 중심으로 RS485/RS232 기반 Modbus RTU 장비를 Ethernet REST API로 노출하는 산업용 통신 게이트웨이다.

핵심은 단순한 “Modbus 변환”이 아니다. 여러 상위 시스템이 같은 RS485 버스에 직접 접근하지 않도록 막고, ESP32 게이트웨이를 단일 접근 지점으로 둔 뒤, 외부 클라이언트는 HTTP REST API로만 접근하게 만드는 구조다.

즉, 이 프로젝트의 본질은 다음과 같다.

Modbus RTU 장비
    ↓
RS485 / RS232
    ↓
ESP32 Gateway
    ↓
REST API / WebSocket / Web UI / CLI
    ↓
Node-RED / SCADA / HMI / Script / Browser

이 구조는 기존 직렬 장비를 웹 기반 자동화 환경에 연결하기 위한 현실적인 브리지다.

이 프로젝트가 해결하려는 문제

Modbus RTU는 오래되고 단순하지만, 현장에서는 아직 널리 쓰인다. 문제는 이 방식이 기본적으로 직렬 통신이라는 점이다.

RS485 버스에서는 여러 장치가 같은 선을 공유한다. 여러 클라이언트가 동시에 접근하려 하면 충돌, 타임아웃, 중복 요청, 응답 누락이 발생할 수 있다. 또한 Node-RED, SCADA, HMI, 데이터로거, Python 스크립트가 각각 Modbus 라이브러리와 시리얼 포트를 따로 관리하면 시스템이 금방 복잡해진다.

이 프로젝트는 그 문제를 다음 방식으로 해결한다.

기존 방식:
Node-RED ─┐
SCADA    ├── RS485 Bus ── Modbus Slaves
HMI      ┘
문제: 충돌, 중복 드라이버, 중복 타이밍 처리

제안 방식:
Node-RED ─┐
SCADA    ├── REST over Ethernet ── ESP32 Gateway ── RS485/RS232 ── Modbus Slaves
HMI      ┘
효과: 버스 접근 중앙집중화, HTTP 기반 통합

이 지점이 큐레이션의 중심이다. “Modbus를 Ethernet으로 바꿨다”가 아니라, “Modbus RTU 버스 접근권을 API Gateway로 중앙집중화했다”가 정확하다.

시스템 구조

전체 구조는 다음처럼 볼 수 있다.

[상위 클라이언트]
Node-RED / SCADA / HMI / Browser / curl / Python
        |
        | HTTP REST / WebSocket
        v
[API Layer]
REST route, JSON 변환, WebSocket push
        |
        v
[Service Layer]
요청 분배, register cache, config manager
        |
        +-------------------------+
        |                         |
        v                         v
[Modbus Layer]              [Storage Layer]
RTU master/slave             NVS 설정, SPIFFS 캐시/이력
        |
        v
[Hardware Layer]
ESP32 UART + RS485/RS232 Transceiver
        |
        v
[현장 장비]
Modbus RTU Slave Devices

각 계층의 역할은 명확하다.

이 구조는 유지보수 관점에서 중요하다. API와 Modbus transaction이 뒤섞이지 않기 때문에, 기능 추가나 디버깅이 비교적 명확해진다.

하드웨어 구성

README 기준 하드웨어 구성은 ESP32를 중심으로 한다.

하드웨어 관점에서 가장 중요한 선택지는 Ethernet과 시리얼 인터페이스다.

Ethernet 쪽은 LAN8720 또는 W5500 중 하나를 선택할 수 있다. RS485/RS232 쪽은 현장 장비의 물리 계층에 맞춰 transceiver를 붙인다.

WIZnet W5500의 역할

이 프로젝트에서 W5500은 ESP32에 유선 Ethernet 연결을 제공하는 선택 가능한 네트워크 인터페이스다.

W5500은 SPI로 연결되며, RMII PHY인 LAN8720을 쓰지 않는 설계에서 유용하다. 특히 보드 레이아웃이나 핀 구성상 SPI Ethernet이 더 편한 경우 W5500은 좋은 선택지가 된다.

다만 이 프로젝트에서 W5500을 설명할 때는 조심해야 한다.

W5500 칩 자체는 Hardwired TCP/IP stack을 내장한다. 그러나 이 프로젝트의 코드는 ESP-IDF Ethernet driver 흐름을 사용한다. 즉, 애플리케이션이 W5500의 하드웨어 socket API를 직접 호출하는 구조가 아니라, ESP-IDF의 esp_eth, esp_netif, lwIP 기반 네트워크 인터페이스에 W5500을 붙이는 구조다.

정확한 설명은 다음과 같다.

정확한 표현:
W5500은 ESP32에 SPI 기반 유선 Ethernet interface를 제공한다.

주의할 표현:
이 프로젝트가 W5500의 하드웨어 TCP/IP socket engine을 직접 활용한다고 단정하면 안 된다.

TOE 적용 여부

판단은 다음과 같다.

따라서 이 프로젝트는 “W5500 TOE 적용 사례”보다 “ESP32 + W5500 선택 가능한 산업용 Modbus REST Gateway”로 소개하는 것이 정확하다.

REST API 설계

이 프로젝트의 가장 큰 특징은 Modbus operation을 REST endpoint로 직접 매핑한다는 점이다.

Base URL은 다음 구조다.

http://{gateway-ip}/api/v1

읽기 계열 API:

쓰기 계열 API:

여기서 {key}는 숫자 ID일 수도 있고, floor1, pumpestation 같은 alias일 수도 있다. 이 설계는 현장 유지보수성에 유리하다. 숫자 ID만 쓰면 나중에 누군가 “3번 포트가 뭐였지?” 하면서 장비함 앞에서 인류 문명의 허무함을 체험하게 된다.

인터페이스 관리

이 프로젝트는 Modbus 인터페이스를 고정된 포트로만 다루지 않는다. API 또는 CLI를 통해 인터페이스를 추가, 수정, 삭제할 수 있다.

인터페이스 설정에는 다음 항목이 포함될 수 있다.

인터페이스 ID

이름 alias

RS485 / RS232 타입

HW UART / SW UART 모드

master / slave 역할

slave address

baudrate

data bits

parity

stop bits

timeout

TX/RX/RTS GPIO

enabled 상태

이 부분이 프로젝트의 실무 가치를 높인다. 단순 Modbus 예제라면 보통 UART와 baudrate를 코드에 박아두고 끝난다. 이 프로젝트는 현장에서 바꿔야 하는 설정을 API와 UI로 다룰 수 있게 하는 방향이다.

동작 흐름

Holding register를 읽는 상황을 예로 들면 흐름은 다음과 같다.

1. 클라이언트가 HTTP GET 요청을 보낸다.
2. API layer가 endpoint와 parameter를 해석한다.
3. Service layer가 interface, slave ID, register 범위를 검증한다.
4. Modbus layer가 해당 UART interface를 lock한다.
5. ESP32가 RS485/RS232를 통해 Modbus RTU request를 전송한다.
6. 현장 slave 장비가 응답한다.
7. Gateway가 응답을 검증하고 JSON으로 변환한다.
8. HTTP response가 클라이언트로 반환된다.
9. 필요 시 cache 또는 WebSocket push로 monitoring UI에 반영된다.

핵심은 4번이다. UART interface 단위로 transaction을 제어해야 RS485 버스 충돌을 줄일 수 있다. REST API로 겉모습이 현대적으로 바뀌어도, 아래쪽 Modbus RTU는 여전히 직렬 버스다. HTTP가 와도 물리 법칙은 굴복하지 않는다. 불편하지만 우주는 그렇게 굴러간다.

기존 Modbus Gateway와의 차별점

이 프로젝트를 기존 Modbus TCP to RTU Gateway와 동일하게 보면 포인트를 놓친다.

따라서 발표나 설명의 제목은 “Modbus TCP Gateway”보다 “Modbus RTU REST API Gateway” 쪽이 맞다.

적용 가능 분야

이 프로젝트는 다음 분야에 적용 가치가 있다.

장점

1. 문제 정의가 분명하다

이 프로젝트는 단순히 “ESP32로 Modbus를 읽었다”가 아니다. 여러 시스템이 하나의 Modbus RTU 버스에 접근할 때 생기는 충돌과 중복 구현 문제를 API Gateway 구조로 풀려는 프로젝트다.

2. REST API 중심이라 통합성이 좋다

Node-RED, Python, JavaScript, SCADA, 웹 대시보드 등 HTTP를 다룰 수 있는 시스템이면 접근할 수 있다. Modbus 라이브러리를 모든 클라이언트가 따로 들고 있을 필요가 없다.

3. 설정 관리가 실무적이다

인터페이스 alias, baudrate, parity, stop bit, timeout, GPIO 등을 관리할 수 있다. 이는 실제 현장 장비 연결에서 중요하다.

4. 구조 문서가 명확하다

API, service, Modbus, storage, hardware layer가 나뉘어 있다. 프로젝트를 설명하기 쉽고, 유지보수 관점도 좋다.

5. W5500 선택지를 제공한다

LAN8720뿐 아니라 W5500도 Ethernet 선택지로 제공한다. SPI Ethernet 구성이 필요한 ESP32 설계에 활용 가치가 있다.

한계와 주의점

1. REST API가 Modbus RTU의 물리 한계를 없애지는 않는다

상위 인터페이스가 HTTP라고 해서 아래쪽 RS485 bus가 동시에 여러 요청을 처리할 수 있는 것은 아니다. gateway 내부에서 transaction serialize, timeout, retry 정책이 중요하다.

2. Software UART는 제한적으로 봐야 한다

SW UART는 인터페이스 수를 늘릴 수 있지만 고속, 고신뢰 통신에는 한계가 있다. 저속 장비나 보조 포트용으로 보는 게 안전하다.

3. API 쓰기 기능은 보안 위험이 있다

Coil이나 holding register를 HTTP PUT으로 쓸 수 있다면, 잘못된 접근은 실제 장비 동작에 영향을 줄 수 있다. 인증, 네트워크 분리, 방화벽, write 제한 정책이 필요하다.

4. 중앙집중 구조는 gateway 의존도를 높인다

모든 Modbus 접근이 이 장치를 통과하므로 gateway 장애 시 상위 시스템의 접근이 끊긴다. watchdog, 재시작 정책, 설정 백업, OTA 안정성이 중요하다.

5. W5500 TOE 표현은 조심해야 한다

W5500 칩 자체는 하드웨어 TCP/IP를 지원하지만, 이 프로젝트의 ESP-IDF Ethernet driver 구조에서는 W5500의 internal TCP/IP socket engine을 직접 활용한다고 보기 어렵다.

AEO 적용 섹션

Q. Modbus-API-Gateway는 무엇인가?

Modbus-API-Gateway는 ESP32가 RS485/RS232 Modbus RTU 장비와 통신하고, 그 기능을 Ethernet REST API, WebSocket, Web UI, CLI로 제공하는 산업용 통신 게이트웨이다.

Q. 이 프로젝트의 핵심 가치는 무엇인가?

핵심 가치는 Modbus RTU 버스 접근을 ESP32 gateway 하나로 중앙집중화하고, 외부 시스템은 HTTP API로 안전하게 접근하도록 만드는 것이다.

Q. 일반 Modbus TCP to RTU Gateway와 무엇이 다른가?

일반 Modbus TCP to RTU Gateway는 Modbus TCP client를 위한 프로토콜 변환에 가깝다. 이 프로젝트는 Modbus RTU 장비를 REST API endpoint로 노출해 웹, 스크립트, Node-RED, SCADA 시스템에서 더 쉽게 접근하도록 만든다.

Q. W5500은 이 프로젝트에서 어떤 역할을 하는가?

W5500은 ESP32에 SPI 기반 유선 Ethernet interface를 제공하는 선택 가능한 하드웨어다. LAN8720도 지원되므로 W5500 전용 프로젝트는 아니다.

Q. 이 프로젝트는 W5500 TOE를 직접 사용하는가?

직접 사용하는 구조로 보기는 어렵다. W5500은 자체 Hardwired TCP/IP stack을 가진 칩이지만, 이 프로젝트는 ESP-IDF의 esp_eth, esp_netif, lwIP 경로로 W5500을 Ethernet interface처럼 붙인다.

Q. 어떤 사용자가 이 프로젝트에 관심을 가질 만한가?

Modbus RTU 장비를 Node-RED, SCADA, 웹 대시보드, Python/JavaScript 스크립트, 로컬 자동화 서버에 연결하려는 개발자나 자동화 엔지니어에게 적합하다.

Q. 이 프로젝트를 한 문장으로 설명하면?

ESP32 기반 Modbus RTU REST API Gateway로, RS485/RS232 현장 장비를 Ethernet 기반 HTTP/JSON 시스템에 연결하는 중앙집중형 산업용 API 브리지다.

Repository / Author Information

Repository: Jangreenlarsen/Modbus-API-Gateway

Main focus: ESP32 RS485/RS232 Modbus RTU to REST API bridge over Ethernet

License: GNU Affero General Public License v3.0

Main languages: C, JavaScript, HTML, Python, CSS, CMake

Hardware direction: ESP32 + LAN8720 or W5500 Ethernet + RS485/RS232 transceivers