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-2019 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 1.9.6
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 //TLS supported?
74 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
75  #include "core/crypto.h"
76  #include "tls.h"
77 #endif
78 
79 //Forward declaration of ModbusClientContext structure
81 #define ModbusClientContext struct _ModbusClientContext
82 
83 //C++ guard
84 #ifdef __cplusplus
85 extern "C" {
86 #endif
87 
88 
89 /**
90  * @brief Modbus/TCP client states
91  */
92 
93 typedef enum
94 {
103 
104 
105 //TLS supported?
106 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
107 
108 /**
109  * @brief TLS initialization callback function
110  **/
111 
114 
115 #endif
116 
117 
118 /**
119  * @brief Modbus/TCP client context
120  **/
121 
123 {
124  ModbusClientState state; ///<Modbus/TCP client state
125  NetInterface *interface; ///<Underlying network interface
126  uint8_t unitId; ///<Identifier of the remote slave
127  uint16_t transactionId; ///<Modbus transaction identifier
128  Socket *socket; ///<Underlying TCP socket
129 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
130  TlsContext *tlsContext; ///<TLS context
131  TlsSessionState tlsSession; ///<TLS session state
132  ModbusClientTlsInitCallback tlsInitCallback; ///<TLS initialization callback function
133 #endif
134  systime_t timeout; ///<Timeout value
135  systime_t timestamp; ///<Timestamp to manage timeout
136  uint8_t requestAdu[MODBUS_MAX_ADU_SIZE]; ///<Request ADU
137  size_t requestAduLen; ///<Length of the request ADU, in bytes
138  size_t requestAduPos; ///<Current position in the request ADU
139  uint8_t responseAdu[MODBUS_MAX_ADU_SIZE]; ///<Response ADU
140  size_t responseAduLen; ///<Length of the response ADU, in bytes
141  size_t responseAduPos; ///<Current position in the response ADU
142  ModbusExceptionCode exceptionCode; ///<Exception code
143 };
144 
145 
146 //Modbus/TCP client related functions
148 
149 #if (MODBUS_CLIENT_TLS_SUPPORT == ENABLED)
150 
152  ModbusClientTlsInitCallback callback);
153 
154 #endif
155 
158 
160  NetInterface *interface);
161 
163  const IpAddr *serverIpAddr, uint16_t serverPort);
164 
166  uint16_t address, uint_t quantity, uint8_t *value);
167 
169  uint8_t address, uint_t quantity, uint8_t *value);
170 
172  uint16_t address, uint_t quantity, uint16_t *value);
173 
175  uint16_t address, uint_t quantity, uint16_t *value);
176 
178  uint16_t address, bool_t value);
179 
181  uint16_t address, uint16_t value);
182 
184  uint16_t address, uint_t quantity, const uint8_t *value);
185 
187  uint16_t address, uint_t quantity, const uint16_t *value);
188 
190  uint16_t address, uint16_t andMask, uint16_t orMask);
191 
193  uint16_t readAddress, uint_t readQuantity, uint16_t *readValue,
194  uint16_t writeAddress, uint_t writeQuantity, const uint16_t *writeValue);
195 
198 
201 
203 
204 //C++ guard
205 #ifdef __cplusplus
206 }
207 #endif
208 
209 #endif
error_t modbusClientReadHoldingRegs(ModbusClientContext *context, uint16_t address, uint_t quantity, uint16_t *value)
Read holding registers.
ModbusClientState
Modbus/TCP client states.
Definition: modbus_client.h:93
int bool_t
Definition: compiler_port.h:49
error_t modbusClientInit(ModbusClientContext *context)
Initialize Modbus/TCP client context.
Definition: modbus_client.c:51
IP network address.
Definition: ip.h:71
uint16_t andMask
Modbus/TCP client context.
error_t modbusClientWriteSingleReg(ModbusClientContext *context, uint16_t address, uint16_t value)
Write single register.
TlsSessionState tlsSession
TLS session state.
error_t modbusClientConnect(ModbusClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort)
Establish connection with the Modbus/TCP server.
#define ModbusClientContext
Definition: modbus_client.h:81
error_t modbusClientClose(ModbusClientContext *context)
Close the connection with the Modbus/TCP server.
error_t modbusClientReadCoils(ModbusClientContext *context, uint16_t address, uint_t quantity, uint8_t *value)
Read coils.
uint8_t responseAdu[MODBUS_MAX_ADU_SIZE]
Response ADU.
@ MODBUS_CLIENT_STATE_CONNECTING
Definition: modbus_client.h:96
error_t modbusClientBindToInterface(ModbusClientContext *context, NetInterface *interface)
Bind the Modbus/TCP client to a particular network interface.
error_t modbusClientReadInputRegs(ModbusClientContext *context, uint16_t address, uint_t quantity, uint16_t *value)
Read input registers.
size_t requestAduLen
Length of the request ADU, in bytes.
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:42
@ MODBUS_CLIENT_STATE_SENDING
Definition: modbus_client.h:98
size_t responseAduLen
Length of the response ADU, in bytes.
#define NetInterface
Definition: net.h:36
General definitions for cryptographic algorithms.
error_t modbusClientMaskWriteReg(ModbusClientContext *context, uint16_t address, uint16_t andMask, uint16_t orMask)
Apply AND/OR bitmask to a register.
size_t requestAduPos
Current position in the request ADU.
@ MODBUS_CLIENT_STATE_DISCONNECTING
ModbusClientState state
Modbus/TCP client state.
@ MODBUS_CLIENT_STATE_DISCONNECTED
Definition: modbus_client.h:95
@ MODBUS_CLIENT_STATE_RECEIVING
Definition: modbus_client.h:99
error_t modbusClientSetUnitId(ModbusClientContext *context, uint8_t unitId)
Set unit identifier.
error_t modbusClientWriteMultipleCoils(ModbusClientContext *context, uint16_t address, uint_t quantity, const uint8_t *value)
Write multiple coils.
uint16_t transactionId
Modbus transaction identifier.
NetInterface * interface
Underlying network interface.
uint8_t unitId
error_t(* ModbusClientTlsInitCallback)(ModbusClientContext *context, TlsContext *tlsContext)
TLS initialization callback function.
uint16_t orMask
void modbusClientDeinit(ModbusClientContext *context)
Release Modbus/TCP client context.
Definitions common to Modbus/TCP client and server.
TLS session state.
Definition: tls.h:1834
error_t modbusClientRegisterTlsInitCallback(ModbusClientContext *context, ModbusClientTlsInitCallback callback)
Register TLS initialization callback function.
Definition: modbus_client.c:98
#define Socket
Definition: socket.h:36
error_t modbusClientWriteMultipleRegs(ModbusClientContext *context, uint16_t address, uint_t quantity, const uint16_t *value)
Write multiple registers.
TLS (Transport Layer Security)
Ipv6Addr address
size_t responseAduPos
Current position in the response ADU.
ModbusClientTlsInitCallback tlsInitCallback
TLS initialization callback function.
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 modbusClientReadDiscreteInputs(ModbusClientContext *context, uint8_t address, uint_t quantity, uint8_t *value)
Read discrete inputs.
systime_t timestamp
Timestamp to manage timeout.
uint8_t requestAdu[MODBUS_MAX_ADU_SIZE]
Request ADU.
error_t modbusClientWriteSingleCoil(ModbusClientContext *context, uint16_t address, bool_t value)
Write single coil.
uint8_t unitId
Identifier of the remote slave.
uint8_t value[]
Definition: dtls_misc.h:150
unsigned int uint_t
Definition: compiler_port.h:45
ModbusExceptionCode exceptionCode
Exception code.
systime_t timeout
Timeout value.
TCP/IP stack core.
@ MODBUS_CLIENT_STATE_CONNECTED
Definition: modbus_client.h:97
ModbusExceptionCode
Modbus exception codes.
error_t modbusClientSetTimeout(ModbusClientContext *context, systime_t timeout)
Set timeout value for blocking operations.
TlsContext * tlsContext
TLS context.
error_t modbusClientDisconnect(ModbusClientContext *context)
Gracefully disconnect from the Modbus/TCP server.
uint8_t exceptionCode
Socket * socket
Underlying TCP socket.
uint32_t systime_t
Definition: compiler_port.h:46
error_t modbusClientGetExceptionCode(ModbusClientContext *context, ModbusExceptionCode *exceptionCode)
Retrieve exception code.
@ MODBUS_CLIENT_STATE_COMPLETE
#define MODBUS_MAX_ADU_SIZE
Definition: modbus_common.h:50