MBLogic
for an open world in automation
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:
- Client connections - This configures the client names, protocol type, address, polling rate, and other information.
- Client commands - This configures the client communications commands, including memory addresses, protocol functions, and other information.
- Fault Configuration - This configures the client communications fault indication, including the memory addresses where the fault information is stored.
- Comments - Comments may be included in the configuration file to assist in documenting the particular application configuration.
Configuration Syntax
The configuration syntax has the following general properties:
- Sections. Sections begin a series of related configuration values. A section name is an identifier which is enclosed by square brackets ("[ ]"). A section includes all items until the beginning of a new section, or until the end of the file. Section names must be unique and must not be duplicated in any other section. Duplicate section names are ignored.
- Configuration items. Any line following the beginning of a section is considered to be an item which belongs to that section (excluding comments). Configuration items are key/value pairs in the format "key=value".
- Each item must be on a separate line.
- Keys are separated from values by equal signs ("="). Because equal signs are used as key/value separators, they may not be used as part of any key or value.
- Parameters are case sensitive. All keys and values must be in the correct case. For example, "Main1", "main1", and "mAin1" are three different identifiers.
- All keys or values which are defined by the configuration syntax are always in lower case.
- User defined values may be in upper, lower, or mixed case.
- The ampersand ("&") character has special meaning. Certain sections are predefined by the configuration system. The names for these will start with an ampersand. User defined section names may not start with an ampersand. Command item names must start with an ampersand. Any item starting with an ampersand is assumed to be a command.
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:
- tcpserver
Protocols
The recognised protocols are:
- modbustcp - The Modbus/TCP protocol.
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:
- c - Client name. This is the name of the client (as defined in the section name).
- p - The generic interface server port number.
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:
- yes - Restart the client if it terminates unexpectedly.
- no - Do not restart the client if it terminates unexpectedly.
- nostart - Do not start the client at all.
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:
- coil - Coil addresses.
- inp - Discrete input addresses.
- holdingreg - Holding register addresses.
- inpreg - Input register addresses.
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.
- Several Modbus/TCP clients are started, each demonstrating a different configuration. These clients read and write the data table through the Modbus/TCP server (noted above).