MBLogic
for an open world in automation
Help - Hart Generic Client Protocol
Overview
The Hart generic client support is experiment at this time and is subject to change. This is currently a beta version.
HART
The Hart Foundation (www.hartcomm.org) generic client implements a single serial Hart Foundation master (this version does not consider a secondary master) that can read/write data to one up to 16 hart slaves, in a point-multipoint scheme (using a Bell202 serial Hart modem, connected to a RS232 port). Each slave can be polled by one or more commands.
The commands are sent sequentially (in alphabetical order), with a time spacing defined by ‘cmdtime’. When last command for the list is sent the client will wait ‘repeattime’ before starting the sequence again with the first command.
To optimize the use of the serial channel, when a command reaches a pre-defined quantity (5) of consecutive failed queries the client declares this command as “faulted” and retries are suspended for this command until a valid response is received and the command is returned to the normal (Ok) state.
The use of Bell202 serial Hart modems implies the mandatory use of hardware handshaking. Because of some limitations in the "pyserial" library used by this client, hardware handshaking is implemented using timing calculations. In some cases, this could cause some desynchronization in sending / receiving messages.
The client makes the proper conversion for the exchange of data (for example, a “0” binary coil converts to “0” in a input register, and an non-zero value in a holding register converts to “1” in an input status), either between the client and the MBLogic server, or between the client and the slaves (field devices).
The implementation covers the following files (contained in /genclient directory):
- hartclient.py
- hartconfig.py
- hartmsg.py
This generic client has been tested with a Hart Foundation emulator (FrameAlyst v7.0) and a Rosemount Hart Digital Transmitter with Rev 5 Universal Commands.
Standard Parameters
The following are the standard generic client parameters for this generic client.
| Item | Value | Description |
|---|---|---|
| protocol | hart | Selects hart protocol |
| type | genericclient | Selects genericclient |
| clientfile | hartclient.py -d 1 | Specifies the name of the file used to implement the client. The parameter "-d" will specify a start-up delay in seconds. |
Example:
type = genericclient protocol = hart clientfile = hartclient.py -d 1
Client Parameters
| Item | Description | Valid Values |
|---|---|---|
| serialport | The serial port to use. This must be a valid serial port name. E.g. "/dev/ttyS0". | See "serial port names" below. |
| statisticstable | Command's statistical table index/offset (inside inpreg group of writetable). | An integer between 0 and the maximum size of the input registers for "writetable" |
| cmdtime | This is the delay time in milli-seconds between commands. | An integer greater than or equal to 0. |
| repeattime | This is the delay time in milli-seconds between repeating sets of commands. | An integer greater than or equal to 0. |
| retrytime | This is the delay time in milli-seconds between retrying commands in the event of an error. | An integer greater than or equal to 0. |
| retries | Maximum number of consecurtive command retries to allow. | An integer greater than or equal to 0. |
Example:
serialport = /dev/ttyS1 statisticstable = 60 cmdtime = 500 repeattime = 1000 retrytime = 1000 retries = 0
Commands
| Item | Description | Valid Values |
|---|---|---|
| action | The command action. If ‘disabled’, the command will not be executed. For ‘oneshot’ action, if the current command is ‘Read’ type send the command until one successful response (valid or not) from field device (slave) is received. If the current command is ‘Write’ type send the command only if data to write has changed since last succesfully query. For ‘poll’ action, send the command in the normal sequence. | poll, oneshot, disabled |
| uid | The HART unit id. | 0 to 15 |
| function | The HART function code. Functions 0, 1, 2 and 3 write the data received from the slaves to the ‘Data Table Write Addresses’. | 0, 1, 2, 3 |
| datatype | The host system data table. | coil, inp, holdingreg, inpreg |
| dataoffset | Data offset index. | Greater than or equal to 0. Must be less than the maximum address transferred for the selected datatype. |
Example:
&readprimaryvar = action=poll, uid=0, function=1, datatype=inpreg, dataoffset=0 &readuniqueid = action=poll, uid=0, function=0, datatype=holdingreg, dataoffset=10 &readallvar = action=oneshot, uid=0, function=3, datatype=inpreg, dataoffset=10 &readcurrentrange = action=poll, uid=0, function=2, datatype=holdingreg, dataoffset=0
Serial Port Names
Serial ports must use the naming conventions defined by pyserial python library (http://pyserial.sourceforge.net)
For either Linux or MS Windows, serial ports may be named as:
- 0 is the first serial port
- 1 is the second serial port
- etc.
For Linux, it is also possible to use standard tty names:
- /dev/tty0 is the first serial port
- /dev/tty1 is the second serial port
- /dev/ttyUSB0 is the first serial port (using an USB-Serial Port adapter)
- etc.
Example:
serialport=/dev/ttyS0 serialport=1
Statistics
Each generic client has a additional statistic table, where results of each command are summarized. This table is contained into the “Input Register” section of “Data Table Write Addresses”, and its use is mandatory, so this section must have at least (Qty of Commands * 10) addresses. For example, if a generic client has 3 commands and must return 8 Input Registers of field data to the server, the size of “Input Register” must be at least 38 (3*10 + 8) .
Collection of statistics begins when the generic client starts and can not be reset (in this version).
The client alphabetically sorts all commands defined in the client configuration file, and the statistics of all commands are showed consecutively following that order. Each command has 10 registers whose function is described below:
| Offset | Description |
|---|---|
| 0 | Result of last query/poll. Value is 1 if Ok, or 0 if an error is present. |
| 1 | Total number of queries. |
| 2 | Total number of valid queries. |
| 3 | Total number of invalid queries. |
| 4 | Total number of frame errors. |
| 5 | Total number of command time-outs. |
| 6 | Total number of times a command was retried. |
| 7 | Command efficieny, calculated as: (valid queries) * 100 / (total queries). |
| 8 | Spare, reserved for future use. |
| 9 | Spare, reserved for future use. |