modbus_server.h
Go to the documentation of this file.
1 /**
2  * @file modbus_server.h
3  * @brief Modbus/TCP server
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2023 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.3.2
29  **/
30 
31 #ifndef _MODBUS_SERVER_H
32 #define _MODBUS_SERVER_H
33 
34 //Dependencies
35 #include "core/net.h"
36 #include "modbus/modbus_common.h"
37 
38 //Modbus/TCP server support
39 #ifndef MODBUS_SERVER_SUPPORT
40  #define MODBUS_SERVER_SUPPORT ENABLED
41 #elif (MODBUS_SERVER_SUPPORT != ENABLED && MODBUS_SERVER_SUPPORT != DISABLED)
42  #error MODBUS_SERVER_SUPPORT parameter is not valid
43 #endif
44 
45 //Modbus/TCP security
46 #ifndef MODBUS_SERVER_TLS_SUPPORT
47  #define MODBUS_SERVER_TLS_SUPPORT DISABLED
48 #elif (MODBUS_SERVER_TLS_SUPPORT != ENABLED && MODBUS_SERVER_TLS_SUPPORT != DISABLED)
49  #error MODBUS_SERVER_TLS_SUPPORT parameter is not valid
50 #endif
51 
52 //Stack size required to run the Modbus/TCP server
53 #ifndef MODBUS_SERVER_STACK_SIZE
54  #define MODBUS_SERVER_STACK_SIZE 650
55 #elif (MODBUS_SERVER_STACK_SIZE < 1)
56  #error MODBUS_SERVER_STACK_SIZE parameter is not valid
57 #endif
58 
59 //Priority at which the Modbus/TCP server should run
60 #ifndef MODBUS_SERVER_PRIORITY
61  #define MODBUS_SERVER_PRIORITY OS_TASK_PRIORITY_NORMAL
62 #endif
63 
64 //Maximum number of simultaneous connections
65 #ifndef MODBUS_SERVER_MAX_CONNECTIONS
66  #define MODBUS_SERVER_MAX_CONNECTIONS 2
67 #elif (MODBUS_SERVER_MAX_CONNECTIONS < 1)
68  #error MODBUS_SERVER_MAX_CONNECTIONS parameter is not valid
69 #endif
70 
71 //Idle connection timeout
72 #ifndef MODBUS_SERVER_TIMEOUT
73  #define MODBUS_SERVER_TIMEOUT 60000
74 #elif (MODBUS_SERVER_TIMEOUT < 1000)
75  #error MODBUS_SERVER_TIMEOUT parameter is not valid
76 #endif
77 
78 //Modbus/TCP server tick interval
79 #ifndef MODBUS_SERVER_TICK_INTERVAL
80  #define MODBUS_SERVER_TICK_INTERVAL 1000
81 #elif (MODBUS_SERVER_TICK_INTERVAL < 100)
82  #error MODBUS_SERVER_TICK_INTERVAL parameter is not valid
83 #endif
84 
85 //TX buffer size for TLS connections
86 #ifndef MODBUS_SERVER_TLS_TX_BUFFER_SIZE
87  #define MODBUS_SERVER_TLS_TX_BUFFER_SIZE 2048
88 #elif (MODBUS_SERVER_TLS_TX_BUFFER_SIZE < 512)
89  #error MODBUS_SERVER_TLS_TX_BUFFER_SIZE parameter is not valid
90 #endif
91 
92 //RX buffer size for TLS connections
93 #ifndef MODBUS_SERVER_TLS_RX_BUFFER_SIZE
94  #define MODBUS_SERVER_TLS_RX_BUFFER_SIZE 2048
95 #elif (MODBUS_SERVER_TLS_RX_BUFFER_SIZE < 512)
96  #error MODBUS_SERVER_TLS_RX_BUFFER_SIZE parameter is not valid
97 #endif
98 
99 //Maximum length of the client role OID
100 #ifndef MODBUS_SERVER_MAX_ROLE_LEN
101  #define MODBUS_SERVER_MAX_ROLE_LEN 32
102 #elif (MODBUS_SERVER_MAX_ROLE_LEN < 0)
103  #error MODBUS_SERVER_MAX_ROLE_LEN parameter is not valid
104 #endif
105 
106 //Application specific context
107 #ifndef MODBUS_SERVER_PRIVATE_CONTEXT
108  #define MODBUS_SERVER_PRIVATE_CONTEXT
109 #endif
110 
111 //TLS supported?
112 #if (MODBUS_SERVER_TLS_SUPPORT == ENABLED)
113  #include "core/crypto.h"
114  #include "tls.h"
115  #include "tls_ticket.h"
116 #endif
117 
118 //Forward declaration of ModbusServerContext structure
119 struct _ModbusServerContext;
120 #define ModbusServerContext struct _ModbusServerContext
121 
122 //Forward declaration of ModbusClientConnection structure
124 #define ModbusClientConnection struct _ModbusClientConnection
125 
126 //C++ guard
127 #ifdef __cplusplus
128 extern "C" {
129 #endif
130 
131 
132 /**
133  * @brief Modbus/TCP connection state
134  **/
135 
136 typedef enum
137 {
146 
147 
148 /**
149  * @brief TCP connection open callback function
150  **/
151 
153  IpAddr clientIpAddr, uint16_t clientPort);
154 
155 
156 /**
157  * @brief TCP connection close callback function
158  **/
159 
161 
162 
163 //TLS supported?
164 #if (MODBUS_SERVER_TLS_SUPPORT == ENABLED)
165 
166 /**
167  * @brief TLS initialization callback function
168  **/
169 
172 
173 #endif
174 
175 
176 /**
177  * @brief Lock Modbus table callback function
178  **/
179 
180 typedef void (*ModbusServerLockCallback)(void);
181 
182 
183 /**
184  * @brief Unlock Modbus table callback function
185  **/
186 
187 typedef void (*ModbusServerUnlockCallback)(void);
188 
189 
190 /**
191  * @brief Get coil state callback function
192  **/
193 
195  uint16_t address, bool_t *state);
196 
197 
198 /**
199  * @brief Set coil state callback function
200  **/
201 
203  uint16_t address, bool_t state, bool_t commit);
204 
205 
206 /**
207  * @brief Get register value callback function
208  **/
209 
211  uint16_t address, uint16_t *value);
212 
213 
214 /**
215  * @brief Set register value callback function
216  **/
217 
219  uint16_t address, uint16_t value, bool_t commit);
220 
221 
222 /**
223  * @brief PDU processing callback function
224  **/
225 
226 typedef error_t (*ModbusServerProcessPduCallback)(const uint8_t *request,
227  size_t requestLen, uint8_t *response, size_t *responseLen);
228 
229 
230 /**
231  * @brief Tick callback function
232  **/
233 
235 
236 
237 /**
238  * @brief Modbus/TCP server settings
239  **/
240 
241 typedef struct
242 {
243  NetInterface *interface; ///<Underlying network interface
244  uint16_t port; ///<Modbus/TCP port number
245  uint8_t unitId; ///<Unit identifier
246  systime_t timeout; ///<Idle connection timeout
247  ModbusServerOpenCallback openCallback; ///<TCP connection open callback function
248  ModbusServerCloseCallback closeCallback; ///<TCP connection close callback function
249 #if (MODBUS_SERVER_TLS_SUPPORT == ENABLED)
250  ModbusServerTlsInitCallback tlsInitCallback; ///<TLS initialization callback function
251 #endif
252  ModbusServerLockCallback lockCallback; ///<Lock Modbus table callback function
253  ModbusServerUnlockCallback unlockCallback; ///<Unlock Modbus table callback function
254  ModbusServerReadCoilCallback readCoilCallback; ///<Get coil state callback function
255  ModbusServerReadCoilCallback readDiscreteInputCallback; ///<Get discrete input state callback function
256  ModbusServerWriteCoilCallback writeCoilCallback; ///<Set coil state callback function
257  ModbusServerReadRegCallback readRegCallback; ///<Get register value callback function
258  ModbusServerReadRegCallback readHoldingRegCallback; ///<Get holding register value callback function
259  ModbusServerReadRegCallback readInputRegCallback; ///<Get input register value callback function
260  ModbusServerWriteRegCallback writeRegCallback; ///<Set register value callback function
261  ModbusServerProcessPduCallback processPduCallback; ///<PDU processing callback function
262  ModbusServerTickCallback tickCallback; ///<Tick callback function
264 
265 
266 /**
267  * @brief Modbus/TCP client connection
268  **/
269 
271 {
272  ModbusConnectionState state; ///<Connection state
273  ModbusServerContext *context; ///<Modbus/TCP server context
274  Socket *socket; ///<Underlying socket
275 #if (MODBUS_SERVER_TLS_SUPPORT == ENABLED)
276  TlsContext *tlsContext; ///<TLS context
277 #endif
278  char_t role[MODBUS_SERVER_MAX_ROLE_LEN + 1]; ///<Client role OID
279  systime_t timestamp; ///<Time stamp
280  uint8_t requestAdu[MODBUS_MAX_ADU_SIZE]; ///<Request ADU
281  size_t requestAduLen; ///<Length of the request ADU, in bytes
282  size_t requestAduPos; ///<Current position in the request ADU
283  uint8_t requestUnitId; ///<Unit identifier
284  uint8_t responseAdu[MODBUS_MAX_ADU_SIZE]; ///<Response ADU
285  size_t responseAduLen; ///<Length of the response ADU, in bytes
286  size_t responseAduPos; ///<Current position in the response ADU
287 };
288 
289 
290 /**
291  * @brief Modbus/TCP server context
292  **/
293 
295 {
296  ModbusServerSettings settings; ///<User settings
297  bool_t running; ///<Operational state of the Modbus/TCP server
298  bool_t stop; ///<Stop request
299  OsEvent event; ///<Event object used to poll the sockets
300  OsTaskId taskId; ///<Task identifier
301 #if (OS_STATIC_TASK_SUPPORT == ENABLED)
302  OsTaskTcb taskTcb; ///<Task control block
304 #endif
305  Socket *socket; ///<Listening socket
307 #if (MODBUS_SERVER_TLS_SUPPORT == ENABLED && TLS_TICKET_SUPPORT == ENABLED)
308  TlsTicketContext tlsTicketContext; ///<TLS ticket encryption context
309 #endif
310  MODBUS_SERVER_PRIVATE_CONTEXT ///<Application specific context
311 };
312 
313 
314 //Modbus/TCP server related functions
316 
318  const ModbusServerSettings *settings);
319 
322 
324 
326 
327 //C++ guard
328 #ifdef __cplusplus
329 }
330 #endif
331 
332 #endif
char char_t
Definition: compiler_port.h:48
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:314
Definitions common to Modbus/TCP client and server.
#define MODBUS_MAX_ADU_SIZE
Definition: modbus_common.h:50
error_t(* ModbusServerReadCoilCallback)(const char_t *role, uint16_t address, bool_t *state)
Get coil state callback function.
error_t(* ModbusServerWriteCoilCallback)(const char_t *role, uint16_t address, bool_t state, bool_t commit)
Set coil state callback function.
void(* ModbusServerCloseCallback)(ModbusClientConnection *connection)
TCP connection close callback function.
error_t(* ModbusServerProcessPduCallback)(const uint8_t *request, size_t requestLen, uint8_t *response, size_t *responseLen)
PDU processing callback function.
#define MODBUS_SERVER_STACK_SIZE
Definition: modbus_server.h:54
#define ModbusServerContext
error_t(* ModbusServerReadRegCallback)(const char_t *role, uint16_t address, uint16_t *value)
Get register value callback function.
void modbusServerDeinit(ModbusServerContext *context)
Release Modbus/TCP server context.
#define MODBUS_SERVER_PRIVATE_CONTEXT
error_t(* ModbusServerWriteRegCallback)(const char_t *role, uint16_t address, uint16_t value, bool_t commit)
Set register value callback function.
error_t(* ModbusServerOpenCallback)(ModbusClientConnection *connection, IpAddr clientIpAddr, uint16_t clientPort)
TCP connection open callback function.
void(* ModbusServerTickCallback)(ModbusServerContext *context)
Tick callback function.
void(* ModbusServerLockCallback)(void)
Lock Modbus table callback function.
ModbusConnectionState
Modbus/TCP connection state.
@ MODBUS_CONNECTION_STATE_SEND
@ MODBUS_CONNECTION_STATE_RECEIVE
@ MODBUS_CONNECTION_STATE_CONNECT_TLS
@ MODBUS_CONNECTION_STATE_SHUTDOWN_TLS
@ MODBUS_CONNECTION_STATE_SHUTDOWN_RX
@ MODBUS_CONNECTION_STATE_SHUTDOWN_TX
@ MODBUS_CONNECTION_STATE_CLOSED
error_t modbusServerInit(ModbusServerContext *context, const ModbusServerSettings *settings)
Initialize Modbus/TCP server context.
#define MODBUS_SERVER_MAX_ROLE_LEN
#define ModbusClientConnection
void(* ModbusServerUnlockCallback)(void)
Unlock Modbus table callback function.
void modbusServerTask(ModbusServerContext *context)
Modbus/TCP server task.
error_t(* ModbusServerTlsInitCallback)(ModbusClientConnection *connection, TlsContext *tlsContext)
TLS initialization callback function.
#define MODBUS_SERVER_MAX_CONNECTIONS
Definition: modbus_server.h:66
void modbusServerGetDefaultSettings(ModbusServerSettings *settings)
Initialize settings with default values.
Definition: modbus_server.c:49
error_t modbusServerStop(ModbusServerContext *context)
Stop Modbus/TCP server.
error_t modbusServerStart(ModbusServerContext *context)
Start Modbus/TCP server.
TCP/IP stack core.
#define NetInterface
Definition: net.h:36
uint32_t systime_t
System time.
uint32_t OsStackType
Stack data type.
thread_t * OsTaskId
Task identifier.
#define Socket
Definition: socket.h:36
Modbus/TCP client connection.
uint8_t responseAdu[MODBUS_MAX_ADU_SIZE]
Response ADU.
systime_t timestamp
Time stamp.
size_t responseAduLen
Length of the response ADU, in bytes.
size_t requestAduLen
Length of the request ADU, in bytes.
TlsContext * tlsContext
TLS context.
uint8_t requestUnitId
Unit identifier.
ModbusConnectionState state
Connection state.
char_t role[MODBUS_SERVER_MAX_ROLE_LEN+1]
Client role OID.
uint8_t requestAdu[MODBUS_MAX_ADU_SIZE]
Request ADU.
ModbusServerContext * context
Modbus/TCP server context.
size_t responseAduPos
Current position in the response ADU.
size_t requestAduPos
Current position in the request ADU.
Socket * socket
Underlying socket.
Modbus/TCP server context.
ModbusServerSettings settings
User settings.
bool_t stop
Stop request.
OsStackType taskStack[MODBUS_SERVER_STACK_SIZE]
Task stack.
OsTaskId taskId
Task identifier.
bool_t running
Operational state of the Modbus/TCP server.
TlsTicketContext tlsTicketContext
TLS ticket encryption context.
ModbusClientConnection connection[MODBUS_SERVER_MAX_CONNECTIONS]
Client connections.
OsTaskTcb taskTcb
Task control block.
Socket * socket
Listening socket.
OsEvent event
Event object used to poll the sockets.
IP network address.
Definition: ip.h:72
Modbus/TCP server settings.
ModbusServerTlsInitCallback tlsInitCallback
TLS initialization callback function.
ModbusServerLockCallback lockCallback
Lock Modbus table callback function.
ModbusServerWriteCoilCallback writeCoilCallback
Set coil state callback function.
uint8_t unitId
Unit identifier.
ModbusServerOpenCallback openCallback
TCP connection open callback function.
ModbusServerReadCoilCallback readDiscreteInputCallback
Get discrete input state callback function.
ModbusServerUnlockCallback unlockCallback
Unlock Modbus table callback function.
ModbusServerCloseCallback closeCallback
TCP connection close callback function.
uint16_t port
Modbus/TCP port number.
ModbusServerTickCallback tickCallback
Tick callback function.
ModbusServerReadRegCallback readRegCallback
Get register value callback function.
ModbusServerReadRegCallback readHoldingRegCallback
Get holding register value callback function.
ModbusServerReadCoilCallback readCoilCallback
Get coil state callback function.
systime_t timeout
Idle connection timeout.
ModbusServerProcessPduCallback processPduCallback
PDU processing callback function.
ModbusServerReadRegCallback readInputRegCallback
Get input register value callback function.
NetInterface * interface
Underlying network interface.
ModbusServerWriteRegCallback writeRegCallback
Set register value callback function.
Event object.
Task control block.
Session ticket encryption context.
Definition: tls_ticket.h:91
uint8_t value[]
Definition: tcp.h:367
TLS (Transport Layer Security)
#define TlsContext
Definition: tls.h:36
TLS session tickets.