lib-modbus - IBV - Echtzeit- und Embedded GmbH & Co. KG
Contents
1. inte t slave uintlo Starte rer urntlo Pec array uIHLlo E fer count int modbus read input regrsters scruct Client Connection connection uinte Slave Vantle L Start fert wintlo C reg array WUnele E ref count int modbus vrite single register struct client Connection y wince t slave uintlo C eg ref Uintle t reg value inc modbus write multiple regrstersi struct client connection connecet on unte t Slave Uinti Start ref Uinti rt reg array nntlo rer counti int modbus mask wILIte register istruct client connection connectronm uinte C slave urnbtbe 5 feo ret uintlo and mask uznrlo Of mask LIB MODBUS PROGRAMMERS MANUAL DOC Seite 10 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG int modbus read write registers struct client Connection Connection ulnes U Slave Uantle t read rer Uintle t read array uinti t read Count UIUtl6 5 write ret urxntlo t write array Uinti t write count Arrays of uint16 t are used to transfer data from the user application to the MODBUS library Each input register or holding register corresponds to one array element with index 0 referencing the item specified by the start ref parameter The modbus write single register function operates on a single holding register whose value is supplied as a single uint16 t argument The modbus mask write register function operates on a single holding register too but takes an an2. software is released for Operating System QNX 6 3 0 with Service Pack 3 2 1 Preconditions QNX 6 running on the target platform Ethernet link to the target platform 2 2 Installation Procedure Copy the file 1iblib modbus so to the desired target directory usually 1ib renaming it to liblib modbus so 1 The header files from the common subdirectory have to be made available to the user application either by copying them to a system wide location or by adding the directory to the include paths searched by the compiler The library files liblib modbus so and liblib modbus_g so debug variant from the binaries subdirectory have to made available to the user application either by copying them to a system wide location or by adding the directory to the library paths searched by the linker e LIB MODBUS PROGRAMMERS MANUAL DOC Seite 5 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG 3 Library Description 3 1 Header Files The following headers have to be included by a user application modbus common h Defines and declarations used by client and server modbus client h Application interface to client functionality modbus server h Application interface to server functionality All necessary header files can be found in the source common subdirectory A user application may decide to include only one of modbus client h and modbus server h if client and server functionality isn t r
3. IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG te zT ZZ amp Realtime is BLUE e lib modbus MODBUS TCP Client and Server Library Programmers Manual IBV MODBUS 0001 Issue 1 0 06 03 2008 Author Reviewed Released VA i JIU IL A Dominic Rath Rath z Vollbraght Lutz Vollbrach LIB MODBUS PROGRAMMERS MANUAL DOC Seite 1 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG Change Log e LIB MODBUS PROGRAMMERS MANUAL DOC Seite 2 von 11 IBV ECHTZ EIT UND EMBEDDED GMBH amp CO KG Table of Contents 1 lereilidur berein meE M 4 Il PUDO MC 4 1 2 TERNINOIOON a ee ee en ee een 4 1292 A TTO ce 4 kie ROIENC E NEU 4 2 INStallal ON a a ES a 5 212 i es pee MATT A nee EA 5 2 2 INSlallauon Procedu RR TT ennan aea EEREN E eE EEEE E EAEE Ea EN a Enina 5 S Library DESEFIDH OM nee anne 6 3 1 Header Files nennen Tt 6 3 2 Library lnitialization lssessesssssssssssseseseeee nennen nnne nn nnne nnn nnn nnns nnne nna rns na nnne aaaea 6 SR MES a Mu Nie EET S T Jok Backend Inen ACS nen ERE T gA Ty EN E sena a Be stale nee een E eE 9 34 BILACCESS FUNCIONS zensiert E E Ei is eaS reine 10 3 4 2 Register Access Functions use nen ande aset KU lade SEE 10 3 4 3 Miscellaneous FUNCHONG ui c
4. array element corresponds to one coil or input discrete Functions operating on input or holdings registers use arrays of uint16 t where each array element corresponds to one input or holding register Functions for reading data read coils read input discretes and read input registers are supposed to fill the array elements with the appropriate application specific values The first array element index 0 corresponds to the reference supplied as start ref The last array element index ref count corresponds to reference start ref ref count 1 Functions for writing data write coils write input discretes and write input registers are supposed to use the values from the array elements to write application specific data The user application should return MODBUS ERR ILLEGAL DATA ADDRESS if addresses outside of the application specific data model are requested If no errors occurred while processing the backend callback function MODBUS ERR OK has to be returned to cause 1ib modbus to send a positive reply When read exception status gets called the current status of the exception register 8 bit should be returned to the MODBUS server library using the uint8 t exception status pointer The function process pdu will be called for all MODBUS function codes not handled by the server library This allows the user application to handle additional application specific function codes In case the application doesn t want
5. asrrez peek duse cus dkn cr dird aa pudba nee een 11 LIB MODBUS PROGRAMMERS MANUAL DOC Seite 3 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG 1 About this Document 1 1 Purpose This document functions as manual for the software module lib modbus Release 1 0 The intended readership is Project Manager for review and release Software Engineer as input for the implementation and maintenance phase Software Engineer as input for the design and implementation of other modules Technical personnel as Installation Manual End User as User s Manual This document is compliant with the IBV documentation standards Familiarity with the C programming language the QNX Momentics development environment and the MODBUS protocol and data model is assumed 1 2 Terminology MODBUS Modbus is a communications protocol existing in multiple variants for communication over serial lines MODBUS ASCII and MODBUS RTU and over TCP IP networks MODBUS TCP 1 3 Acronyms IBV IBV Echtzeit und Embedded GmbH amp Co KG TCP Transmission Control Protocol RTU Remote Terminal Unit 1 4 References MBAP MODBUS APPLICATION PROTOCOL SPECIFICATION V1 1b MBTCPIP MODBUS MESSAGING ON TCP IP IMPLEMENTATION GUIDE V1 0b MBSER MODBUS over Serial Line Specification and Implementation Guide V1 02 LIB MODBUS PROGRAMMERS MANUAL DOC Seite 4 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG 2 Installation The
6. case of an error 3 3 1 Backend Interface The backend interface is declared in modbus server h The callback functions supplied in the backend interface structure have to be implemented by the user application They will be called by the server to retrieve data for client requests typedef struct _ backend interface int tread Collo uinte C Start rer Uulnte t bit array xmntlo t ref count ine write COIILS Turntlo t Start rer Uite Dit array Uxntlo t ref count lint read Input UIsOoretes Uintlo L start fer unte t DI t array urntlo t rer count Int read input register uinelo X start zer Uncle reg array ulnctlo t rel Count int read holding registers uintle start rer uintlo t reg array ulnele t ref count int WELCe holding regrsters qurntlo t Start rer intlo t req array une Le t fef count int read exception status inte C SxCeption Status e LIB MODBUS PROGRAMMERS MANUAL DOC Seite 7 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG iUt process Pdu uinte regusst Ulnt9 ut request lengthy uns i re eplv nee t reply lengthy Ent P LOOR 1 int unlock Os backend interface The backend interface functions closely follow the MODBUS data model according to MBAP References and reference counts are expressed as integer numbers between 0 and 65535 zero based Functions accessing coils or input discretes use arrays of uint8 t where each
7. client connection should be closed and reopened No automatic retransmission is performed e LIB MODBUS PROGRAMMERS MANUAL DOC Seite 9 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG 3 4 1 Bit Access Functions The following functions may be called by the user application to send MODBUS requests accessing bit quantities Int modbus read Coile struct _ Client connection connectlion XHt9 i glave Uinti E Starr Fer Uince Dit array lnele zei count ine Modbus read input discretes struct client Connection Connection Mens Slava DInEle Start zer Winte L DIE array UIDELO t ber count int modb s write coll struct client connection Connection uinte t slave uintlo E bit rer uints t bat value int modbus write multiple colls struct client connection connection ULES Slave ulnele start rer ons DL Dit array u nele t ret count Arrays of uint8 t are used to transfer data from the user application to the MODBUS library Each coil or input discrete corresponds to one array element with index 0 referencing the item specified by the start ref parameter The modbus write coil function operates on a single coil whose value is supplied as a single uint8 t argument 3 4 2 Register Access Functions The following functions may be called by the user application to send MODBUS requests accessing registers inc modbus read multiple rbregisters struct Client connection connection
8. d mask and an or mask as specified by the MODBUS standard The modbus read write registers function uses two arrays one to hold the values that should be written and one holding the values read from the server Two different count parameters exist to allow reading and writing arbitrary numbers of registers 3 4 3 Miscellaneous Functions int modbus read exception Status struct _ Client connection connecbplonm UnL C Slave INC status The modbus read exception status function allows a client to read a servers exception status register The exception register value is returned using the uint8 t Pointer status int modbus send pdu struct client connection connectios Uuints slave uinto request Uinto request length uinte t Frreply inte t reply dength The modbus read exception status function provides direct access to the MODBUS PDU interface implemented by lib modbus The request is transmitted as is and any data received is returned using the reply and reply length pointers The buffer space for the reply is allocated by the library and has to be freed by the user application once the reply has been processed In case of an error either communication or protocol error no reply is returned and the pointers are set to NULL LIB MODBUS PROGRAMMERS MANUAL DOC Seite 11 von 11
9. equired at the same time 3 2 Library Initialization Prior to calling any other library function the libraries initialization function should be called int modbus 2nic The function takes no arguments and returns MODBUS ERR OK on success e LIB MODBUS PROGRAMMERS MANUAL DOC Seite 6 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG 3 3 Server Interface The server interface consists of two functions Struct _ server modbus start server Int Type void server params backend Interface backend int modbus Stop Serveri istruct Server server To start a server the user application has to call modbus start server specifying the connection type only MODBUS CONNECTION TCP is implemented a set of parameters specific to the connection type and the backend interface used by the library to retrieve data for client requests The parameter set for TCP connections is a pointer to a structure of type modbus tcp params as declared in modbus common h It consists of a pointer to a C String specifying the IP address the server should bind itself to and a short integer specifying the TCP port the connection should listen at The IP address pointer may be NULL in which case the server will listen on all addresses assigned to the system typedet struct _ modbus tcp params char ups short port tcp params The modbus start server function returns a pointer to the newly created server on success or NULL in
10. gle connection could be used to access multiple clients Struct _ client connection modbus open Int type void Connection params int timeout ine Modbus Close struce client Connection OODDectionm s The parameters required by the modbus open function are the same as those required by the modbus start server function see 3 3 Server Interface for more information The additional timeout argument specifies the timeout for client requests in milliseconds The function will return a poiner to the newly created client connection on success or NULL in case an error occurred The returned pointer has to be used in all subsequent calls as a handle to identify the particular connection A connection should be closed using the modbus close function if the client connection isn t required anymore The connection pointer is invalid once the modbus close function returned and must not be used in subsequent calls to client request functions All functions for sending MODBUS requests to a MODBUS server take a pointer to the connection and a slave ID as an argument For MODBUS TCP requests the slave parameter is ignored and the corresponding field in the request is filled with OxFF Possible return values from client request functions are MODBUS ERR OK MODBUS ERR CONNECTION CLOSED MODBUS ERR COMMUNICATION FAILURE One of the MODBUS protocol error codes In case of a connection or communication error the corresponding
11. to handle a certain function code it should return MODBUS ERR ILLEGAL FUNCTION The request and request length arguments hold the MODBUS PDU as received by the server while reply and reply length are pointers to the location where the user application should store any results produced The memory for the reply buffer has to be allocated by the user application It will be freed by the server library once the reply has been sent The length of the reply buffer has to be returned using the reply length pointer The lock and unlock functions are called to ensure data consistency for the Read Write Multiple Registers and Mask Write Register function codes It is up to the user application to ensure that the data is held consistent between a lock and a subsequent unlock call In order to stop a previously started MODBUS server the user application has to call the modbus stop server function using the server pointer returned by the modbus start server function as an argument The pointer will be invalid once the modbus stop server function returned e LIB MODBUS PROGRAMMERS MANUAL DOC Seite 8 von 11 IBV ECHTZEIT UND EMBEDDED GMBH amp CO KG 3 4 Client Interface Two functions exist that allow the user application to open and close connections to clients In case of a MODBUS TCP connection an individual connection has to be opened for every client that should be accessed If MODBUS RTU support was to be implemented a sin
Download Pdf Manuals
Related Search