---

drvModtcp.c File Reference

This module implements the Modicon PLC communication protocol to allow an application to talk to a Modicon Quantum or Momentum PLC via TCP/IP. More...

Compounds
union	MIXED_str
struct	plc_str
struct	readGroup_str
struct	writeGroup_str
Defines
#define	VERSION   __DATE__
#define	INVALID_SOCKET   (-1)
#define	ERROR   (-1)
#define	MAX_PLC   5
#define	MAX_REQUEST   500
#define	MAX_READ_POINTS   125
#define	MAX_WRITE_POINTS   500
#define	MAX_MEM   10000
#define	TIMEHISTLENGTH   200
#define	MAX_REPORTGROUPS   20
#define	FAST_CYCLE   20
#define	SLOW_CYCLE   2000
#define	DELAY_RW   330
#define	DELAY_WATCHDOG   5000
#define	logMsg   printf
Typedefs
typedef MIXED_str	MIXED
typedef plc_str	plc_t
typedef readGroup_str	readGroup_t
typedef writeGroup_str	writeGroup_t
Enumerations
enum	radix_t { RAD_dec = 0, RAD_hex }
Functions
void	setEpicsVariables (void)
int	modtcpCheckLimits (PLC_ID pPlc, int start, int length, int offset, int maxp)
	Checks the limits of the parameters to ensure no overflows possible.
int	modtcpInitWriteData (PLC_ID pPLC, WRITEGROUP_ID pGr)
int	modtcpEncodeRead_rq (int function, int start, int points, char *readRequest)
int	modtcpEncodeWrite_rq (int function, int reg, int value, char *readRequest)
int	modtcpStoreData (PLC_ID pPlc, READGROUP_ID pGr, char *readReply)
	Takes the read reply from the PLC and decomposes into the shared memory pool at the proper location.
void	modtcpCounterInit (PLC_ID pPlc)
	Initializes the statistics counters for the specified PLC.
void	modtcpReadCount (PLC_ID pPlc, int ok)
	Increments the read statistics counter.
void	modtcpWriteCount (PLC_ID pPlc, int ok)
	Increments the write statistics counter.
void	modtcpUnpackResponse (char *msg, int start)
void	plcRead (PLC_ID pPlc)
	This function continuously reads the PLC read registers and loads the data into the local data structure.
void	plcWrite (PLC_ID pPlc)
	This function continuously monitors the local data structure and sends.
void	plcWatch (PLC_ID pPlc)
	The watchdog task for the PLC.
int	modtcpUser (char *cmd)
	This is the console based user interface tool.
int	modtcpDrvCreate (char *name, int tcpPort, char *inet_address, int mem_length)
	Creates the data structures, initializes values and prepares all socket information for the connection to a PLC.
long	modtcpInit ()
	Initializes all defined PLCs.
long	modtcpInitPlc (int index)
	Starts the processes that will read and write via sockets to the PLC.
long	modtcpAbort (int index)
	Shuts down the tasks/threads associated with a particular PLC.
void	modtcpRecover (int index)
	Attempts to recover the system by restarting the system.
int	modtcpWrite (int index, int addr, unsigned short mask, unsigned short *pData)
	Writes the passed value to the requested register in the PLC.
int	modtcpRead (int index, int addr, unsigned short mask, unsigned short *pData)
	Reads the current value of the requested register in the PLC.
int	modtcpInitRead (int index, int addr, unsigned short mask, unsigned short *pData)
	EPICS device support access function for PLC reads at record initialization time.
int	modtcpCheckParams (int plcindex, int addr)
	Checks the bounds of the passed address to ensure it is valid for the specified PLC.
int	modtcpDrvReadGroup (char *name, unsigned short start, unsigned short length, unsigned int offset, int read_once)
	Create a read group for the PLC read thread to scan on a regular basis.
int	modtcpDrvWriteGroup (char *name, unsigned short start, unsigned short length, unsigned int offset)
	Create a write group for the PLC write thread to update whenever there are changes.
void	modtcpWatchdog (char *plcname, int address)
	Define the location of the Watchdog register in the PLC.
void	modtcpKeepalive (char *plcname, int address)
	Define the location of the Keepalive register in the PLC.
long	modtcpReport (int level)
	Displays information for each PLC adn the associated read and write groups.
void	modtcpGetTimes ()
	Displays timing statistics.
int	modtcpSetDelay (int delay)
	Sets delay value for the read task loop time.
int	modtcpSetWatchdogDelay (int delay)
	Sets delay value for the watchdog task loop time.
void	modtcpNoisy (int noisy)
	Enabled or disables noisy presentation.
int	modtcpIsNoisy ()
	Tests value of noisy flag.
PLC_ID	plcOpen (char *name)
	Find the PLC by name in the linked list.
int	plcIndex (char *name)
	Find the index of the PLC by name in the linked list.
char *	plcName (int index)
	Find the index of the PLC by name in the linked list.
void	modtcpStartHist (int plcindex)
	Starts logging of activity for diagnostics.
void	modtcpStopHist (int plcindex)
	Stops the histogram system.
void	modtcpPrintHist (int plcindex)
	Displays the histogram information.
int	setplc (char *name)
int	setplcindex (int index)
int	rplc (int start, int regs)
int	dplc (int start, int regs)
int	dgrp (int index, char typ)
int	mplc (int addr, int data)
void	modreport (int mode)
	Change the reporting mode for the screen and slow down the rate to make viewing of info easier.
void	plchex ()
void	plcdec ()
Variables
int	drvModtcpNoisy = 1
int	drvModtcpDebug = 0
int	modprot = 0
int	modRecoverId = 0
unsigned long	modtcpMaxread = 0
unsigned long	modtcpMaxwrite = 0
int	modtcpDebugReadRequest = 0
int	modtcpDebugReadOk = 0
long	moddelay = DELAY_RW
long	modwatch = DELAY_WATCHDOG
long	modwatch_disconnect = 1
long	max_noupd_count = 2
long	plc0_read_ok
long	plc0_write_ok
long	plc0_read_bad
long	plc0_write_bad
long	plc0_enbHist
long	plc0_timeLong
long	plc0_readTicks
long	plc0_timeHist [TIMEHISTLENGTH]
long	plc0_groupTime [MAX_REPORTGROUPS]
PLC_ID	Plcs [MAX_PLC]
PLC_ID	pFirstPlc
PLC_ID	diagPlc
int	no_of_plcs
char *	driver = "drvModtcp"
const unsigned short	mbapListenPort = 502
const int	modbusEncoding = 0
int	modreadrep = 0
int	modwriterep = 0
int	moddogrep = 0
radix_t	radix

---

Detailed Description

This module implements the Modicon PLC communication protocol to allow an application to talk to a Modicon Quantum or Momentum PLC via TCP/IP.

Functions are provided for defining read and write registers in the PLC which are mapped to a shared memory space and updated on a regular basis. Single writes to the shared memory are sent to the PLC.

The following example shows what calls to make to setup the driver.

  modtcpDrvCreate("theplc", 502, "xx.xx.xx.xx", 1024);
  modtcpDrvReadGroup("theplc", 101, 1, 101, 1);
  modtcpDrvReadGroup("theplc", 100, 1, 100, 0);
  modtcpDrvReadGroup("theplc", 103, 1, 103, 0);
  modtcpDrvWriteGroup("theplc", 101, 1, 101);
  modtcpDrvWriteGroup("theplc", 104, 1, 104);
  modtcpWatchdog("theplc", 103);
  modtcpKeepalive("theplc", 104);

• modtcpDrvCreate() sets up the internal structures for a new PLC and defines the IP address.
• modtcpDrvReadGroup() defines a group of read registers which will be scanned regularly to update the shared memory. The write groups are first defined as a "read once" group to read back the current state of the write registers before they are updated.
• modtcpDrvWriteGroup() defines groups of write registers that will be updated whenever a change is made in the shared memory.
• modtcpWatchdog() defines the location of a Watchdog counter in the PLC which should be monitored. A read group must be defined that includes the location of the Watchdog counter read from the PLC. If the PLC watchdog stops it indicates the PLC has stopped cycling.
• modtcpKeepalive() defines an optional register in the PLC that is to be written by the driver on a regular basis to keep the TCP socket open. On Momentum PLCs an idle socket is closed after ten seconds. A write group must be defined that includes the location of the Keepalive counter sent to the PLC.

---

Define Documentation

#define DELAY_RW   330

#define DELAY_WATCHDOG   5000

#define ERROR   (-1)

#define FAST_CYCLE   20

#define INVALID_SOCKET   (-1)

#define logMsg   printf

#define MAX_MEM   10000

#define MAX_PLC   5

#define MAX_READ_POINTS   125

#define MAX_REPORTGROUPS   20

#define MAX_REQUEST   500

#define MAX_WRITE_POINTS   500

#define SLOW_CYCLE   2000

#define TIMEHISTLENGTH   200

#define VERSION   __DATE__

---

Typedef Documentation

typedef union MIXED_str MIXED

typedef struct plc_str plc_t

typedef struct readGroup_str readGroup_t

typedef struct writeGroup_str writeGroup_t

---

Enumeration Type Documentation

enum radix_t

Enumeration values: RAD_dec  RAD_hex

---

Function Documentation

int dgrp (  int    index, char    typ )

int dplc (  int    start, int    regs )

void modreport (  int    mode )

Change the reporting mode for the screen and slow down the rate to make viewing of info easier. Parameters: mode  0x0 to turn off, 0x1 for read, 0x2 for write

long modtcpAbort (  int    index )

Shuts down the tasks/threads associated with a particular PLC. Parameters: index  in the PLC list

int modtcpCheckLimits (  PLC_ID    pPlc, int    start, int    length, int    offset, int    maxp )  [static]

Checks the limits of the parameters to ensure no overflows possible.

int modtcpCheckParams (  int    plcindex, int    addr )

Checks the bounds of the passed address to ensure it is valid for the specified PLC. Parameters: plcindex  the index in the PLC table for the desired PLC addr  the address to test for this PLC

void modtcpCounterInit (  PLC_ID    pPlc )  [static]

Initializes the statistics counters for the specified PLC. Parameters: pPlc  a pointer to the PLC structure

int modtcpDrvCreate (  char *    name, int    tcpPort, char *    inet_address, int    mem_length )

Creates the data structures, initializes values and prepares all socket information for the connection to a PLC. This must be called once for each PLC accessed by the application. See also: modtcpInit() Parameters: name  the local name for the target plc tcpPort  the port to be used for the connection. For Modicon systems this is typically 502. inet_address  a decimal-dot string containing the IP address mem_length  the number of 4x registers in the PLC Return values: PLC_exists  if PLC is already defined in the system PLC_toomany  if the number of defined PLCs exceeds MAX_PLC PLC_maxmem  if the memory required exceeds MAX_MEM PLC_alloc  if unable to allocate space for PLC structure SOCKET_nameExists  if there is already a socket with the passed name SOCKET_alloc  if an error occurrs allocating memory for the socket structure SOCKET_OK  on success

int modtcpDrvReadGroup (  char *    name, unsigned short    start, unsigned short    length, unsigned int    offset, int    read_once )

Create a read group for the PLC read thread to scan on a regular basis. This must be called once for each PLC read group accessed by the application. See also: modtcpWatchdog Parameters: name  the local name for the target plc start  the start of the read group in the PLC (1001 <==> 401001) length  the number of 16 bit words to read offset  the offset into the memory buffer for storage read_once  if 1, group is read only once Return values: GROUP_OK  on success GROUP_badplc  GROUP_exists  GROUP_alloc  -1  if bad socket name

int modtcpDrvWriteGroup (  char *    name, unsigned short    start, unsigned short    length, unsigned int    offset )

Create a write group for the PLC write thread to update whenever there are changes. This must be called once for each PLC write group accessed by the application. See also: modtcpKeepalive Parameters: name  the local name for the target plc start  the start of the read group in the PLC (1001 <==> 401001) length  the number of 16 bit words to read offset  the offset into the memory buffer for storage Return values: GROUP_OK  on success GROUP_badplc  GROUP_exists  GROUP_alloc  -1  if bad socket name

int modtcpEncodeRead_rq (  int    function, int    start, int    points, char *    readRequest )  [static]

int modtcpEncodeWrite_rq (  int    function, int    reg, int    value, char *    readRequest )  [static]

void modtcpGetTimes (    )

Displays timing statistics.

long modtcpInit (    )

Initializes all defined PLCs. Starts the processes that will read and write via sockets to the PLC. Spawn the watchdog task; one for each PLC on first call only. Spawn the read task and wait until all read-once groups are read. Spawn the write task with the read-once values. See also: modtcpInitPlc Returns: PLC_OK

long modtcpInitPlc (  int    index )

Starts the processes that will read and write via sockets to the PLC. Spawn the watchdog task; one for each PLC on first call only. Spawn the read task and wait until all read-once groups are read. Spawn the write task with the read-once values. Note the structures used for creating the threads. For OS portability, the vxWorks format is used, but under UNIX and WINDOWS, only a couple of the parameters are extracted by ss_thread_spawn See also: plcRead , plcWrite , plcWatch Parameters: index  in the PLC list Return values: PLC_OK  success PLC_exists  already initialized

int modtcpInitRead (  int    index, int    addr, unsigned short    mask, unsigned short *    pData )

EPICS device support access function for PLC reads at record initialization time. only to be used for _output_ records! all read-once groups must have been read! Parameters: index  the index in the PLC table for the desired PLC addr  the address of the register number in the 4x section, without the 4x prefix mask  a bit mask if needed. If zero, then the whole value is returned pData  a pointer to the place to put the value Returns: the latest data value from the PLC read/write data buffer (where it was deposited by read_plc()) Return values: -1  if the socket value is invalid, if the Read Once actions are not complete 0  on success

int modtcpInitWriteData (  PLC_ID    pPLC, WRITEGROUP_ID    pGr )  [static]

int modtcpIsNoisy (    )

Tests value of noisy flag. Returns: value of noisy flag

void modtcpKeepalive (  char *    plcname, int    address )

Define the location of the Keepalive register in the PLC. This is needed for Momentum PLCs which close unused sockets after 10 seconds. This location will be written every 5 seconds by the watchdog task See also: modtcpWatchdog Parameters: plcname  the local name for the PLC address  the location in the 4x registers where the keepalive value is located

void modtcpNoisy (  int    noisy )

Enabled or disables noisy presentation.

void modtcpPrintHist (  int    plcindex )

Displays the histogram information. The display shows See also: modtcpStartHist(). , modtcpStopHist(). Parameters: plcindex  the index of the PLC to log

int modtcpRead (  int    index, int    addr, unsigned short    mask, unsigned short *    pData )

Reads the current value of the requested register in the PLC. This will be the local copy updated by the plcRead() task. EPICS device support accesses this function for PLC reads. If the watchdog is defined, it must be running! Parameters: index  the index in the PLC table for the desired PLC addr  the address of the register number in the 4x section, without the 4x prefix mask  a bit mask if needed. If zero, then the whole value is returned pData  a pointer to the place to put the value Returns: 0 on success else ERROR

void modtcpReadCount (  PLC_ID    pPlc, int    ok )  [static]

Increments the read statistics counter. Parameters: pPlc  a pointer to the PLC structure ok  if true, then the write was successful, so increment the write_ok counter. If false then an error occurred so increment the write_bad counter.

void modtcpRecover (  int    index )

Attempts to recover the system by restarting the system. After restart, sets the scan delay to the previous value. Parameters: index  the index of the PLC to recover

long modtcpReport (  int    level )

Displays information for each PLC adn the associated read and write groups. Parameters: level  the level of detail 0 = just PLC 1 = read/write statistics

int modtcpSetDelay (  int    delay )

Sets delay value for the read task loop time. Parameters: delay  the delay between reads of the PLC in milliseconds. Note that for vxWorks the resolution will be 1/60th of a second. Returns: the previous value of the delay

int modtcpSetWatchdogDelay (  int    delay )

Sets delay value for the watchdog task loop time. Parameters: delay  the delay between reads of the PLC watchdog in milliseconds. Note that for vxWorks the resolution will be 1/60th of a second. Returns: the previous value of the delay

void modtcpStartHist (  int    plcindex )

Starts logging of activity for diagnostics. See also: modtcpPrintHist(). , modtcpStopHist(). Parameters: plcindex  the index of the PLC to log

void modtcpStopHist (  int    plcindex )

Stops the histogram system. See also: modtcpStartHist(). , modtcpPrintHist(). Parameters: plcindex  the index of the PLC to log

int modtcpStoreData (  PLC_ID    pPlc, READGROUP_ID    pGr, char *    readReply )  [static]

Takes the read reply from the PLC and decomposes into the shared memory pool at the proper location. Parameters: pPlc  pGr  readReply

void modtcpUnpackResponse (  char *    msg, int    start )  [static]

int modtcpUser (  char *    cmd )  [static]

This is the console based user interface tool.

void modtcpWatchdog (  char *    plcname, int    address )

Define the location of the Watchdog register in the PLC. See also: modtcpKeepalive Parameters: plcname  the local name for the PLC address  the location in the 4x registers where the watchdog value is located

int modtcpWrite (  int    index, int    addr, unsigned short    mask, unsigned short *    pData )

Writes the passed value to the requested register in the PLC. This will update the local copy and the plcWrite() task will send the data to the PLC. EPICS device support accesses this function for PLC writes. No test is made of the watchdog . Parameters: index  the index in the PLC table for the desired PLC addr  the address of the register number in the 4x section, without the 4x prefix mask  a bit mask if needed. If zero, then the whole value is returned pData  a pointer to the place to find the value Returns: 0 on success else -1

void modtcpWriteCount (  PLC_ID    pPlc, int    ok )  [static]

Increments the write statistics counter. Parameters: pPlc  a pointer to the PLC structure ok  if true, then the write was successful, so increment the write_ok counter. If false then an error occurred so increment the write_bad counter.

int mplc (  int    addr, int    data )

void plcdec (    )

void plchex (    )

int plcIndex (  char *    name )

Find the index of the PLC by name in the linked list. Parameters: name  the name of the PLC Returns: index of PLC_ID structure in linked list

char* plcName (  int    index )

Find the index of the PLC by name in the linked list. Returns: index of PLC_ID structure in linked list

PLC_ID plcOpen (  char *    name )

Find the PLC by name in the linked list. Parameters: name  the name of the PLC Returns: pointer to PLC_ID structure

void plcRead (  PLC_ID    pPlc )  [static]

This function continuously reads the PLC read registers and loads the data into the local data structure. It runs as a separate thread or task. Only one instance spawned per PLC. Parameters: pPlc  pointer to PLC_ID structure. Must not be NULL.

void plcWatch (  PLC_ID    pPlc )  [static]

The watchdog task for the PLC. Only one instance should be started per PLC. The process will terminate if no watchdog location has been defined. Parameters: pPlc  pointer to PLC_ID structure with all info about PLC

void plcWrite (  PLC_ID    pPlc )  [static]

This function continuously monitors the local data structure and sends. any modifications to the correct PLC registers. It runs as a separate thread or task. Only one instance spawned per PLC. Parameters: pPlc  pointer to PLC_ID structure. Must not be NULL.

int rplc (  int    start, int    regs )

void setEpicsVariables (  void    )  [static]

int setplc (  char *    name )

int setplcindex (  int    index )

---

Variable Documentation

PLC_ID diagPlc [static]

char* driver = "drvModtcp" [static]

int drvModtcpDebug = 0

int drvModtcpNoisy = 1

long max_noupd_count = 2

const unsigned short mbapListenPort = 502 [static]

const int modbusEncoding = 0 [static]

long moddelay = DELAY_RW

int moddogrep = 0 [static]

int modprot = 0

int modreadrep = 0 [static]

int modRecoverId = 0

int modtcpDebugReadOk = 0

int modtcpDebugReadRequest = 0

unsigned long modtcpMaxread = 0

unsigned long modtcpMaxwrite = 0

long modwatch = DELAY_WATCHDOG

long modwatch_disconnect = 1

int modwriterep = 0 [static]

int no_of_plcs [static]

PLC_ID pFirstPlc [static]

long plc0_enbHist

long plc0_groupTime[MAX_REPORTGROUPS]

long plc0_read_bad

long plc0_read_ok

long plc0_readTicks

long plc0_timeHist[TIMEHISTLENGTH]

long plc0_timeLong

long plc0_write_bad

long plc0_write_ok

PLC_ID Plcs[MAX_PLC] [static]

radix_t radix [static]

---