Advanced Ligo Twincat Epics Ioc (Tcioc) User Guide: Ligo Laboratory / Ligo Scientific Collaboration
Advanced Ligo Twincat Epics Ioc (Tcioc) User Guide: Ligo Laboratory / Ligo Scientific Collaboration
Daniel Sigg
1
LIGO LIGO-E1900185-v2
Table of Contents
1 Introduction...................................................................................................3
2 IOC Commands.............................................................................................3
2.1 EPICS Initialization............................................................................................3
2.2 Scan Rate...........................................................................................................4
2.3 Loading Records...............................................................................................4
2.4 Alias and Replacement Rules..........................................................................5
2.5 Generating Listings..........................................................................................5
2.6 Information Records.........................................................................................5
2.7 Generating Macros............................................................................................6
3 TwinCAT EPICS Options..............................................................................8
4 OPC Specification.......................................................................................10
4.1 OPC Access.....................................................................................................12
4.2 OPC Properties................................................................................................12
4.3 Automatic Type Support................................................................................14
4.4 Enumerated Types..........................................................................................14
4.5 Array Variables................................................................................................15
2
LIGO LIGO-E1900185-v2
1 Introduction
The TwinCAT EPICS IOC, tcIoc, is an interface between the TwinCAT automation software
and the EPICS channel access. It makes TwinCAT variables available to the EPICS system using
an annotation mechanism similar to the TwinCAT OPC server. The exported variables of one or
multiple TwinCAT PLCs are scanned at a fixed rate using the TwinCAT ADS communication
library. A memory pool is setup in the IOC which mirrors the variable value in the TwinCAT
PLCs. On the EPICS side a device driver has been written for a “tcat” device that interfaces this
memory pool and makes all variables available using channel access. Special care was taken to
map EPICS output channels to TwinCAT variables that are both readable and writeable. EPICS
input channels are mapped to TwinCAT read only variables. Write only variables are not
supported.
In the current TwinCAT EPICS IOC implementation, the exported variables have to be declared
as global symbols. They can be of complex types such as structures and arrays—even structures
of structures. Since EPICS doesn’t support complex types, complex types are expanded down to
the simple types, which are then exported each as an EPICS database record. Floating point types
are mapped to ai/ao records, integer types to longin/longout records, character strings to
stringin/stringout records, and Boolean types to bi/bo records. Enumerated types are mapped to
mbbi/mbbo records, if the numerical representation lies within 0 to 15. Otherwise, they map to
longin/longout records as well. EPICS only supports short strings, so TwinCAT string values
that are larger than 40 characters are truncated.
EPICS also has limitation on the length of channels names. The current limitation is 56
characters maximum. Since the EPICS channel names are typically derived from the full
TwinCAT variable name, one has to be careful to stay within this limit. Deep structures of
structures can exceed this limit more easily, since each element name is appended to the base
variable name.
If a TwinCAT PLC is halted, the data exchange will stop and all EPICS variables are set to
invalid. If the TwinCAT PLC is restarted, the data exchange will be reinitialized and the EPICS
variables become valid again. The tcIoc is periodically checking the TwinCAT configuration. If
it has changed, e.g., after a recompiling and reloading, the data exchange will also stop. Since the
tcIoc cannot alter the EPICS database, it has to be terminated and restarted to load the new
configuration.
2 IOC Commands
The TwinCAT EPICS IOC looks like a normal IOC, but supports an extra command set to
configure the TwinCAT interface. A typical tcIoc configuration file is listed in Table 1. The last
command in a tcIoc configuration file should be the “iocInit()” command to start the EPICS
server.
3
LIGO LIGO-E1900185-v2
the TwinCAT specific device driver commands, and the third line increases the callback queue
size, which may be needed for large databases.
4
LIGO LIGO-E1900185-v2
dbLoadDatabase("C:\SlowControls\tcIoc\tCat.dbd",0,0)
tCat_registerRecordDeviceDriver(pdbbase)
callbackSetQueueSize(50000)
tcSetScanRate(10, 5)
tcSetAlias("C1PLC1", "IFO=H1,END=X")
tcGenerateList("C:\SlowControls\Target\PLC1.opc.txt","-l -rn -yi -cp")
tcGenerateList("C:\SlowControls\Target\PLC1.chn.txt","-l")
tcGenerateList("C:\SlowControls\Target\PLC1.req","-lb")
tcGenerateMacros("C:\SlowControls\Target\ADL")
tcInfoPrefix(".\${IFO}.Sys.\${ALIAS}.info")
tcLoadRecords ("C:\SlowControls\Target\PLC1.tpy")
iocInit()
5
LIGO LIGO-E1900185-v2
6
LIGO LIGO-E1900185-v2
7
LIGO LIGO-E1900185-v2
TYPE ErrorStruct :
STRUCT
Flag: BOOL; (*~
(OPC :1: Make variable visible for OPC-Server)
(OPC_PROP[005] :1: OPC_PROP_RIGHTS)
(OPC_PROP[0101] :Error flag: Description)
(OPC_PROP[0106] :Error: ONAM)
(OPC_PROP[0107] :OK: ZNAM)
*)
Code: DWORD; (*~
(OPC :1: Make variable visible for OPC-Server)
(OPC_PROP[005] :1: OPC_PROP_RIGHTS)
(OPC_PROP[0101] :Bit endcoded error condition: Description)
*)
Msg: STRING; (*~
(OPC :1: Make variable visible for OPC-Server)
(OPC_PROP[005] :1: OPC_PROP_RIGHTS)
(OPC_PROP[0101] :Human readable error message: Description)
*)
END_STRUCT
END_TYPE;
It will also generate macros for error screens. For this to work properly, a global list needs to be
defined that contains all error messages. These error messages need to be defined in a global
constant of type ErrorMessagesArray. Example:
VAR_GLOBAL CONSTANT
ThermistorStruct_Errors: ErrorMessagesArray :=
(* 1 *) 'Thermistor resistance is too high',
(* 2 *) 'Thermistor resistance is too low',
(* 3 *) 'Thermistor data invalid',
(* 4 *) 'Thermistor measurement error';
END_VAR
The name of the constant string array has to reflect the name of the structure that contains the
error structure with the extension “_Errors” added. In TwinCAT2 this constant has to be linked
to a file with the name “ThermistorStruct_Errors.exp” with the option “Export before compile”
selected. This will guarantee that the automatic screen generator is able to assemble an error list
for each structure.
8
LIGO LIGO-E1900185-v2
Option Description
Channel Processing:
/eo (default) Only export variables which are marked by an OPC export directive in the tpy file
/ea Export all global variables regardless of the OPC settings in the tpy file
/ys (default) String variables are processed
/ns No string variables are processed
/pa (default) Process all types
/ps Process only simple types types, e.g., INT, BOOL, DWORD, etc.
/pc Process only complex types, e.g., STRUCT, ARRAY
Channel Name Conversion:
/rl (default) LIGO standard conversion rule
/rv LIGO rules for initial vacuum channel names (version 1.1)
/rd Replace dots with underscores in channel names
/rn Do not apply any special conversion rules
/cp Preserve case in EPICS channel names
/cu (default) Force upper case in EPICS channel names (default)
/cl Force lower case in EPICS channel names
/nd (default) Eliminate leading dot in channel name as well as all prior characters
/yd Leave leading dot in channel name as well as all prior characters
/yi Leave array indices in channel names
/ni Replace array brackets with a single leading underscore
/p 'name' Include a prefix of 'name' for every channel (defaults to no prefix)
Split File Support:
/nsio (default) Do not split database or listing by record type
/ysio Split database or listing into input only and input/ouput recrods
/sn ‘num’ Split database or listing into files with no more than 'num' records
/sn 0 (default) Does not split database or listing into multiple files
9
LIGO LIGO-E1900185-v2
10
LIGO LIGO-E1900185-v2
4 OPC Specification
We are using the TwinCAT OPC comments denoted by (*~ ... *) to make global variables
accessible to the OPC server. The opening bracket annotation needs to be on the same line as the
variable. OPC properties are used to describe additional database fields such as limits
(HOPR/LOPR), precision (PREC) and many more. These OPC properties are translated into
corresponding EPICS database fields. An extended example can be found in Table 5.
Individual tags such as the LaserType of the ALSLaserStruct will have the TwinCAT name
“H1.Als.X.Laser.LaserType”. The default EPICS channel name constructed from this tag will
then become “H1:ALS-X_LASER_LASERTYPE”, if the LIGO standard conversion option is
selected. Be aware that TwinCAT names are not case sensitive, whereas EPICS channel names
are case sensitive.
TYPE ALSLaserEnum : (
NPRO, (*NPRO*)
Diode, (*DIODE*)
Argon (*ARGON*)
};
END_TYPE; (*~
(OPC_PROP[8510] :NPRO: ZRST)
(OPC_PROP[8511] :DIODE: ONST)
(OPC_PROP[8512] :ARGON: TWST)
*)
TYPE ALSLaserStruct:
STRUCT
Error: ErrorStruct;
LaserType: ALSLaserEnum;
LaserDiodePowerMonitor: LREAL; (*~
(OPC :1: Make variable visible for OPC-Server)
(OPC_PROP[005] :1: OPC_PROP_RIGHTS)
(OPC_PROP[0100] :A: Unit/EGU)
(OPC_PROP[0101] :Laser diode 1 power monitor: Description/DESC)
(OPC_PROP[8500] :3: Display precision/PREC)
*)
LaserDiodePowerNominal: LREAL; (*~
(OPC :1: Make variable visible for OPC-Server)
(OPC_PROP[005] :3: OPC_PROP_RIGHTS)
(OPC_PROP[0100] :A: Unit)
(OPC_PROP[0101] :Laser diode power nominal: Description)
(OPC_PROP[8500] :3: Display precision)
*)
NoiseEaterRelay: BOOL; (*~
(OPC :1: Make variable visible for OPC-Server)
(OPC_PROP[005] :3: OPC_PROP_RIGHTS)
11
LIGO LIGO-E1900185-v2
TYPE AlsEndStruct :
STRUCT
Laser: ALSLaserStruct;
VCO: LowNoiseVcoStruct;
PZT: ARRAY [1..2] OF PZTMirrorStruct;
…
END_STRUCT
END_TYPE;
TYPE AlsStruct :
STRUCT
End: AlsEndStruct; (*~
(OPC :1: visible)
(OPC_PROP[8620] :${END}: alias name)
*)
END_STRUCT
END_TYPE
…
TYPE IfoStruct:
STRUCT
Als: AlsStruct;
…
END_STRUCT
END_TYPE;
VAR_GLOBAL
IFO: IfoStruct; (*~
(OPC :1: visible)
(OPC_PROP[8620] :.${IFO}: alias name)
*)
END_VAR;
12
LIGO LIGO-E1900185-v2
will make the entire IFO variable with all its sub elements visible through the OPC interface. In
turn, it can be interfaced by EPICS. The default behavior of a structure element is to be visible,
when the corresponding global variable is visible. However, if an OPC comment is added to a
structure element, the visibility has to be set explicitly again.
13
LIGO LIGO-E1900185-v2
14
LIGO LIGO-E1900185-v2
EPICS TwinCAT
longin/longout SINT, INT, DINT, LINT, USINT, UINT, UDINT, ULINT, BYTE, WORD, DWORD,
LWORD
bi/bo BOOL
mbbi/mbbo Enumerated data type with 16 or fewer labels
stringin/stringout STRING
ai/ao REAL, LREAL, any other
This leads to EPICS labels of the form H1, L1, etc. rather than the default IfoH1, IfoL1, etc.
TwinCAT3 no longer requires enum labels to be unique, so they can be defined exactly as they
will be seen in EPICS. Unfortunately, the OPC support in TwinCAT3 is broken for enumerated
types, and one has to revert to normal comments after each tag; see Table 5 for an example.
15
LIGO LIGO-E1900185-v2
TYPE DemodComplex:
STRUCT
I: LREAL;
Q: LREAL;
END_STUCT
END_TYPE;
TYPE WfsStruct:
STRUCT
Gain: ARRAY [1..4] OF LREAL;
Rotation: ARRAY [1..4,1..4] OF LREAL;
Signal: ARRAY [1..4] OF DemodComplex;
END_STUCT
END_TYPE;
The corresponding OPC and EPICS variables are (with m and n ranging from 1 to 4):
16