TRIUMF Device and Driver Support for Modbus/TCP Protocol under EPICS
Rolf Keitel, updated 2005-08-24
Version 2.21 24-Aug-2005
|
bug-fix in mbbodirectRecord initialization
|
Version 2.2 09-Dec-2004
|
improve error checking on connect time-out
|
Version 2.11 31-Mar-2004
|
default reconnect behaviour changed to "reconnect"
|
| Version 2.1 08-Feb-2004 |
reconnect behaviour is now configurable
keep-alive function for Momentum series PLCs
|
| Version 2.0 15-Dec-2003 |
added support for bipolar ADCs and DACs |
In case of discrepancies between this documentation and documentation
in the source code, the source code is (probably) more correct.
Download from here
Table of Contents
Functionality
Interface Functions
Connection Failures
TRIUMF's way to avoid stale PLC data
Limitations and Known Problems
NSLS port to support WAGO PLCs on Linux
Combined Linix/VxWorks version with support for Modicon, Wago, and Siemens S5 Fetch/write (Beta - use at your own risk)
The TRIUMF modtcp driver allows reading of data from Modicon PLCs and
writing of data to Modicon PLCs over Ethernet. It uses the Modbus/TCP
protocol.
This device/driver support is used in the ISAC control system with
Quantum and Momentum series PLCs.
Functionality:
- modtcp supports communications to more than one PLC out of
one IOC.
- reading data from PLC:
A background task (one per PLC) reads groups of data from the PLC
into an IOC memory buffer. Data are read in groups of up to 125
registers.
- writing data to PLC:
A background tasks (one per PLC) writes changed data from the IOC
memory buffer to the PLC. Data transfer is not optimized, data are
written one register per ethernet message.
- an [optional] watchdog task (one per PLC) can be used to set
INVALID alarms on records, if the IOC <--> PLC communication is
interrupted.
- the driver recovers from Ethernet interruptions or disconnects
*** change in Version of 8-Feb-2004:
see section "Connection Failures" below
- EPICS record support:
- bi, bo
- mbbi, mbbo
- mbbiDirect, mbboDirect
- ai, ao
- for ai and ao records, both unipolar and bipolar (2's complement) data are supported
- EPICS addressing: #Cx Sy @n [p] where
- x is the PLC register address relative to the output
register base, i.e. C1 <==> 400001
- y is the bit number (0..15) in the PLC register. This is used for bi and bo records only.
- n is the PLC index (0 for the first PLC)
- p is an optional bit-range identifier for analog records.
p is specified in hex notation of the format [-]<range>, where the minus sign indicates a bipolar signal
Default bit-range is 12 bits, unipolar
Examples for the p parameter:
- for a 16 bit unipolar signal set p to 0xffff
- for an 11 bit unipolar signal set p to 0x7ff
- for a 16 bit bipolar (2's complement) signal, set p to -0x7fff
- for a 12 bit bipolar (2's complement) signal, set p to -0x7ff
- for an 11 bit bipolar (2's complement) signal, set p to -0x3ff
For analog records with bipolar signals set (EGUL, EGUF) to (0, engineering value at <range>)
top
Interface Functions:
The following commands are implemented for use in IOC startup scripts
and from the IOC consolse (you'll find probably a few more in the
source code). The example of an IOC startup script shows the typical
use of these functions. Please note in this example, that the polling
of the PLC is slowed down by setting the global variable moddelay to 20
modtcpDrvCreate
Defines a new PLC. The first call to this function creates PLC 0, the next PLC 1, ...
|
Parameters: |
type
|
1
|
PLC name
|
string
|
2
|
TCP/IP port
|
integer
|
3
|
PLC IP address
|
string
|
4
|
length of memory buffer
|
integer
|
Example:
modtcpDrvCreate("itwplc",502,"142.90.132.94",4096)
modtcpDrvReadGroup
Defines a "read group", i.e. a contiguous set of registers to be read from the PLC.
|
Parameters: |
type
|
1
|
PLC name
|
string
|
2
|
start of read group in PLC (1 <==> 400001)
|
integer
|
3
|
length of read group (must be <= 125)
|
integer
|
4
|
offset into memory buffer for storage
|
integer |
5
|
read-only-once flag (0 = read continuously)
|
integer
|
Example:
modtcpDrvReadGroup("itwplc",1001,23,1001,0)
modtcpDrvWriteGroup
Defines a "write group", i.e. a contiguous area of the memory
buffer, which is monitored for changes. Changed values are written to
the PLC.
|
Parameters: |
type
|
1
|
PLC name
|
string
|
2
|
start of write group in PLC (1 <==> 400001)
|
integer
|
3
|
length of write group (must be <= 125)
|
integer
|
4
|
offset into memory buffer (start of data to write)
|
integer |
Example:
modtcpDrvWriteGroup("itwplc",2001,23,2001)
modtcpWatchdog
Specifies a watchdog location in the PLC, where the value is changing with each PLC scan.
|
Parameters: |
type
|
1
|
PLC name
|
string
|
2
|
watchdog address (1 <==> 400001)
|
integer
|
Example:
modtcpWatchdog("itwplc",3001)
modtcpKeepAlive
Specifies a location in the PLC, to which the driver writes a changed value every 5 seconds
|
Parameters: |
type
|
1
|
PLC name
|
string
|
2
|
"keep alive" address (1 <==> 400001)
|
integer
|
Example:
modtcpKeepAlive("itwplc",101)
modtcpInit
Initializes communication with all PLCs
Example:
modtcpInit
modtcpAbort
Aborts communication with all PLCs
Example:
modtcpAbort
modtcpReport
Reports information about all PLCs on the system. If an optional
parameter > 0 is given, the reported information is more detailed
Example:
modtcpReport 1
modtcpSetAutoReconnect
Enables/disables the auto-reconnect function of the driver. Default is set by #define DEFAULT_RECONNECT in file drvModtcp.c.
NOTE: this function has no effect, if there is no watchdog specified.
|
Parameters: |
type
|
1
|
PLC name |
string
|
2
|
1 (= yes) or 0 (= no)
|
integer
|
Example:
modtcpSetAutoReconnect("itwplc",1);
top
Connection Failures
Behaviour of the driver if the Ethernet is interrupted:
- if no watchdog task is specified in startup script:
In this case read and write tasks block on their TCP/IP recv functions.
Use commands from the IOC consoles:
"modtcpAbort" (or
"modtcpAbortPLC(<PLC index>)", if the IOC drives more than one
PLC) to abort the read and write tasks
"modtcpInit" (or "modtcpInitPLC(<PLC index>)", to restart the read and write tasks
- if watchdog task is specified in startup script:
In this case, the read and write tasks are aborted, when there is no
communication for X 5-second intervals. X is configurable (see
Console Interface).
The reconnect behaviour is determined by the directive
#define DEFAULT_RECONNECT in the source file drvModtcp.c.
This compile-time value can be overridden by a call to
modtcpSetAutoReconnect(1) in the IOC startup script. A value of 1
causes the driver to attempt reconnecting every 20 seconds.
top
Limitations and Known Problems:
- tested on:
- Motorola CPUs with 680x0 architecture
- TRI-M MZ104+ (PC104) boards with x86 architecture
- GMS Mariner (Pentium)
- -- obsolete -- For use with Momentum series PLCs, a "keep alive" write to the
PLC must be implemented, otherwise the TCP/IP server in the PLC closes
write connections after a short period of inactivity. In a future
release, this will be implemented at the driver level. -- obsolete --
- The communication background tasks do only register transfers
between PLC and the IOC memory buffer, i.e supported MODBUS functions
are
- function 3 (READ OUTPUT REGISTERS), i.e. no reading of
individual bits (coils).
- function 6 (PRESET SINGLE REGISTER), i.e. no writing of
individual bits (coils)
Note, however, that EPICS device
support supports binary input and output records.
Known problems:
- none, until you tell me
top