Chapter 179: Modbus TCP/IP Implementation

Chapter Objectives

By the end of this chapter, you will be able to:

• Understand the fundamental principles of the Modbus TCP/IP protocol.
• Differentiate Modbus TCP/IP from its serial counterpart, Modbus RTU.
• Identify the key components and structure of a Modbus TCP/IP message.
• Describe the roles of clients (masters) and servers (slaves) in Modbus TCP/IP communication.
• Understand the conceptual integration of Modbus TCP/IP with the ESP-IDF framework.
• Recognize considerations for implementing Modbus TCP/IP on various ESP32 variants.
• Identify common issues and troubleshooting approaches for Modbus TCP/IP implementations.

Introduction

Modbus, originally developed by Modicon (now Schneider Electric) in 1979, is one of the most widely adopted industrial communication protocols. Its simplicity, openness, and robustness have made it a de facto standard for connecting industrial electronic devices. While initially designed for serial communication (Modbus RTU/ASCII), the evolution of industrial networks towards Ethernet and TCP/IP has led to the development of Modbus TCP/IP. This variant allows Modbus messages to be transmitted over modern TCP/IP networks, leveraging the speed, scalability, and existing infrastructure of Ethernet.

The ESP32 family of microcontrollers, with their built-in Wi-Fi and Ethernet capabilities (on select variants or with external PHYs), are well-suited for implementing Modbus TCP/IP solutions. This makes them ideal for applications such as industrial control, building automation, sensor data acquisition, and bridging legacy Modbus RTU networks to Ethernet. This chapter will explore the theoretical aspects of Modbus TCP/IP and its application within the ESP-IDF ecosystem.

Theory

Modbus Protocol Overview (A Quick Recap)

Before diving into Modbus TCP/IP, let’s briefly revisit the core concepts of the Modbus protocol, which were covered in detail in Chapters 176-178 for Modbus RTU.

• Client-Server (Master-Slave) Architecture: Modbus operates on a master-slave (or client-server in modern terminology) principle. A client initiates a transaction by sending a request to a server, which then processes the request and sends a response.
• Data Model: Modbus defines a simple data model consisting of four primary tables or register types:
  • Coils (Discrete Outputs): Single-bit read/write data items (e.g., turning a relay on/off).
  • Discrete Inputs: Single-bit read-only data items (e.g., status of a digital input).
  • Input Registers: 16-bit read-only data items (e.g., sensor readings from an analog input).
  • Holding Registers: 16-bit read/write data items (e.g., configuration setpoints).
• Function Codes: Clients use function codes to tell the server what action to perform (e.g., read holding registers, write single coil).

Modbus TCP/IP vs. Modbus RTU

Modbus TCP/IP (also known as Modbus TCP) adapts the Modbus protocol for TCP/IP networks. While the fundamental Modbus application layer (the PDU – Protocol Data Unit) remains largely the same, there are significant differences in how messages are framed and transported:

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
flowchart LR
    subgraph RTU ["Modbus RTU Frame (Serial)"]
    direction LR
        A["Slave ID<br/>(1 byte)"]
        B["Function Code<br/>(1 byte)"]
        C["Data<br/>(N bytes)"]
        D["CRC<br/>(2 bytes)"]
        A --> B --> C --> D
        
        subgraph PDU1 ["PDU (Protocol Data Unit)"]
            B
            C
        end
    end

    subgraph TCP ["Modbus TCP/IP Packet (Ethernet)"]
    direction LR
        E["Ethernet<br/>Header"]
        F["IP<br/>Header"]
        G["TCP<br/>Header"]
        H["Transaction ID<br/>(2 bytes)"]
        I["Protocol ID<br/>(2 bytes)"]
        J["Length<br/>(2 bytes)"]
        K["Unit ID<br/>(1 byte)"]
        L["Function Code<br/>(1 byte)"]
        M["Data<br/>(N bytes)"]
        N["Ethernet<br/>Trailer"]
        E --> F --> G --> H --> I --> J --> K --> L --> M --> N

        subgraph MBAP ["MBAP Header (7 bytes)"]
            H
            I
            J
            K
        end
        
        subgraph PDU2 ["PDU (Protocol Data Unit)"]
            L
            M
        end
    end

    %% Styling
    classDef slaveId fill:#DBEAFE,stroke:#2563EB
    classDef function fill:#FEF3C7,stroke:#D97706
    classDef data fill:#FEF3C7,stroke:#D97706
    classDef crc fill:#FEE2E2,stroke:#DC2626
    classDef network fill:#D1FAE5,stroke:#059669
    classDef mbap fill:#EDE9FE,stroke:#5B21B6

    class A slaveId
    class B,C,L,M function
    class D crc
    class E,F,G,N network
    class H,I,J,K mbap

Modbus TCP/IP Frame Structure: The MBAP Header

Modbus TCP/IP messages are encapsulated within a TCP packet. Instead of the Slave ID and CRC found in Modbus RTU, Modbus TCP/IP uses a special header called the Modbus Application Protocol (MBAP) header. This header is 7 bytes long and precedes the Modbus PDU.

The MBAP Header consists of:

1. Transaction Identifier (TI) – 2 bytes:
   • This field is initiated by the client and echoed by the server.
   • It allows the client to match responses with requests, which is crucial in networks where multiple transactions can be active concurrently or when requests might be routed through gateways.
   • The client is responsible for managing these IDs.
2. Protocol Identifier (PI) – 2 bytes:
   • This field is always 0x0000 for Modbus services.
   • It was originally intended for future extensions or other protocols, but for Modbus, it’s fixed.
3. Length Field – 2 bytes:
   • This field specifies the number of bytes that follow it, including the Unit Identifier and the PDU (Function Code + Data).
   • Length = 1 (Unit ID) + Length of PDU.
4. Unit Identifier (UID) – 1 byte:
   • This field is used for routing messages through gateways to Modbus serial slave devices. If a Modbus TCP/IP server is directly connected to the Ethernet network (not a gateway), this field is typically echoed by the server from the client’s request. It can also be used to identify different logical devices within a single Modbus TCP server.
   • In a direct TCP connection to an end device, if the device doesn’t have internal routing to serial sub-networks, the Unit ID might be fixed (e.g., 0xFF or 0x01) or ignored. However, it’s good practice for clients to set it and servers to check it if relevant.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
graph LR
    subgraph "MBAP Header (7 Bytes Total)"
        direction LR
        A("<b>Transaction Identifier</b><br><i>2 Bytes</i><br>Matches request to response")
        B("<b>Protocol Identifier</b><br><i>2 Bytes</i><br>Always 0x0000 for Modbus")
        C("<b>Length</b><br><i>2 Bytes</i><br>Size of UID + PDU")
        D("<b>Unit Identifier</b><br><i>1 Byte</i><br>For routing through gateways")
    end

    subgraph "PDU (Follows MBAP)"
        direction LR
        PDU[("<b>Protocol Data Unit</b><br><i>(Function Code + Data)</i>")]
    end
    
    A --> B --> C --> D --> PDU

    style A fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6
    style B fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF
    style C fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF
    style D fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E
    style PDU fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46

Example Modbus TCP/IP Frame:

[Ethernet Header | IP Header | TCP Header | MBAP Header | Modbus PDU | Ethernet Trailer]

Protocol Data Unit (PDU)

The PDU is the core of the Modbus message and is identical in structure to the PDU used in Modbus RTU/ASCII. It consists of:

1. Function Code (FC) – 1 byte: Specifies the action to be performed (e.g., 0x03 for Read Holding Registers).
2. Data – N bytes: Contains the actual data or parameters for the function code (e.g., starting register address, number of registers, data values to write). The content and length of this field depend on the function code.

Since TCP provides reliable, connection-oriented communication with its own error checking (checksums) and flow control, the CRC field used in Modbus RTU is not needed and is omitted in Modbus TCP/IP.

Common Modbus Function Codes

The most commonly used Modbus function codes include:

• Read Coils (0x01): Reads the ON/OFF status of discrete outputs (coils).
• Read Discrete Inputs (0x02): Reads the ON/OFF status of discrete inputs.
• Read Holding Registers (0x03): Reads the content of read/write registers.
• Read Input Registers (0x04): Reads the content of read-only input registers.
• Write Single Coil (0x05): Writes a single ON/OFF state to a coil.
• Write Single Register (0x06): Writes a value to a single holding register.
• Write Multiple Coils (0x0F): Writes multiple ON/OFF states to a sequence of coils.
• Write Multiple Registers (0x10): Writes values to multiple holding registers.
• Exception Responses: If a server encounters an error (e.g., illegal data address, illegal function code), it returns an exception response. This is formed by setting the most significant bit of the original function code and adding an exception code byte.

Client (Master) and Server (Slave) Roles in Modbus TCP/IP

• Modbus TCP/IP Server (Slave):
  • A Modbus TCP server listens for incoming connections on a specific TCP port. The standard port for Modbus TCP/IP is port 502.
  • Once a client connects, the server waits for Modbus requests.
  • Upon receiving a valid request (matching Unit ID, valid function code, etc.), the server processes it (e.g., reads its internal data registers or writes to them) and sends a Modbus response back to the client over the same TCP connection.
  • A server can typically handle multiple client connections simultaneously, though the exact number depends on the server’s resources and implementation.
• Modbus TCP/IP Client (Master):
  • A Modbus TCP client initiates communication by establishing a TCP connection to a server’s IP address and port 502.
  • Once connected, the client sends Modbus request messages (MBAP Header + PDU) to the server.
  • The client then waits for the server’s response. It uses the Transaction Identifier in the MBAP header to match responses to its requests.
  • The client is responsible for handling timeouts and retries if a server does not respond.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
sequenceDiagram
    actor Client as Modbus TCP Client
    participant Server as ESP32 (Modbus TCP Server)

    Client->>Server: 1. Establish TCP Connection (to IP_ADDR:502)
    activate Server
    Server-->>Client: 2. Acknowledge Connection
    
    Client->>Server: 3. Send Request<br>MBAP: {TI: 101, UID: 1}<br>PDU:{FC: 3, Addr: 40, Len: 2}
    
    Server->>Server: 4. Process Request<br>- Parse MBAP & PDU<br>- Access internal data table<br>- Prepare response
    
    Server-->>Client: 5. Send Response<br>MBAP: {TI: 101, UID: 1}<br>PDU: {FC: 3, Bytes: 4, Data: ...}

    Note over Client,Server: Further requests can be sent over the same connection.

    Client->>Server: 6. Close TCP Connection
    deactivate Server

ESP-IDF Modbus TCP/IP Support

The Espressif IoT Development Framework (ESP-IDF) provides support for Modbus communication through its freemodbus component. This component is based on the popular FreeMODBUS library and has been adapted for the ESP32’s FreeRTOS environment and LwIP TCP/IP stack.

Key features related to Modbus TCP/IP in ESP-IDF (v5.x):

• TCP Slave (Server) Mode: Allows an ESP32 device to act as a Modbus TCP server, responding to requests from Modbus TCP clients.
• TCP Master (Client) Mode: Allows an ESP32 device to act as a Modbus TCP client, initiating requests to Modbus TCP servers.
• Integration with LwIP: The Modbus TCP functionality leverages the LwIP TCP/IP stack, which manages the underlying network communication (Ethernet or Wi-Fi).
• Configuration: Developers can configure Modbus parameters, such as the data tables (coils, registers), through API calls and Kconfig options.
• Callback System: The library uses callbacks to notify the application layer about Modbus events, such as when a register needs to be read or written. This allows the application to map Modbus register addresses to actual device data or variables.

To implement Modbus TCP/IP on an ESP32, you would typically:

1. Initialize the underlying network interface (Ethernet or Wi-Fi).
2. Ensure the ESP32 has a valid IP address.
3. Initialize the Modbus controller (client or server) using the ESP-IDF Modbus API.
4. Define and register callback functions to handle data access for the different Modbus register types.
5. Start the Modbus communication task.

Tip: When configuring a Modbus TCP/IP server, ensure that no other service is using TCP port 502 on the ESP32.

Variant Notes

The implementation and performance of Modbus TCP/IP can vary slightly depending on the specific ESP32 variant used:

• Ethernet Requirement:
  • ESP32 (Original): Requires an external Ethernet PHY (e.g., LAN8720, TLK110) connected via RMII or MII to its Ethernet MAC peripheral for wired Modbus TCP/IP.
  • ESP32-S3: Some ESP32-S3 SoCs and modules integrate an Ethernet MAC. Like the original ESP32, they require an external PHY for wired Ethernet.
  • Other ESP32 Variants (ESP32-S2, ESP32-C3, ESP32-C6, ESP32-H2): These variants do not have a built-in Ethernet MAC. To use wired Ethernet, an external SPI-to-Ethernet controller (e.g., W5500, ENC28J60) would be necessary. The ESP-IDF provides drivers for some common SPI Ethernet modules.
• Wi-Fi as a Transport:
  • All ESP32 variants (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2) have Wi-Fi capabilities. Modbus TCP/IP can be implemented over Wi-Fi. The Modbus protocol itself is transport-agnostic as long as TCP/IP is provided. The choice between Ethernet and Wi-Fi depends on the application’s requirements for reliability, range, and infrastructure.
• Performance and Resources:
  • Dual-Core Variants (ESP32, ESP32-S3): Offer more processing power, which can be beneficial if the ESP32 needs to handle multiple concurrent Modbus TCP/IP connections, manage large Modbus data tables, or perform other complex tasks simultaneously (e.g., running a web server, processing sensor data).
  • Single-Core Variants (ESP32-S2, ESP32-C3, ESP32-C6, ESP32-H2): While capable of running Modbus TCP/IP, resource management (CPU time, RAM) becomes more critical, especially if the application is complex.
  • RAM: The LwIP TCP/IP stack and the Modbus library consume RAM. Ensure your chosen variant has sufficient RAM for your application’s needs, including the Modbus data tables. ESP32-S2, ESP32-S3, and some other variants can have external PSRAM, which can alleviate RAM constraints for application data, though core networking buffers usually reside in internal RAM.
• ESP32-H2: This variant is primarily designed for IEEE 802.15.4 based protocols like Thread and Zigbee, along with Bluetooth LE. While it can run Wi-Fi and thus Modbus TCP/IP over Wi-Fi, its feature set is more optimized for low-power mesh networking. If Ethernet is required, an SPI-to-Ethernet module would be needed.
• Security: When using Modbus TCP/IP, especially over Wi-Fi or public networks, consider network security. ESP32 variants support WPA2/WPA3 for Wi-Fi security. For sensitive applications, consider VPNs or other network-level security measures, as Modbus TCP/IP itself does not include encryption or robust authentication.

Warning: Modbus TCP/IP, by default, does not encrypt data or provide strong authentication. Transmitting sensitive control data over unsecured networks (e.g., open Wi-Fi) is a significant security risk. Always implement appropriate network security measures.

Common Mistakes & Troubleshooting Tips

When working with Modbus TCP/IP, developers might encounter several common issues:

Exercises

1. Conceptual Server Design:Describe the key software components and data structures you would need to define within an ESP32 application (using ESP-IDF) to implement a Modbus TCP/IP server that exposes the following:
   • 10 Holding Registers (address 0-9) that can be read and written.
   • 5 Discrete Inputs (address 0-4) that reflect the state of 5 GPIO pins.What callback functions would be essential, and what would be their primary responsibilities?
2. Client Request Logic:Outline the sequence of steps an ESP32 acting as a Modbus TCP/IP client would need to perform to:
   • Connect to a Modbus TCP/IP server at IP address 192.168.1.100.
   • Read 5 holding registers starting from address 100.
   • Write the value 1234 to holding register at address 105.
   • Disconnect from the server.What information needs to be populated in the MBAP header for each request?
3. Gateway Scenario:Imagine an ESP32 is acting as a Modbus gateway, translating Modbus TCP/IP requests from an Ethernet network to a Modbus RTU serial network. If a TCP/IP client sends a request with Unit Identifier 0x05, how should the ESP32 gateway interpret this, and what actions should it take regarding the serial Modbus RTU network?
4. Error Handling and Robustness:Consider an ESP32 Modbus TCP/IP client application that continuously polls data from multiple servers. What strategies would you implement in the client application to handle:
   • A server becoming temporarily unresponsive?
   • A server returning a Modbus exception response?
   • Network disconnections and reconnections?

Summary

• Modbus TCP/IP is an adaptation of the Modbus protocol for use over TCP/IP networks, typically Ethernet.
• It replaces the serial line communication of Modbus RTU with TCP/IP sockets, using port 502 as the standard.
• The Modbus PDU (Function Code + Data) is encapsulated within an MBAP (Modbus Application Protocol) header for TCP/IP transmission.
• The MBAP header includes a Transaction Identifier, Protocol Identifier (0 for Modbus), Length field, and a Unit Identifier.
• TCP handles error checking and flow control, so Modbus-level CRC is not used in Modbus TCP/IP.
• ESP-IDF supports Modbus TCP/IP client (master) and server (slave) implementations via the freemodbus component, leveraging the LwIP TCP/IP stack.
• Proper network configuration (IP address, connectivity via Ethernet or Wi-Fi) is fundamental for Modbus TCP/IP operation on ESP32 devices.
• Different ESP32 variants offer varying levels of built-in support for Ethernet; all support Wi-Fi, which can also serve as a transport for Modbus TCP/IP.
• Security is a critical consideration, as Modbus TCP/IP itself does not provide encryption.

Further Reading

• Modbus Organization: For official specifications and protocol details.
  • Modbus Application Protocol Specification V1.1b3
  • Modbus Messaging on TCP/IP Implementation Guide V1.0b
• ESP-IDF Modbus Controller Documentation (ESP-IDF V5.x): Refer to the official Espressif documentation for API references and examples.
  • ESP-IDF Modbus Documentation (select your ESP-IDF version and target chip) (Link points to v5.2, adjust as needed for other v5.x versions).
• LwIP TCP/IP Stack: For understanding the underlying TCP/IP stack used in ESP-IDF.
  • Documentation is typically found within the ESP-IDF documentation or on the official LwIP Savannah site.
• RFC 793 – Transmission Control Protocol (TCP): For a deep understanding of the TCP protocol.
  • RFC 793