Get MBLogic at SourceForge.net. Fast, secure and Free Open Source 
	software downloads

Help Topics

Topic Details for Communications

Help - Client Communications Configuration


Overview

Clients configurations are saved in a text file called "mbclient.config". This configuration file is read on start up of the software and used to determine what protocols to enable, what network addresses and ports to use, what data to read or write, etc. This file must be edited in order to configure a system for every individual application.


Configuration Overview

Editing a Configuration

There is one, and only one client communications configuration file for each system. This file is in ASCII text format and may be edited with any standard text editor. If you use a word processor, be sure to save in a plain text mode which does not insert formatting characters into the text.

Configuration Elements

A client communications configuration file contains the following elements:

Configuration Syntax

The configuration syntax has the following general properties:

Comments

Any line beginning with a '#' character is considered to be a comment and is ignored. Comments must begin at the start of a line, and may not be on the same line as any other valid input.

Example


	# 16-Apr-2008. This is a comment.
	# This is also a comment.


TCP Client Connections

TCP Client connections define the connection parameters to an external server (e.g. an I/O module, valve bank, or RTU). Each client connection executes independently of (is not synchronised with) any other client connect.

Configuration Items

Item Description
The section name. This is used as the name of the client. This name is used to identify the client in the status monitoring system and will appear on the status web pages.
type This is the protocol type and is used to determing the communications method used. This must be one of the recognised protocol types (listed below).
protocol This determines the protocol recognised by the client. This must be one of the recognised protocols (listed below).
host The IP address of the server the client is polling. If the server is on the same PC, 'localhost' is also a valid address.
port The IP port being polled.
action Must always be "poll" at this time.
cmdtime The time delay in milliseconds between execution of consecutive commands.
repeattime The time delay in milliseconds between executing the last command and beginning the set of commands again.
retrytime The maximum time in milliseconds to wait for a reply to a command. If no reply is received, the next command is attempted.
fault_inp, fault_coil, fault_inpreg, fault_holdingreg The data table addresses to use for indicating faults. These must be valid data table addresses. Faults are discussed in more detail below.
fault_reset The data table address to use for resetting faults. This must be a valid coil address. Faults are discussed in more detail below.
commands These are instructions which the client uses to poll the remote server addresses. Commands are discussed in more detail below. There may be any number of client commands.

Example


	[Module002]
	type=tcpclient 
	protocol=modbustcp 
	host=localhost
	port=8502 
	action=poll 
	cmdtime=050 
	repeattime=050 
	retrytime=5000 
	fault_inp=10002 
	fault_coil=10002 
	fault_inpreg=10002 
	fault_holdingreg=10002 
	fault_reset=65281 
	&command1= function=2, remoteaddr=1, qty=1, memaddr=1002, uid=2
	&command2= function=3, remoteaddr=1, qty=4, memaddr=5000 

The items may appear in any order.

Types

The recognised types are:

Protocols

The recognised protocols are:

Commands

Client commands are the actions to be executed for each client connection. Commands within a connection are executed consecutively. There is however no guarranty as to the order in which they are executed, and they are not synchronised with commands for other clients.

Client commands are part of the section they are associated with and must be defined as part of that section. The recognised commands parameters are:

Command Element Description
The command name. This is used as the key to the item. This name is used to identify the command in the status monitoring system and will appear on the status web pages. The command name must start with an ampersand. No two commands may have the same name in the same client connection (section). If they do, all but one will be ignored. However, it is permitted to use the same name in other client sections, provided that it appears no more than once in the same section. The names may be any combination of upper and lower case and may be descriptive (e.g. "Valves").
function The client protocol code or name. For Modbus, this is the Modbus function code.
remoteaddr The memory address at the server being polled.
qty The number of consecutive addresses being polled. For protocol functions which do not require a quantity, this parameter must be present and a valid number, although the value will not necessarily be used.
memaddr The memory address in the local data table which is being read or written to.
uid The unit ID to be sent with the message. This is optional, and if this parameter is left out a default unit ID of 1 is used. Each command may specify a differnt unit ID independently of any other command. This parameter is optional, but good practice would be to include it even if the value does not differ from the default.

Example


	&command1= function=2, remoteaddr=1, qty=1, memaddr=1002

	&command1= function=2, remoteaddr=1, qty=1, memaddr=97345, uid=2

The command name must be the first element in the line. Other parameters may appear in any order. All parameters associated with a single command must appear on the same line.


Generic Clients

Generic clients permit adding new clients to the system without making them a permanent part of the software. This is accomplished by running the generic client as a separate process (program) and having it commmunicate with the main system via a special protocol. Generic clients are primarily intended to make integrating serial protocols (including custom protocols) into the main system easier. but they are not restricted to serial communications, nor indeed are they restricted to communications at all.

Generic client support is still experimental and subject to change in future.

Configuration Items

Item Description
The section name This is used as the name of the client. This name is used to identify the client in the status monitoring system and will appear on the status web pages. This also acts to identify the generic client to the server when the client contacts it.
type Must be "genericclient"
protocol This determines the protocol information is displayed on the status interface. This may be any value.
clientfile This is the file name for the generic client. It may also include additional command line parameters which are to be passed to the client on start.
restartonfail This defines the restart characteristics to be used if the client fails (dies or crashes) during operation.
action Must always be "poll" at this time.
readtable This is the list of addresses to be read from the server and passed to the generic client. Details are described below.
writetable This is the list of addresses to be read from the client and passed to the server. Details are described below.
fault_inp, fault_coil, fault_inpreg, fault_holdingreg The data table addresses to use for indicating faults. These must be valid data table addresses. Faults are discussed in more detail below.
fault_reset The data table address to use for resetting faults. This must be a valid coil address. Faults are discussed in more detail below.
commands These are instructions which the client uses to poll the remote server addresses. Commands are discussed in more detail below. There may be any number of client commands.

Client File Name

The file name of the generic client is specified by the "clientfile" parameter. This must be a valid Python program file. The system will explicitly call the Python interpreter to execute the file.

The file name parameter can include additional command line parameters. These parameters will be passed to the client at start up.

However, the system has parameters of its own which it passes to the client, and any user defined parameters must not interfere with these. These system parameters are:

Restart Characteristics

If a generic client unexpectedly exits ("dies") while running, it can be automatically restarted by setting the appropriate option for "restartonfail". The restart options are as follows:

The system monitors configured clients to see if they are running. This check takes place at approximately 1 second intervals. If "restartonfail" is set to "yes", and if the client terminates unexpectedly, the system will attempt to restart it immediately at the next check interval. The system will attempt to restart the client up to 5 times. If the maximum number of restart attempts is exceeded, the system will cease trying to restart that client. If the client was successfully restarted, the restart counter is reset. This means a client can be automatically restarted as many times as necessary, provided the number of consecutive unsuccessful attempts is not exceeded.

Data Table Read and Write Addresses

A generic client communicates with the main server by copying a selected part of the data table to and from the server. The "readtable" item specifies the addresses to be read from the server and copied to the generic client. The "writetable" item specifies the addresses to be read from the generic client and copied to the main server. They are specified in the format: "<type>=<address>:<length>". The address types may be the following:

The addresses may be any valid address for each type. The lengths may be any length which does not result in attempting to read or write beyond the end of the data table. These parameters are not limited by Modbus protocol read or write specifications. Any type may be read from or written to. Any quantity may be transferred at once. However, excessively large data transfers may cause problems with system performance.

In addition to the above types, the type of "none" is also valid. This may be used as a placeholder to specify that no data transfer is requested for that item. Some examples are:


	# Do not read any addresses
	readtable= none
	# Write 10 coils starting at 9100, and 4 holding registers starting at 9650
	writetable= coil=9100:10, holdingreg=9650:4

	# Read and write all types.
	readtable= coil=9100:10, inp=9100:11, holdingreg=9650:4, inpreg=10000:1
	writetable= coil=900:10, inp=900:1, holdingreg=62050:150, inpreg=2:99

Client Configuration Items

Any parameters which are not recognised by the server as standard generic client items, and which are not commands are passed to the generic client as is. This allows a generic client to define their own parameters as required for the application.

Commands

Client commands are the actions to be executed for each client connection. Commands within a connection are executed consecutively. Commands for generic clients are defined by the application and need not be present. The server however will parse them from the parameter set for convenience. The generic client is responsible for validating the command parameters.

Example


	# This is used to help demonstrate the generic client.
	[CasClient]
	type=genericclient
	protocol=cascadas
	clientfile=casclient.py -d 1
	restartonfail=yes
	cmdtime=750
	repeattime=1250
	retrytime=5000
	action=poll
	readtable= none
	writetable= coil=9100:10, holdingreg=9650:4
	fault_inp=10020
	fault_coil=10020
	fault_inpreg=10020
	fault_holdingreg=10020
	fault_reset=65293
	&cmd1= PL1, PL2, PL3, PL4, Tank1Level


Fault Configuration

Fault configurations are the memory addresses where communications faults which are detected by each client are indicated. There must be only one fault configuration per client.

Configuration Items

Item Description
fault_inp When a fault is detected, this discrete input will be turned on.
fault_coil When a fault is detected, this coil will be turned on.
fault_inpreg When a fault is detected, this input register will be set to a non-zero value. The value will be protocol dependent and may indicate the type of fault.
fault_holdingreg When a fault is detected, this input register will be set to a non-zero value. The value will be protocol dependent and may indicate the type of fault.
fault_reset When this coil address is turned on, the fault indication bits and registers are reset to "0", and this coil is turned off. Only the highest (last) 256 coils may be used as fault reset coils. If a lower address is selected no error will be indicated, but the coil will not be monitored to reset the fault indicating registers or bits.

Example


	fault_inp=256 
	fault_coil=97 
	fault_inpreg=10000 
	fault_holdingreg=52000 
	fault_reset=65281

Additional Notes

The items may appear in any order.

Fault configurations are part of the section they are associated with and must be defined as part of that section. All of the fault configuration items must appear with each client.

The fault reset coils are scanned once every several seconds. It therefore may take several (e.g. 2 or 3) seconds for the faults to reset once the reset coil is activated.

All four indicating parameters (inp, coil, inpreg, holdingreg) are equivalent in that all are turned on together in the event of any fault. This means that any one of these may be read to determine the presence of a fault. It is suggested that addresses be chosen to allow them to be read as part of the same read operation as other normal data.


Complete Example

The following is an example showing a complete configuration file.

Example


	# Client connections.
	# This "loops back" into the server. You don't really want to do this. 
	[Module000] 
	type=tcpclient 
	protocol=modbustcp 
	host=localhost 
	port=8502 
	action=poll 
	cmdtime=050 
	repeattime=75 
	retrytime=5000
	fault_inp=15 
	fault_coil=15 
	fault_inpreg=10096 
	fault_holdingreg=10096 
	fault_reset=65280
	&command1=function=1, remoteaddr=0, qty=15, memaddr=0
	
	# This is another client connection.
	[Module001] 
	type=tcpclient 
	protocol=modbustcp 
	host=192.168.5.100 
	port=502 
	action=poll 
	cmdtime=040 
	repeattime=59 
	retrytime=5000
	fault_inp=32 
	fault_coil=32 
	fault_inpreg=10097 
	fault_holdingreg=10097 
	fault_reset=65281
	&Sensor1=function=2, remoteaddr=0, qty=16, memaddr=16
	&PushButtons=function=1, remoteaddr=0, qty=16, memaddr=16
	&PressForce=function=3, remoteaddr=0, qty=2, memaddr=5000
	&PumpStatus=function=4, remoteaddr=0, qty=4, memaddr=200
	&ValueBank=function=4, remoteaddr=8192, qty=120, memaddr=32768
	&DoorSwitches=function=15, remoteaddr=8192, qty=48, memaddr=61000
	&Beacon=function=6, remoteaddr=39, qty=1, memaddr=62000

	# This is an example of a generic client.
	[HartClient]
	protocol = hart
	type = genericclient
	serialport = /dev/ttyS1
	clientfile = hartclient.py -d 1
	restartonfail = yes
	action = poll
	cmdtime = 500
	repeattime = 1000
	retrytime = 1000
	fault_coil = 12500
	fault_inp = 12500
	fault_holdingreg = 12500
	fault_inpreg = 12500
	fault_reset = 65297
	readtable = coil=0:0, holdingreg=0:0, inp=0:0, inpreg=0:0
	writetable = coil=11500:20, holdingreg=11500:25, inp=11500:125, inpreg=11500:100
	retries = 0
	statisticstable = 60
	&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


Loop Back Sample

The sample configuration file supplied with the system uses what is referred to as a "loop-back" configuration for the clients. That is, a set of Modbus/TCP clients are configured to poll the system's own Modbus/TCP server. This is not in itself a useful feature. It is provided mainly to demonstrate the communications features. A different configuration should be created for a practical application. The sample configuration demonstrates the following features.