modbus_client.h
Go to the documentation of this file.
1 /**
2  * @file modbus_client.h
3  * @brief Modbus/TCP client
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.4.0
29  **/
30 
31 #ifndef _MODBUS_CLIENT_H
32 #define _MODBUS_CLIENT_H
33 
34 //Dependencies
35 #include "core/net.h"
36 #include "modbus/modbus_common.h"
37 
38 //Modbus/TCP client support
39 #ifndef MODBUS_CLIENT_SUPPORT
40  #define MODBUS_CLIENT_SUPPORT ENABLED
41 #elif (MODBUS_CLIENT_SUPPORT != ENABLED && MODBUS_CLIENT_SUPPORT != DISABLED)
42  #error MODBUS_CLIENT_SUPPORT parameter is not valid
43 #endif
44 
45 //Modbus/TCP security
46 #ifndef MODBUS_CLIENT_TLS_SUPPORT
47  #define MODBUS_CLIENT_TLS_SUPPORT DISABLED
48 #elif (MODBUS_CLIENT_TLS_SUPPORT != ENABLED && MODBUS_CLIENT_TLS_SUPPORT != DISABLED)
49  #error MODBUS_CLIENT_TLS_SUPPORT parameter is not valid
50 #endif
51 
52 //Default timeout
53 #ifndef MODBUS_CLIENT_DEFAULT_TIMEOUT
54  #define MODBUS_CLIENT_DEFAULT_TIMEOUT 20000
55 #elif (MODBUS_CLIENT_DEFAULT_TIMEOUT < 0)
56  #error MODBUS_CLIENT_DEFAULT_TIMEOUT parameter is not valid
57 #endif
58 
59 //TX buffer size for TLS connections
60 #ifndef MODBUS_CLIENT_TLS_TX_BUFFER_SIZE
61  #define MODBUS_CLIENT_TLS_TX_BUFFER_SIZE 2048
62 #elif (MODBUS_CLIENT_TLS_TX_BUFFER_SIZE < 512)
63  #error MODBUS_CLIENT_TLS_TX_BUFFER_SIZE parameter is not valid
64 #endif
65 
66 //RX buffer size for TLS connections
67 #ifndef MODBUS_CLIENT_TLS_RX_BUFFER_SIZE
68  #define MODBUS_CLIENT_TLS_RX_BUFFER_SIZE 2048
69 #elif (MODBUS_CLIENT_TLS_RX_BUFFER_SIZE < 512)
70  #error MODBUS_CLIENT_TLS_RX_BUFFER_SIZE parameter is not valid
71 #endif
72 
73 //Application specific context
74 #ifndef MODBUS_CLIENT_PRIVATE_CONTEXT
75  #define MODBUS_CLIENT_PRIVATE_CONTEXT
76 #endif
77 
78 //TLS supported?
79 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
80  #include "core/crypto.h"
81  #include "tls.h"
82 #endif
83 
84 //Forward declaration of ModbusClientContext structure
86 #define ModbusClientContext struct _ModbusClientContext
87 
88 //C++ guard
89 #ifdef __cplusplus
90 extern "C" {
91 #endif
92 
93 
94 /**
95  * @brief Modbus/TCP client states
96  */
97 
98 typedef enum
99 {
108 
109 
110 //TLS supported?
111 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
112 
113 /**
114  * @brief TLS initialization callback function
115  **/
116 
119 
120 #endif
121 
122 
123 /**
124  * @brief Modbus/TCP client context
125  **/
126 
128 {
129  ModbusClientState state; ///<Modbus/TCP client state
130  NetInterface *interface; ///<Underlying network interface
131  uint8_t unitId; ///<Identifier of the remote slave
132  uint16_t transactionId; ///<Modbus transaction identifier
133  Socket *socket; ///<Underlying TCP socket
134 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
135  TlsContext *tlsContext; ///<TLS context
136  TlsSessionState tlsSession; ///<TLS session state
137  ModbusClientTlsInitCallback tlsInitCallback; ///<TLS initialization callback function
138 #endif
139  systime_t timeout; ///<Timeout value
140  systime_t timestamp; ///<Timestamp to manage timeout
141  uint8_t requestAdu[MODBUS_MAX_ADU_SIZE]; ///<Request ADU
142  size_t requestAduLen; ///<Length of the request ADU, in bytes
143  size_t requestAduPos; ///<Current position in the request ADU
144  uint8_t responseAdu[MODBUS_MAX_ADU_SIZE]; ///<Response ADU
145  size_t responseAduLen; ///<Length of the response ADU, in bytes
146  size_t responseAduPos; ///<Current position in the response ADU
147  ModbusExceptionCode exceptionCode; ///<Exception code
148  MODBUS_CLIENT_PRIVATE_CONTEXT ///<Application specific context
149 };
150 
151 
152 //Modbus/TCP client related functions
154 
155 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
156 
158  ModbusClientTlsInitCallback callback);
159 
160 #endif
161 
164 
166  NetInterface *interface);
167 
169  const IpAddr *serverIpAddr, uint16_t serverPort);
170 
172  uint16_t address, uint_t quantity, uint8_t *value);
173 
175  uint16_t address, uint_t quantity, uint8_t *value);
176 
178  uint16_t address, uint_t quantity, uint16_t *value);
179 
181  uint16_t address, uint_t quantity, uint16_t *value);
182 
184  uint16_t address, bool_t value);
185 
187  uint16_t address, uint16_t value);
188 
190  uint16_t address, uint_t quantity, const uint8_t *value);
191 
193  uint16_t address, uint_t quantity, const uint16_t *value);
194 
196  uint16_t address, uint16_t andMask, uint16_t orMask);
197 
199  uint16_t readAddress, uint_t readQuantity, uint16_t *readValue,
200  uint16_t writeAddress, uint_t writeQuantity, const uint16_t *writeValue);
201 
204 
207 
209 
210 //C++ guard
211 #ifdef __cplusplus
212 }
213 #endif
214 
215 #endif
unsigned int uint_t
Definition: compiler_port.h:50
int bool_t
Definition: compiler_port.h:53
General definitions for cryptographic algorithms.
error_t
Error codes.
Definition: error.h:43
Ipv6Addr address[]
Definition: ipv6.h:316
error_t modbusClientInit(ModbusClientContext *context)
Initialize Modbus/TCP client context.
Definition: modbus_client.c:51
error_t modbusClientReadHoldingRegs(ModbusClientContext *context, uint16_t address, uint_t quantity, uint16_t *value)
Read holding registers.
error_t modbusClientDisconnect(ModbusClientContext *context)
Gracefully disconnect from the Modbus/TCP server.
error_t modbusClientSetUnitId(ModbusClientContext *context, uint8_t unitId)
Set unit identifier.
error_t modbusClientReadDiscreteInputs(ModbusClientContext *context, uint16_t address, uint_t quantity, uint8_t *value)
Read discrete inputs.
#define MODBUS_CLIENT_PRIVATE_CONTEXT
Definition: modbus_client.h:75
error_t modbusClientClose(ModbusClientContext *context)
Close the connection with the Modbus/TCP server.
error_t modbusClientWriteMultipleRegs(ModbusClientContext *context, uint16_t address, uint_t quantity, const uint16_t *value)
Write multiple registers.
error_t(* ModbusClientTlsInitCallback)(ModbusClientContext *context, TlsContext *tlsContext)
TLS initialization callback function.
error_t modbusClientRegisterTlsInitCallback(ModbusClientContext *context, ModbusClientTlsInitCallback callback)
Register TLS initialization callback function.
Definition: modbus_client.c:98
error_t modbusClientConnect(ModbusClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort)
Establish connection with the Modbus/TCP server.
error_t modbusClientReadCoils(ModbusClientContext *context, uint16_t address, uint_t quantity, uint8_t *value)
Read coils.
error_t modbusClientMaskWriteReg(ModbusClientContext *context, uint16_t address, uint16_t andMask, uint16_t orMask)
Apply AND/OR bitmask to a register.
error_t modbusClientBindToInterface(ModbusClientContext *context, NetInterface *interface)
Bind the Modbus/TCP client to a particular network interface.
error_t modbusClientWriteSingleReg(ModbusClientContext *context, uint16_t address, uint16_t value)
Write single register.
error_t modbusClientReadWriteMultipleRegs(ModbusClientContext *context, uint16_t readAddress, uint_t readQuantity, uint16_t *readValue, uint16_t writeAddress, uint_t writeQuantity, const uint16_t *writeValue)
Read/write multiple registers.
error_t modbusClientWriteSingleCoil(ModbusClientContext *context, uint16_t address, bool_t value)
Write single coil.
error_t modbusClientReadInputRegs(ModbusClientContext *context, uint16_t address, uint_t quantity, uint16_t *value)
Read input registers.
void modbusClientDeinit(ModbusClientContext *context)
Release Modbus/TCP client context.
error_t modbusClientGetExceptionCode(ModbusClientContext *context, ModbusExceptionCode *exceptionCode)
Retrieve exception code.
error_t modbusClientSetTimeout(ModbusClientContext *context, systime_t timeout)
Set timeout value for blocking operations.
ModbusClientState
Modbus/TCP client states.
Definition: modbus_client.h:99
@ MODBUS_CLIENT_STATE_SENDING
@ MODBUS_CLIENT_STATE_CONNECTED
@ MODBUS_CLIENT_STATE_CONNECTING
@ MODBUS_CLIENT_STATE_COMPLETE
@ MODBUS_CLIENT_STATE_DISCONNECTING
@ MODBUS_CLIENT_STATE_RECEIVING
@ MODBUS_CLIENT_STATE_DISCONNECTED
error_t modbusClientWriteMultipleCoils(ModbusClientContext *context, uint16_t address, uint_t quantity, const uint8_t *value)
Write multiple coils.
#define ModbusClientContext
Definition: modbus_client.h:86
Definitions common to Modbus/TCP client and server.
ModbusExceptionCode
Modbus exception codes.
#define MODBUS_MAX_ADU_SIZE
Definition: modbus_common.h:50
uint8_t unitId
uint8_t exceptionCode
uint16_t orMask
uint16_t andMask
TCP/IP stack core.
#define NetInterface
Definition: net.h:36
uint32_t systime_t
System time.
#define Socket
Definition: socket.h:36
Modbus/TCP client context.
uint8_t responseAdu[MODBUS_MAX_ADU_SIZE]
Response ADU.
systime_t timestamp
Timestamp to manage timeout.
ModbusClientTlsInitCallback tlsInitCallback
TLS initialization callback function.
size_t responseAduLen
Length of the response ADU, in bytes.
ModbusClientState state
Modbus/TCP client state.
size_t requestAduLen
Length of the request ADU, in bytes.
TlsContext * tlsContext
TLS context.
uint8_t unitId
Identifier of the remote slave.
uint8_t requestAdu[MODBUS_MAX_ADU_SIZE]
Request ADU.
size_t responseAduPos
Current position in the response ADU.
systime_t timeout
Timeout value.
size_t requestAduPos
Current position in the request ADU.
Socket * socket
Underlying TCP socket.
uint16_t transactionId
Modbus transaction identifier.
TlsSessionState tlsSession
TLS session state.
NetInterface * interface
Underlying network interface.
ModbusExceptionCode exceptionCode
Exception code.
IP network address.
Definition: ip.h:79
TLS session state.
Definition: tls.h:2021
uint8_t value[]
Definition: tcp.h:369
TLS (Transport Layer Security)
#define TlsContext
Definition: tls.h:36