MODBUS application protocol specification

MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 1/45 8May02 Content 1 Introduction .......................................................................... 2 1.1 Scope of this document .......................................................... 2 1.2 References ............................................................................. 2 2 Abbreviations ....................................................................... 3 3 Context................................................................................. 3 4 General description .............................................................. 5 4.1 Protocol description................................................................ 5 4.2 Data Encoding........................................................................ 7 4.3 MODBUS data model ............................................................. 7 4.4 Define MODBUS Transaction ................................................. 9 5 Function Code Categories .................................................. 11 5.1 Public Function Code Definition .............................................12 6 Function codes descripitons................................................ 12 6.1 01 (0x01) Read Coils .............................................................12 6.2 02 (0x02) Read Discrete Inputs..............................................14 6.3 03 (0x03) Read Holding Registers .........................................17 6.4 04 (0x04) Read Input Registers .............................................18 6.5 05 (0x05) Write Single Coil ....................................................20 6.6 06 (0x06) Write Single Register .............................................22 6.7 15 (0x0F) Write Multiple Coils................................................25 6.8 16 (0x10) Write Multiple registers ..........................................28 6.9 20 (0x14) Read File Record ...................................................29 6.10 22 (0x16) Mask Write Register ...........................................34 6.11 23 (0x17) Read/Write Multiple registers..............................35 6.12 43 (0x2B) Read Device Identification..................................38 7 MODBUS Exception Responses......................................... 43 modbus.org http://www.modbus.org/ 2/45 8May02 1 Introduction 1.1 Scope of this document MODBUS is an application layer messaging protocol, positioned at level 7 of the OSI model, that provides client/server communication between devices connected on different types of buses or networks. The industry’s serial de facto standard since 1979, Modbus continues to enable millions of automation devices to communicate. Today, support for the simple and elegant structure of MODBUS continues to grow. The Internet community can access MODBUS at a reserved system port 502 on the TCP/IP stack. MODBUS is a request/reply protocol and offers services specified by function codes. MODBUS function codes are elements of MODBUS request/reply PDUs. The objective of this document is to describe the function codes used within the framework of MODBUS transactions. 1.2 References 1. RFC 791, Internet Protocol, Sep81 DARPA 2. MODBUS Protocol Reference Guide Rev J, MODICON, June 1996, doc # PI_MBUS_300 MODBUS is an application layer messaging protocol for client/server communication between devices connected on different types of buses or networks. It is currently implemented using: Ÿ TCP/IP over Ethernet. Ÿ Asynchronous serial transmission over a variety of media (wire : EIA/TIA-232-E, EIA-422, EIA/TIA-485-A; fiber, radio, etc.) Ÿ MODBUS PLUS, a high speed token passing network. TCP Modbus on TCP MODBUS APPLICATION LAYER IP Ethernet Physical layer Ethernet II /802.3 EIA/TIA-232 or EIA/TIA-485 Master / Slave Physical layer MODBUS+ / HDLC Other Other Figure 1: MODBUS communication stack MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 3/45 8May02 2 Abbreviations ADU Application Data Unit HDLC High level Data Link Control HMI Human Machine Interface IETF Internet Engineering Task Force I/O Input/Output IP Internet Protocol MAC Medium Access Control MB MODBUS Protocol MBAP MODBUS Application Protocol PDU Protocol Data Unit PLC Programmable Logic Controller TCP Transport Control Protocol 3 Context The MODBUS protocol allows an easy communication within all types of network architectures. PLC PLCHMI I/ O I/ O I/ ODrive MODBUS ON TCP/IP Gateway Gateway Gateway M O D B U S O N M B + M O D B U S O N R S 23 2 M O D B U S O N R S 48 5 Device HMI PLC PLC Drive I/ O I/ O I/ O I/ O Device MODBUS COMMUNICATION Figure 2: Example of MODBUS Network Architecture Every type of devices (PLC, HMI, Control Panel, Driver, Motion control, I/O Device… ) can use MODBUS protocol to initiate a remote operation. MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 4/45 8May02 The same communication can be done as well on serial line as on an Ethernet TCP/IP networks. Some gateway allows a communication between several types of buses or network using the MODBUS protocol. MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 5/45 8May02 4 General description 4.1 Protocol description The MODBUS protocol defined a simple protocol data unit (PDU) independent of the underlying communication layers. The mapping of MODBUS protocol on specific buses or network can introduce some additional fields on the application data unit (ADU). Additional address Function code Data Error check ADU PDU Figure 3: General MODBUS frame The MODBUS application data unit is built by the client that initiates a MODBUS transaction. The function indicates to the server what kind of action to perform. The MODBUS application protocol establishes the format of a request initiated by a client. The function code field of a MODBUS data unit is coded in one byte. Valid codes are in the range of 1 ... 255 decimal (128 – 255 reserved for exception responses). When a message is sent from a Client to a Server device the function code field tells the server what kind of action to perform. Sub-function codes are added to some function codes to define multiple actions. The data field of messages sent from a client to server devices contains additional information that the server uses to take the action defined by the function code. This can include items like discrete and register addresses, the quantity of items to be handled, and the count of actual data bytes in the field. The data field may be nonexistent (of zero length) in certain kinds request, in this case the server does not require any additional information. The function code alone specifies the action. If no error occurs related to the MODBUS function requested in a properly received MODBUS ADU the data field of a response from a server to a client contains the data requested. If an error related to the MODBUS function requested occurs, the field contains an exception code that the server application can use to determine the next action to be taken. For example a client can read the ON / OFF states of a group of discrete outputs or inputs or it can read/write the data contents of a group of registers. When the server responds to the client, it uses the function code field to indicate either a normal (error-free) response or that some kind of error occurred (called an exception response). For a normal response, the server simply echoes the original function code. Function code Data Request Client Server Initiate request Perform the action Initiate the response Receive the response Function code Data Response MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 6/45 8May02 Figure 4: MODBUS transaction (error free) For an exception response, the server returns a code that is equivalent to the original function code with its most significant bit set to logic 1. Function code Data Request Client Server Initiate request Error detected in the action Initiate an error Receive the response Error code Exception code Figure 5: MODBUS transaction (exception response) F Note: It is desirable to manage a time out in order not to indefinitely wait for an answer which will perhaps never arrive. The size of the Modbus PDU is limited by the size constraint inherited from the first Modbus implementation on Serial Line network (max. RS485 ADU = 256 bytes). Therefore, MODBUS PDU for serial line communication = 256 - Server adress (1 byte) - CRC (2 bytes) = 253 bytes. Consequently : RS232 / RS485 ADU = 253 bytes + Server adress (1 byte) + CRC (2 bytes) = 256 bytes. TCP MODBUS ADU = 249 bytes + MBAP (7 bytes) = 256 bytes . The MODBUS protocol defines three PDUs. They are : · MODBUS Request PDU, mb_req_pdu · MODBUS Response PDU, mb_rsp_pdu · MODBUS Exception Response PDU, mb_excep_rsp_pdu The mb_req_pdu is defined : mb_req_pdu = { function_code, request_data), where function_code - [1 byte] MODBUS function code request_data - [n bytes] This field is function code dependent and usually contains information such as variable references, variable counts, data offsets, sub-function codes etc. The mb_rsp_pdu is defined : MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 7/45 8May02 mb_rsp_pdu = { function_code, response_data), where function_code - [1 byte] MODBUS function code response_data - [n bytes] This field is function code dependent and usually contains information such as variable references, variable counts, data offsets, sub-function codes, etc. The mb_excep_rsp_pdu is defined : mb_excep_rsp_pdu = { function_code, request_data), where function_code - [1 byte] MODBUS function code + 0x80 exception_code - [1 byte] MODBUS Exception Code Defined in table below. 4.2 Data Encoding · MODBUS uses a ‘big-Endian’ representation for addresses and data items. This means that when a numerical quantity larger than a single byte is transmitted, the most significant byte is sent first. So for example Register size value 16 - bits 0x1234 the first byte sent is 0x12 then 0x34 F Note: For more details, see [1] . 4.3 MODBUS data model MODBUS bases its data model on a series of tables that have distinguishing characteristics. The four primary tables are: Primary tables Object type Type of access Comments Discretes Input Single bit Read-Only This type of data can be provided by an I/O system. Coils Single bit Read-Write This type of data can be alterable by an application program. Input Registers 16-bit word Read-Only This type of data can be provided by an I/O system Holding Registers 16-bit word Read-Write This type of data can be alterable by an application program. The distinctions between inputs and outputs, and between bit-addressable and word-addressable data items, do not imply any application behavior. It is perfectly acceptable, and very common, to regard all four tables as overlaying one another, if this is the most natural interpretation on the target machine in question. For each of the primary tables, the protocol allows individual selection of 65536 data items, and the operations of read or write of those items are designed to span multiple consecutive data items up to a data size limit which is dependent on the transaction function code. It’s obvious that all the data handled via MODBUS (bits, registers) must be located in device application memory. But physical address in memory should not be confused with data reference. The only requirement is to link data reference with physical address. MODBUS logical reference number, which are used in MODBUS functions, are unsigned integer indices starting at zero. MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 8/45 8May02 · Implementation examples of MODBUS model The examples below show two ways of organizing the data in device. There are different organizations possible, all are not described in this document. Each device can have its own organization of the data according to its application Example 1 : Device having 4 separate blocks The example below shows data organization in a device having digital and analog, inputs and outputs. Each block is separate from each other, because data from different block have no correlation. Each block is thus accessible with different MODBUS functions. Input Discrete MODBUS access Device application memory MODBUS SERVER DEVICE MODBUS RequestCoils Input Registers Holding Registers Figure 6 MODBUS Data Model with separate block Example 2: Device having only 1 block In this example, the device have only 1 data block. A same data can be reached via several MODBUS functions, either via a 16 bits access or via an access bit. Device application memory MODBUS SERVER DEVICE MODBUS Request Input Discrete MODBUS access Coils Input Registers Holding Registers R W R W Figure 7 MODBUS Data Model with only 1 block MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 9/45 8May02 4.4 Define MODBUS Transaction The following state diagram describes the generic processing of a MODBUS transaction in server side. Validate function code Validate data value ExceptionCode_3 Wait for a MB indication ExceptionCode_2 ExeptionCode_1 Send Modbus Exception Response ExceptionCode_4_5_6 Execute MB function Send Modbus Response Validate data Address ExceptionCode_3 ExceptionCode_2 ExeptionCode_1 ExceptionCode_4_5_6 [Invalid] [Invalid] [Invalid] [valid] [Invalid] [Valid] [valid] [Valid] [Receive MB indication] Figure 8 MODBUS Transaction state diagram Once the request has been processed by a server, a MODBUS response using the adequate MODBUS server transaction is built. Depending on the result of the processing two types of response can be built : § A positive MODBUS response : MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 10/45 8May02 § the response function code = the request function code § A MODBUS Exception response ( see chapter 6.14): § the objective is to provide to the client relevant information concerning the error detected during the processing ; § the response function code = the request function code + 0x80 ; § an exception code is provided to indicate the reason of the error. MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 11/45 8May02 5 Function Code Categories There are three categories of MODBUS Functions codes. They are : Public Function Codes · Are well defined function codes , · guaranteed to be unique, · validated by the modbus.org community, · publically documented · have available conformance test, · are documented in the MB IETF RFC, · includes both defined public assigned function codes as well as unassigned function codes reserved for future use. User-Defined Function Codes · there is a defined two ranges of user-defined function codes, ie 65 to 72 and from 100 to 110 decimal. · user can select and implement a function code without any approval from modbus.org · there is no guarantee that the use of the selected function code will be unique · if the user wants to re-position the functionality as a public function code, he must initiate an RFC to introduce the change into the public category and to have a new public function code assigned. Reserved Function Codes · Function Codes currently used by some companies for legacy products and that are not available for public use. User Defined Function codes 1 65 100 110 72 User Defined Function codes PUBLIC function codes PUBLIC function codes PUBLIC function codes 127 Figure 9 MODBUS Function Code Categories MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 12/45 8May02 5.1 Public Function Code Definition Function Codes code Sub code (hex) Page Physical Discrete Inputs Read Input Discrete 02 02 11 Read Coils 01 01 10 Write Single Coil 05 05 16 Write Multiple Coils 15 0F 37 Bit access Internal Bits Or Physical coils Physical Input Registers Read Input Register 04 04 14 Read Multiple Registers 03 03 13 Write Single Register 06 06 17 Write Multiple Registers 16 10 39 Read/Write Multiple Registers 23 17 47 Mask Write Register 22 16 46 16 bits access Internal Registers Or Physical Output Registers Read File record 20 6 14 42 Data Access File record access Write File record 21 6 15 44 Encapsulated Interface Read Device Identification 43 14 2B 6 Function codes descripitons 6.1 01 (0x01) Read Coils This function code is used to read from 1 to 2000 contiguous status of coils in a remote device. The Request PDU specifies the starting address, ie the address of the first coil specified, and the number of coils. Coils are addressed starting at zero. Therefore coils 1-16 are addressed as 0-15. The coils in the response message are packed as one coil per bit of the data field. Status is indicated as 1= ON and 0= OFF. The LSB of the first data byte contains the output addressed in the query. The other coils follow toward the high order end of this byte, and from low order to high order in subsequent bytes. If the returned output quantity is not a multiple of eight, the remaining bits in the final data byte will be padded with zeros (toward the high order end of the byte). The Byte Count field specifies the quantity of complete bytes of data. Request PDU Function code 1 Byte 0x01 Starting Address 2 Bytes 0x0000 to 0xFFFF Quantity of coils 2 Bytes 1 to 2000 (0x7D0) Response PDU Function code 1 Byte 0x01 MODBUS Application Protocol Specification MODBUS.ORG modbus.org http://www.modbus.org/ 13/45 8May02 Byte count 1 Byte N* Coil Status n Byte n = N or N+1 *N = Quantity of Outputs / 8, if the remainder is different of 0 Þ N = N+1 Error