ClientTCP (FB) ¶ FUNCTION_BLOCK ClientTCP EXTENDS Client MODBUS TCP client (master). Please note: some input variables related to connection configuration are read when rising edge on xConnect occurs. To change connection configuration the application needs to - disconnect (xConnect := FALSE and execute the FB) - modify the related input variables - connect (xConnect := TRUE and execute the FB) The Client provides some statistics of sent request messages and received valid reply messages. Invalid messages are dropped at the communication level, so doesnt appear in the statistics. To analyse situations where invalid reply messages might occur, you can use udiLogOptions with LoggingOptions.WarnOnReceivedInvalidFrames. Please visit https://forge.codesys.com/prj/codesys-example/modbus/home to find examples. InOut: Scope Name Type Initial Comment Inherited from Input xConnect BOOL FALSE Connect to server (slave). Client Output xConnected BOOL Client (master) is connected to server (slave). Client xError BOOL Error Client eErrorID Error Error status Client udiNumMsgSent UDINT Number of request messages send since connect. Client udiNumMsgReply UDINT Number of reply messages received since connect. Client udiNumMsgExcReply UDINT Number of exception reply messages received since connect. Client udiNumMsgExcReplyIllFct UDINT Number of exception reply messages received since connect, signaling illegal function. Client udiNumMsgExcReplyIllDataAdr UDINT Number of exception reply messages received since connect, signaling illegal data address. Client udiNumReplyTimeouts UDINT Number of reply timeouts since connect. Client udiNumReqNotProcessed UDINT Number of requests not processed in time (“request starvation”) since connect. Client udiNumReqParamError UDINT Number of requests started with parameter error, for example “Read Coils” -> “Quantity of coils” = 0. Client udiLastTransactionTime UDINT Transaction time in ms - time difference between request message send und reply message received. Client Input aIPaddr ARRAY [0..3] OF BYTE [255, 255, 255, 255] ETH server (slave) address, only read when rising edge on xConnect occurs. uiPort UINT 502 ETH server (slave) port, only read when rising edge on xConnect occurs. tConnnectTimeOut TIME TIME#1s0ms Connect timeout (in milliseconds), only read when rising edge on xConnect occurs. udiLogOptions UDINT LoggingOptions.ClientConnectDisconnect Logging options.

Server ¶ ExampleDataModel (FunctionBlock) Server (FunctionBlock) Supported function codes “data model” “data item” offset / “data item” numbers DataModel CheckDataModel (Method) InitDataModel (Method) LogDataModel (Method) Log LogStatusInfo (Method) ResetRequestStatistics (Method) SupportFc (Method) SupportsFc (Method) ServerSerial (FunctionBlock) Log LogStatusInfo (Method) ServerTCP (FunctionBlock) Log LogStatusInfo (Method)

ExampleDataModel (FB) ¶ FUNCTION_BLOCK ExampleDataModel Simple “data model” example, contains four memory-separated sections containg two: - “discrete inputs” - “coils” - “input registers” - “holding registers” “data item” start index for all sections is 5 InOut: Scope Name Type Initial Comment Output tableDefs TableDefinitions STRUCT(tableDiscreteInputs := STRUCT(uiNumSections := (SIZEOF(_aDiscreteInputsSections) / SIZEOF(_aDiscreteInputsSections[0])), pSections := ADR(_aDiscreteInputsSections[0])), tableCoils := STRUCT(uiNumSections := (SIZEOF(_aCoilsSections) / SIZEOF(_aCoilsSections[0])), pSections := ADR(_aCoilsSections[0])), tableInputRegisters := STRUCT(uiNumSections := (SIZEOF(_aInputRegistersSections) / SIZEOF(_aInputRegistersSections[0])), pSections := ADR(_aInputRegistersSections[0])), tableHoldingRegisters := STRUCT(uiNumSections := (SIZEOF(_aHoldingRegistersSections) / SIZEOF(_aHoldingRegistersSections[0])), pSections := ADR(_aHoldingRegistersSections[0]))) the “data model” tables

Server (FB) ¶ FUNCTION_BLOCK ABSTRACT Server MODBUS server (slave) base class. Supported function codes ¶ Supported function codes can be configured, see fcsSupported. By default the MODBUS server supports: ReadCoils ReadDiscreteInputs ReadHoldingRegisters ReadInputRegisters WriteSingleCoil WriteSingleRegister WriteMultipleRegisters ReadWriteMultipleRegisters Optionally it supports also: MaskWriteRegister “data model” ¶ The “data model” allows: non-consecutive index for the “data items” (for example: index 0..9, 20..29) multiple (non-consecutive) memory blocks for “data items” in one “data block” (for example: index 0..9 => memory block 1, index 20..29 => memory block 2) not-memory-mapped “data items” (user code needs to be written to handle reads/writes for those “data items”) “discrete inputs” / “coils” : data item size 1 bit or 8 bit (basically: ARRAY [0..numBits/8] OF BYTE vs. ARRAY [0..numBits-1] OF BOOL) “input registers” / “holding registers” : data item size of 16 bit (basically: ARRAY [0..numRegisters-1] OF UDINT) overlapping memory blocks, could overlap “registers” with “registers” as well as “registers” with “discrete inputs” / “coils” (caution - hard to use feature) To support all this the “data model” ( TableDefinitions ) defines zero or more TableSection for each of the MODBUS “primary tables” ( TableDefinition ). Some more or less obvious limitations: all “data items” in one section need to have the same TableSection.uiDataItemSize all “data item” index in one “primary table” have to be unique, so no section index overlap is allowed of course read/write requests must not span more than one section “data item” offset / “data item” numbers ¶ Please note: unlike standard MODBUS, in CODESYS MODBUS the “data item” numbers are equal to the “data addresses”. The MODBUS standard states: “In the MODBUS data Model each element within a data block is numbered from 1 to n.” In CODESYS MODBUS the “data items” are numbered from 0 to n-1. InOut: Scope Name Type Initial Comment Input xEnable BOOL FALSE Enables the server, take over the configuration information fcsSupported and dataModel. If the “data model” (tableDefinitions) contains configuration errors, the Server will not got busy (xBusy = FALSE). fcsSupported SupportedFcs Constants.SUPPORTED_FCS_SIMPLE_SERVER Supported “function codes”, accepted at xEnable FALSE => TRUE. In case fcsSupported is not assigned by the application it defaults to Constants.SUPPORTED_FCS_SIMPLE_SERVER . dataModel TableDefinitions “data model”, accepted at xEnable FALSE => TRUE. tInactivityInfoTime UDINT 0 “inactivity info time” (in milliseconds). If no valid requests are received in this time xInactive is signaling inactivity - default = 0 -> no “inactivity info”. Output xRunning BOOL Server is up and running, waiting for requests. xError BOOL Error eErrorID Error Error status xInactive BOOL No valid requests received for tInactivityTimeOut. udiNumMsgRecv UDINT Request statistics: number of request messages received since enabling the Server. udiNumMsgReply UDINT Request statistics: number of reply messages send since enabling the Server. udiNumMsgExcReply UDINT Request statistics: number of exception reply messages send since enabling the Server. udiNumMsgExcReplyIllFct UDINT Request statistics: number of exception reply messages send since enabling the Server, signaling illegal function. udiNumMsgExcReplyIllDataAdr UDINT Request statistics: number of exception reply messages send since enabling the Server, signaling illegal data address. udiNumMsgExcReplyIllDataValue UDINT Request statistics: number of exception reply messages send since enabling the Server, signaling illegal data value. xReadRequest BOOL Read request(s) happened since last call, rejected requests included. udiNumReadRequests UDINT Request statistics: read request counter, rejected requests included. xWriteRequest BOOL Write request(s) happened since last call, rejected requests included. udiNumWriteRequests UDINT Request statistics: write request counter, rejected requests included. Methods: ResetRequestStatistics SupportFc SupportsFc CheckDataModel InitDataModel LogDataModel LogStatusInfo Structure: DataModel CheckDataModel (Method) InitDataModel (Method) LogDataModel (Method) Log LogStatusInfo (Method) ResetRequestStatistics (Method) SupportFc (Method) SupportsFc (Method)

Function Blocks ¶ Client Client (FunctionBlock) ClientRequest (FunctionBlock) Client request errors and timeout Client request errors and connection shutdown Timeout default “data item” offset / “data item” numbers ClientRequestMaskWriteRegister (FunctionBlock) ClientRequestRead (FunctionBlock) ClientRequestReadBits (FunctionBlock) ClientRequestReadCoils (FunctionBlock) ClientRequestReadDiscreteInputs (FunctionBlock) ClientRequestReadHoldingRegisters (FunctionBlock) ClientRequestReadInputRegisters (FunctionBlock) ClientRequestReadRegisters (FunctionBlock) ClientRequestReadWriteMultipleRegisters (FunctionBlock) ClientRequestWriteMultiple (FunctionBlock) ClientRequestWriteMultipleCoils (FunctionBlock) ClientRequestWriteMultipleRegisters (FunctionBlock) ClientRequestWriteSingle (FunctionBlock) ClientRequestWriteSingleCoil (FunctionBlock) ClientRequestWriteSingleRegister (FunctionBlock) ClientSerial (FunctionBlock) ClientTCP (FunctionBlock) Server ExampleDataModel (FunctionBlock) Server (FunctionBlock) Supported function codes “data model” “data item” offset / “data item” numbers DataModel CheckDataModel (Method) InitDataModel (Method) LogDataModel (Method) Log LogStatusInfo (Method) ResetRequestStatistics (Method) SupportFc (Method) SupportsFc (Method) ServerSerial (FunctionBlock) Log LogStatusInfo (Method) ServerTCP (FunctionBlock) Log LogStatusInfo (Method) Util ByteBuffer (FunctionBlock) BytesToEnd (Method) Capacity (Method) CopyContent (Method) Equals (Method) Freeze (Method) GetByte (Method) GetData (Method) GetDataPointerAt (Method) GetDataPointerAtPosition (Method) GetNBytes (Method) GetNBytesReverse (Method) GetNWords (Method) GetWord (Method) Init (Method) Len (Method) PutByte (Method) PutNBytes (Method) PutNBytesReverse (Method) PutNWords (Method) PutWord (Method) PutWordAt (Method) Rewind (Method) SetLen (Method) SetPos (Method) SetPosToEnd (Method)

Client ¶ Client (FunctionBlock) ClientRequest (FunctionBlock) Client request errors and timeout Client request errors and connection shutdown Timeout default “data item” offset / “data item” numbers ClientRequestMaskWriteRegister (FunctionBlock) ClientRequestRead (FunctionBlock) ClientRequestReadBits (FunctionBlock) ClientRequestReadCoils (FunctionBlock) ClientRequestReadDiscreteInputs (FunctionBlock) ClientRequestReadHoldingRegisters (FunctionBlock) ClientRequestReadInputRegisters (FunctionBlock) ClientRequestReadRegisters (FunctionBlock) ClientRequestReadWriteMultipleRegisters (FunctionBlock) ClientRequestWriteMultiple (FunctionBlock) ClientRequestWriteMultipleCoils (FunctionBlock) ClientRequestWriteMultipleRegisters (FunctionBlock) ClientRequestWriteSingle (FunctionBlock) ClientRequestWriteSingleCoil (FunctionBlock) ClientRequestWriteSingleRegister (FunctionBlock) ClientSerial (FunctionBlock) ClientTCP (FunctionBlock)

Client (FB) ¶ FUNCTION_BLOCK ABSTRACT Client IMPLEMENTS IClient MODBUS client (master) base class. Client provides the communication infrastructure for ClientRequest to work with. InOut: Scope Name Type Initial Comment Input xConnect BOOL FALSE Connect to server (slave). Output xConnected BOOL Client (master) is connected to server (slave). xError BOOL Error eErrorID Error Error status udiNumMsgSent UDINT Number of request messages send since connect. udiNumMsgReply UDINT Number of reply messages received since connect. udiNumMsgExcReply UDINT Number of exception reply messages received since connect. udiNumMsgExcReplyIllFct UDINT Number of exception reply messages received since connect, signaling illegal function. udiNumMsgExcReplyIllDataAdr UDINT Number of exception reply messages received since connect, signaling illegal data address. udiNumReplyTimeouts UDINT Number of reply timeouts since connect. udiNumReqNotProcessed UDINT Number of requests not processed in time (“request starvation”) since connect. udiNumReqParamError UDINT Number of requests started with parameter error, for example “Read Coils” -> “Quantity of coils” = 0. udiLastTransactionTime UDINT Transaction time in ms - time difference between request message send und reply message received.

ClientRequest (FB) ¶ FUNCTION_BLOCK ABSTRACT ClientRequest EXTENDS CBML.ETrigTo IMPLEMENTS IClientRequest MODBUS client (master) request base class. There are specific client request function blocks related to all supported MODBUS “function codes”. A ClientRequest relies on a Client to provide the communication infrastructure, this means a ClientRequest needs to be connected to one Client ( ClientSerial or ClientTCP ) to work with. Once a client request is triggered (rising edge on xExecute) it is processed by the Client it is connected to. The Client does process the triggered requests strictly in the order they got triggered (first come, first served). A successful client request is indicated by xDone=TRUE, a client request in progress is indicated by xBusy=TRUE. A failed client request is indicated by xError=TRUE, and a specific eErrorID. ClientRequest does have a timeout (it extends CBML.ETrigTo - udiTimeout in µs) to avoid endless, effectless client operations. So in general the application should: - trigger the request with rising edge on xExecute (set xExecute:=TRUE) - check if request is done (xDone=TRUE) or error occured (xError=TRUE) - falling edge on xExecute (set xExecute:=FALSE) - eventually repeat Client request errors and timeout ¶ A client request can fail (xError=TRUE) for different reason: “exception reply” - the server is answering in time, but signals an invalid request. In this case eErrorID is set to Error.RequestException and eException contains the specific exception code. This is kind of a normal reply a server can do, because of client request parameters not valid for the server “data model”. “reply timeout” - the server is not answering in time (udiReplyTimeout - for consistency to CBML.ETrigTo.udiTimeout in µs as well). This includes incomplete (frames) or invalid replies which are dropped, but does not include “exception replies”. In this case eErrorID is set to Error.ReplyTimeout. In general the application can’t do a lot about this type of error except choosing adequate udiReplyTimeout. “request starvation” - too many client requests triggered in parallel, causing a timeout (see udiTimeout) before server reply or “reply timeout” happens. In this case eErrorID is set to Error.RequestNotProcessed. In general the application is responsible to avoid “request starvation”. The client does process the client requests as fast as possible, but in sequential order. Processing one client request involves waiting for the server reply to be processed (including eventual “reply timeout”). In case a number of client requests are triggered in parallel, processing time and waiting sums up for the subsequent client requests triggered already, but not processed yet. Because “request starvation” can not be avoided in general, it is recommended to trigger client requests in “daisy chains” (first client request xDone=TRUE or xError=TRUE triggering second client request) to avoid client “request starvation” at all. Client request errors and connection shutdown ¶ In case of a client request there is no other action on client involved - the client connection stays alive. In case there is a need to disconnect the client (shutdown the client connection either TCP or serial) on such a single client request error, this has to be done in the application by setting client.xConnect:=FALSE. Timeout default ¶ It is not possible to overload member defaults of base classes in IEC61131. CBML.ETrigTo defaults udiTimeout to 0 which is not optimal for ClientRequest’s because it’s state machine would get stuck without timeout on “reply timeout” or “request starvation”. So ClientRequest.fb_init writes udiTimeout to 2s (in µs) initially. In case you want to chose another udiTimeout you need to assign it explicitly after initializaton (in a PLC application cycle). “data item” offset / “data item” numbers ¶ Please note: unlike standard MODBUS, in CODESYS MODBUS the “data item” numbers are equal to the “data addresses”. The MODBUS standard states: “In the MODBUS data Model each element within a data block is numbered from 1 to n.” In CODESYS MODBUS the “data items” are numbered from 0 to n-1. InOut: Scope Name Type Initial Comment Inherited from Input xExecute BOOL Rising edge: Starts defined operation FALSE : Resets the defined operation after ready condition was reached ETrigTo udiTimeOut UDINT Max. operating time for executing [µs], 0: No operating time limit ETrigTo Output xDone BOOL Ready condition reached ETrigTo xBusy BOOL Operation is running ETrigTo xError BOOL Error condition reached ETrigTo Inout rClient Client Reference to Client . Input uiUnitId UINT 0 Unit-Id to send the request to. udiReplyTimeout UDINT (50 * 1000) Reply timeout in µs - accepted maxmimum time between request message send and reply message receveived - default 50ms. uiMaxRetries UINT 0 Maximum number of request retries in case of “reply timeout”. Output eErrorID Error Error status eException ExceptionCodes Request exception code. uiRetryCnt UINT 0 Number of request retries in case of “reply timeout”.

ClientRequestMaskWriteRegister (FB) ¶ FUNCTION_BLOCK ClientRequestMaskWriteRegister EXTENDS ClientRequestWriteSingle MaskWriteRegister client request (FC22). For details about client request see ClientRequest . InOut: Scope Name Type Initial Comment Inherited from Input xExecute BOOL Rising edge: Starts defined operation FALSE : Resets the defined operation after ready condition was reached ETrigTo udiTimeOut UDINT Max. operating time for executing [µs], 0: No operating time limit ETrigTo Output xDone BOOL Ready condition reached ETrigTo xBusy BOOL Operation is running ETrigTo xError BOOL Error condition reached ETrigTo Inout rClient Client Reference to Client . ClientRequest Input uiUnitId UINT 0 Unit-Id to send the request to. ClientRequest udiReplyTimeout UDINT (50 * 1000) Reply timeout in µs - accepted maxmimum time between request message send and reply message receveived - default 50ms. ClientRequest uiMaxRetries UINT 0 Maximum number of request retries in case of “reply timeout”. ClientRequest Output eErrorID Error Error status ClientRequest eException ExceptionCodes Request exception code. ClientRequest uiRetryCnt UINT 0 Number of request retries in case of “reply timeout”. ClientRequest Input uiItem UINT 0 “data item” to write. ClientRequestWriteSingle uiAndMask UINT 0 The “AND mask”. uiOrMask UINT 0 The “OR mask”.

ClientRequestRead (FB) ¶ FUNCTION_BLOCK ABSTRACT ClientRequestRead EXTENDS ClientRequest Read client request base class for ReadCoils, ReadDiscreteInputs, ReadHoldingRegisters and ReadInputRegisters. InOut: Scope Name Type Initial Comment Inherited from Input xExecute BOOL Rising edge: Starts defined operation FALSE : Resets the defined operation after ready condition was reached ETrigTo udiTimeOut UDINT Max. operating time for executing [µs], 0: No operating time limit ETrigTo Output xDone BOOL Ready condition reached ETrigTo xBusy BOOL Operation is running ETrigTo xError BOOL Error condition reached ETrigTo Inout rClient Client Reference to Client . ClientRequest Input uiUnitId UINT 0 Unit-Id to send the request to. ClientRequest udiReplyTimeout UDINT (50 * 1000) Reply timeout in µs - accepted maxmimum time between request message send and reply message receveived - default 50ms. ClientRequest uiMaxRetries UINT 0 Maximum number of request retries in case of “reply timeout”. ClientRequest Output eErrorID Error Error status ClientRequest eException ExceptionCodes Request exception code. ClientRequest uiRetryCnt UINT 0 Number of request retries in case of “reply timeout”. ClientRequest Input uiStartItem UINT 0 First “data item” to read. uiQuantity UINT 1 Number of “data items” to read. ReadCoils / ReadDiscreteInputs: 1 to 2000 ReadHoldingRegisters / ReadInputRegisters: 1 to 125