TM-SP08-0001, Extended Modbus Slave Protocol Specification
TM-SP08-0001, Extended Modbus Slave Protocol Specification
TM-SP08-0001, Extended Modbus Slave Protocol Specification
Electronic I
Document type
Specifikation/Specification
Approved by Reg. No.
EPc-HK TM-SP08-0001
Issued by Date Issue Page
EPc-HK Håkan Kjellström 2017-07-13 12 1(42)
Fördelning/To För kännedom/Copy
TANKMASTER
This document replace the old document “TANKMASTER Extended Modbus Slave Protocol
Issue 1
Table of contents
1 DOCUMENT DEFINITION ..............................................................................4
1.1 Identification .......................................................................................................4
1.2 Difference to old protocol ...................................................................................4
1.2.1 Difference in FC02 Registers ..............................................................................4
1.2.2 Difference in FC03 Registers ..............................................................................5
1.2.3 Difference in FC06 and FC16 Registers .............................................................5
1.3 Revision history ..................................................................................................6
2 GENERAL ..........................................................................................................8
2.1 Introduction .........................................................................................................8
2.2 References ...........................................................................................................8
2.3 Definitions ...........................................................................................................9
3 ENVIRONMENT ...............................................................................................10
3.1 System .................................................................................................................10
3.2 Hardware .............................................................................................................10
3.3 Software ..............................................................................................................10
4 PROTOCOL........................................................................................................11
4.1 Introduction .........................................................................................................11
4.2 Message Description ...........................................................................................11
4.3 Slave Address ......................................................................................................11
4.4 Function Code .....................................................................................................11
4.5 Data Field ............................................................................................................12
4.6 CRC-16 ...............................................................................................................12
4.7 Inventory Registers .............................................................................................12
4.8 Tank Order ..........................................................................................................12
4.9 Property Settings .................................................................................................13
4.10 Units ....................................................................................................................14
4.11 Query Limitations ...............................................................................................15
5 FUNCTION CODE 02 READ INPUT STATUS ...............................................17
5.1 Introduction .........................................................................................................17
5.2 Query Format ......................................................................................................17
5.3 Response Format .................................................................................................17
5.4 Register Numbers ................................................................................................18
Issue 1
1 DOCUMENT DEFINITION
1.1 Identification
This document specifies the protocol for communication between a HOST computer and
TankMaster Modbus Slave Protocol Server, using the Modbus standard protocol defined in
document Modicon Modbus Protocol Reference Guide.
This document replace the old document “TANKMASTER Extended Modbus Slave Protocol
Specification” with reg. no WinOpi/SP-98.019.
It also replace TRL/2-95.110 that described the protocol between a HOST computer and TRL/2 OPI
for OS/2.
Document TRL/2-95.110 was tested with Honeywell TDC 3000 via EPLC Gateway.
See chapter below for differences between the new and old protocol.
Removed registers
Address (hex) Parameter Address (hex) Parameter
1E00 - 1EFF Current input 1 status 5100 – 51FF Current input 2 L alarm status
1F00 - 1FFF Current input 2 status 5200 – 52FF Current Input 2 Blocked
2700 – 27FF Frequency input 3 status 5300 – 53FF Current Input 2 Disconnect
2800 – 28FF Frequency input 2 status 5400 – 54FF Current input 3 H alarm status
2900 – 29FF Frequency input 1 status 5500 – 55FF Current input 3 L alarm status
Issue 1
2F00 - 2FFF Digital input status 5600 – 56FF Current Input 3 Blocked
4C00 – 4CFF Current input 1 H alarm 5700 – 57FF Current Input 3 Disconnect
status
Document template: R:\SME General\PM\RTR PM eng.dot
4D00 – 4DFF Current input 1 L alarm status 5800 – 58FF Current input 4 H alarm status
4E00 - 4EFF Current Input 1 Blocked 5900 – 59FF Current input 4 L alarm status
4F00 - 4FFF Current Input 1 Disconnect 5A00 – 5AFF Current Input 4 Blocked
5000 – 50FF Current input 2 H alarm 5B00 - 5BFF Current Input 4 Disconnect
status
Removed registers
Address (hex) Parameter Address (hex) Parameter
0200 – 02FF RTG Status 2800 – 28FF Frequency input 2
1A00 – 1AFF Temp block status 2900 – 29FF Frequency input 1
1B00 - 1BFF Temp error status 2C00 – 2CFF Digital input status
1D00 – 1DFF Current status 4200 – 42FF Current input 1 alarm status
1E00 - 1EFF Current input 1 4300 – 43FF Current input 2 alarm status
1F00 - 1FFF Current input 2 4400 – 44FF Current input 3 alarm status
2700 – 27FF Frequency input 3 4500 – 45FF Current input 4 alarm status
Removed registers
Address (hex) Parameter
1E00 - 1EFF Current input 1
1F00 - 1FFF Current input 2
Added registers
Address (hex) Parameter
0400 – 04FF Level
1C00 – 1CFF Average Temperature
2300 – 23FF Sediment & Water
2400 – 24FF Free Water Level
2500 – 25FF Pressure Liquid
2600 – 26FF Pressure Vapor
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
7 2007-12-28 / ESs-AB-R New code for servo command status C (motor limit) was added.
The code for “unknown” status was changed to 100 (before it
was 5).
Implemented in TM 4.H1 build7.
8 2008-01-28 / TT-TH Register old WinOpi/SP-98.019 doc as TM document.
9 2010-05-24 / EPc-HK Added Roof Tilt as FC02 and FC03 register.
Added Redundancy status as FC03 register, CR20445.
Added WIV as FC03 and FC04 register, CR20381
Added Set-Point alarm as FC02 and FC03 register, CR20383.
Review group: EPc-HK, TT-TH
10 2012-08-07 / ESs-AB-R Product support added for FC02 and FC03
11 2015-11-10 / ESs-AB-R FWL, VP, LP alarm statuses were added for FC02 and FC03
12 2017-08-07 / ESs-PK-R Vapor Temperature added for FC02, FC03, FC06 and FC16
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
2 GENERAL
2.1 Introduction
The communication between the HOST and the TankMaster is done on a standard RS-232C serial
link. The transmission mode is RTU, which means that all transferred data will be in binary. The
HOST computer will be the MASTER in the communication and requests data from the
TankMaster. TankMaster will be the SLAVE in the communication.
In RTU mode messages includes an error-checking field that is based on a CRC method. The CRC
field is two bytes and is added to the end of each message.
When a sensor failure or communication failure has occurred, then the value is unchanged.
The HOST must ask for sensor status.
E.g. if status for the level is set to error or to no response the value isn't changed.
2.2 References
1. Modicon Modbus Protocol Reference Guide, Modicon Inc. PI-MBUS-300 Rev. G
2. The Modbus Protocol applied to the TRL2 Communication TRL2-89.28 Issue 2
Systems
3 TRL/2 OPI Extended Modbus Host Protocol TRL/2-95.110 Issue 2
4 TankMaster Functional Specification WinOpi/SP-97.002 Issue 1
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
2.3 Definitions
EPLCG Enhanced Programmic Logic Computer Gateway ( Honeywell TDC 3000
gateway )
HOST Host Computer
TankMaster Tank interface programs, on a PC with Windows NT
RTU Remote Terminal Unit
CRC Cyclic Redundancy Check
DC Diagnostic Code
TRL2 TankRadar L/2
TRL2 Units DAU, FCU, OPI, RTG
FCU Field Connection Unit
RTG Radar Tank Gauge
DAU Data Acquisition Unit
Register Signed or unsigned word (2 byte).
Word Unsigned word, same size as a register (2 byte).
Unsigned word 16 bit unsigned integer (2 byte).
Signed word 16 bit signed integer (2 byte).
Unsigned double 32 bit unsigned integer (4 byte).
word
Signed double 32 bit signed integer (4 byte).
word
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
3 ENVIRONMENT
3.1 System
TankMaster
COM 3 COM 1
Other bus
TRL/2 bus
Other Units
TRL/2 Units
3.2 Hardware
Hardware Description
PC All TankMaster programs should run on the IBM PC and compatible
computers with Intel or compatible processors.
Hardware key (Dongle) A hardware key is connected to the TankMaster PC to enable functions,
which is not free of charge.
1. Slave protocol option must be enabled in the key.
Issue 1
3.3 Software
See ref[4].
4 PROTOCOL
4.1 Introduction
The communication between the HOST and the TankMaster will use a half-duplex link protocol. It
is a master / slave protocol where the TankMaster is the slave.
When the slave receives the query from the master it will process the query, when the query is
processed the slave will send the response to the master.
The function code in the message defines what actions are to be performed or what data is to be
transmitted. There are a number of different Modbus function codes, each one assigned to a specific
function. Only function codes 02, 03, 04, 06, 08 and 16 are supported. The rest of the functions will
be answered by exception code 1 (see page 37 below).
4.6 CRC-16
Contains the CRC-16 word, the high order byte is sent first. The high order byte is defined as the
MSB of the CRC calculation but is the lower part of the CRC-16 word (see page 35 below).
If the “WinView” option is enabled in the hardware key then the following inventory registers are
accessible (even if the “Inventory” option is disabled): Total Observed Volume, Weight in Vacuum
(mass) and Set-Point Alarms.
4.10 Units
The units of the supported protocol parameters are as shown in the table below.
lb/gal (US) 1/1000 lb/gal (US) Density as signed double word (FC04) or as
(Pound/gallon(US)) signed word (FC06).
m³/h 1/10 m³/h Flow rate as signed double word.
Document template: R:\SME General\PM\RTR PM eng.dot
1. If the HOST query for registers that not correspond to mapped tanks the system will respond
with exception 2 (illegal data address).
2. If the HOST query for registers and some of them correspond to mapped tanks and some of
them do not then the system will return zero (0) values for the registers that not correspond to
any tanks except for query FC02. Returned bit values for query FC02 registers not
corresponding to any tanks will be one (1) to indicate alarm or invalid data.
3. If FC03 or FC04 query requests registers corresponding to a parameter that have double word
format then first register number must be even. Number of queried registers must also be even
in this case.
4. Query FC06 and FC16 must specify registers corresponding to a mapped tank.
5. Queries with register range that crosses parameter boundary (e.g. queries with register range
3FE – 401) are not supported. Such queries will be answered with exception 2 (illegal data
address).
6. All queries for parameters sent to the server the first 5 seconds after start up will be return with
exception 6 (slave device busy). It is possible to monitor the server status with help of FC08
queries to determine when it is ready (see FC08 chapter for more information).
7. The first query for a parameter will return zero value (except for FC02 that will return value
one), even if the value is not actually zero. Subsequent queries (approx. 5 seconds after the first
query) will return valid data. The HOST can use the FC02 query to check if the data is valid.
The most common parameters are preloaded during start up to reduce the above delay.
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
The following table provides some examples (it is assumed that tank mapping table contains 3
entries):
Register
Function ModbusSlave Response Comments
range
FC02 404 – 410
Exception 2 (illegal data No queried registers correspond to
FC03 404 – 410
address) mapped tanks
FC04 406 – 410
FC02 402 – 406 Correct status bit for register 402
, 1 bits for registers 403 – 406
and 0 bits for 407- 409.
FC03 400 – 406 Level for 3 tanks(register 400 -
Only a part of queried registers
402) and zero values for
correspond to mapped tanks.
registers 403 – 406
FC04 404 – 407 GSV for the 3rd tank (registers
404, 405) and zero values for
registers 406 and 407
FC03 1–2 The parameter has double word
FC04 1–2 format. First register number must
be even.
Exception 2
FC03 2–4 The parameter has double word
FC04 2–4 format. Number of queried
registers must be even.
FC06 410 The register 410 doesn’t
Exception 2
correspond to a mapped tank.
FC16 402 – 406 All registers in FC16 must
Exception 2
correspond to mapped tanks.
FC02 3FE – 401
Register range crosses parameter
FC03 3FE – 401 Exception 2
boundary
FC04 3FE – 401
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
5.1 Introduction
The response data will be packed and the requested parameters are represented with one bit each.
The first bit in the low order byte in the response contains the addressed parameter, and the
remainder follows. For requested quantities that are not even multiples of eight, the last character
will be filled in with zeros at high order end.
Sensor data: a '0' means valid data, a '1' means invalid data.
Alarm data: a '0' means normal, a '1' means alarm.
See example chapter below.
…
n Last data byte
n+1 CRC (high byte)
n+2 CRC (low byte)
6.1 Introduction
The requested parameters below are represented with one or two registers.
7.1 Introduction
Each value in the response is divided into two registers for maximum resolution.
8.1 Introduction
This function is used to set a single data value for a tank in the TankMaster.
9.1 Introduction
This function is used to set a multiple data values for tanks in the TankMaster.
10.1 Introduction
Only sub function 0 and 2 will be answered. Exception code 7 will be returned for all other sub
functions.
11 REGISTER DECODING
11.1 Introduction
There are four alternatives of value representation:
6 1 Relay 4 on
7 1 Relay 4 off
8 1 Relay 1 failure
Document template: R:\SME General\PM\RTR PM eng.dot
9 1 Relay 2 failure
10 1 Relay 3 failure
11 1 Relay 4 failure
12 Not used
13 Not used
14 1 Sets if the device does not answer.
15 Not used
12 ERROR HANDLING
The resulting message including CRC, when divided by the same polynomial at the receiver will
give a zero remainder if no errors have occurred. The receiving unit recalculates the CRC and
compares it to the transmitted CRC. All arithmetic is performed modulo two (no carry).
An example of the CRC-16 error check is found in the Modicon Modbus Protocol reference guide.
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
When you append the CRC-16 check word to the message do it as follows:
Declarations:
MESSAGE (LENGHT) BYTE;
Code:
MESSAGE(LENGHT-2) = BYTE(CRC AND 0FF16); /* Low order */
MESSAGE(LENGHT-1) = BYTE(shr(CRC,8)); /* High order */
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
If not all of the requested memory addresses are valid, only the valid words are returned.
If no address is valid, exception code 2 is returned.
Issue 1
Document template: R:\SME General\PM\RTR PM eng.dot
13 EXAMPLE
13.1 Introduction
Below is an example of how the request from the HOST and the response from TankMaster will
look like.