= EPICS interface for the PLC system = <> == Overview == PLC system holds signal values in its internal registers. By reading the register values or writing values into the registers, we can communicate with the PLC system. EPICS translator is a software translating the PLC register values to EPICS process variables (PVs). It can also transfer EPICS PV values into PLC registers. The EPICS translator is implemented as an EPICS IOC. It is running on a computer called k1kiki0 (the name should be changed to k1plc0). Physical location of this computer is the PLC rack in the center area. You can login to this computer from the KAGRA control network with the controls account. === A note on EPICS terminology === The following words are used to mean basically the same thing. PV (Process Variable)<
> EPICS record<
> EPICS channel "PV" and "record" are correct EPICS terms. "Channel" is widely used to mean PV or record, but it is a misuse. == How to add/modify PLC related EPICS PVs == As a policy, the PLC system provide two classes of EPICS PVs. * Hardware PVs These PVs read or write into hardware channels, for example: channel 1 of Y-End ADC, channel 6 of X-End DI and so on. These PVs have names such as K1:PLC-YEND_ADC_Ch1 or K1:PLC-XEND_DI_Ch6. The names do not contain the information of what is connected. So users of the PLC system should create User PVs to have more meaningful names. The PLC administrator (currently Aso) will make all the hardware channels available as hardware PVs. * User PVs These PVs read one or more hardware PVs and (optionally) do some calculations to produce physically meaningful values and PV names. For example, assuming that a vacuum gauge is connected to Y-End ADC Ch1 and the corresponding hardware PV is K1:PLC-YEND_ADC_Ch1, you can create an user PV, K1:PLC-VAC_EY_PRESSURE, with the following database definition. {{{ record (calc, "$(SYSTEM)-VAC_EY_PRESSURE") { field (DESC, "EY Vacuum pressure" ) field (INPA, "$(SYSTEM)-YEND_ADC_Ch1") field (CALC, "10^(1.667*A*10/4096 - 9.33)" ) field (EGU, "Pa") field (SCAN,"$(SCAN) second") } }}} This PV holds the vaccum pressure in Pa. You do not have to do a calculation unless necessary. Just copying the value of a hardware PV is fine in most cases. === Adding a hardware PVs (usually not necessary for users) === * Check the register address to which the hardware channel is assigned by looking at the [[https://gwdoc.icrr.u-tokyo.ac.jp/cgi-bin/private/DocDB/ShowDocument?docid=3712|documents]] provided by Hitz. センターエリアレジスターマップ.pdf shows the register assignments. * Login to k1kiki0 as controls * Go to "/home/controls/PLC/EPICS_Trans/base-3.14.12.2/db/". Actually, /home/controls/PLC folder is linked to KAGRA Dropbox's Dropbox/Subsystems/PLC. Therefore, you can also edit files in this directory from Dropbox and the result is automatically synchronized to k1kiki0. * Edit a database file. For example, to add/modify ADC channels in Y-End, open yEndADC.db. * PLC register values are first read into EPICS array records, such as "K1:PLC:M0-959". These arrays are defined in "kagraMpsArray.db". * To extract a single channel value for a hardware PV, use DTYP of "devFromArray". Here is an example: {{{ record (ai, "$(SYSTEM)-XEND_ADC_Ch1") { field (DESC, "D3792:X-End ADC Ch1 value" ) field (DTYP, "devFromArray") field (INP, "$(SYSTEM):D3640-D4599 @ 152" ) field (SCAN,"$(SCAN) second") } }}} * This example reads a register value at D3792 from the EPICS array "$(SYSTEM):D3640-D4599", using "@ 152" as an index. The value is available as "$(SYSTEM)-XEND_ADC_Ch1". * Note that $(SYSTEM) is replaced with K1:PLC at the time of execution. This is defined in "/home/controls/PLC/EPICS_Trans/base-3.14.12.2/iocBoot/iockagraMps/st_end.cmd". * If you add a new database file, see the section "[[#AddNewDb|Adding a new database file]]" below. * [[#Start.2BAC8-Restart|Restart]] the EPICS translator IOC. * If you need to access PLC registers which are not read in kagraMpsArray.db, see [[KAGRA/Subgroups/MIF/PLC/EPICS/RegisterAccess|Register Access]] for how to configure the EPICS translator to read those registers. === How to add a User PV === * You can create a user PV by reading a hardware PV from a calculation record. * For example, to read the value of the digital input channel 10 of Y-End, and export it as K1:PLC-VAC_EY_GV1_OPEN, make the following record. {{{ record (calc, "$(SYSTEM)-VAC_EY_GV1_OPEN") { field (DESC, "EY GV Open" ) field (INPA, "$(SYSTEM)-YEND_DI_Ch10") field (CALC, "A" ) field (SCAN,"$(SCAN) second") } }}} * This example does not do any conversion, just copying the value to the new PV. * You can do arbitrary calculation using the CALC field. See the EPICS [[https://wiki-ext.aps.anl.gov/epics/index.php/RRM_3-14_Calculation|documentation]] for more details. * You can put the new record in an arbitrary database file. Currently, there are xEnd.db and yEnd.db to hold such user PVs. * If you add a new database file, see the section "[[#AddNewDb|Adding a new database file]]" below. <> === Adding a new database file === * When you add a new database file, modify "/home/controls/PLC/EPICS_Trans/base-3.14.12.2/iocBoot/iockagraMps/st_end.cmd" and add the name of the new database file as follows: {{{ dbLoadRecords("db/newDatabaseFile.db","SYSTEM=$(SYSTEM),SCAN=.1") }}} * Then restart the EPICS translator (see below). <> === Starting/Restarting the EPICS translator === The EPICS translator is started at the system start by systemd. You can control it by executing the following commands on k1kiki0. * Start {{{ sudo systemctl start epics-trans.service }}} * Stop {{{ sudo systemctl stop epics-trans.service }}} * Restart {{{ sudo systemctl restart epics-trans.service }}} * Check the status {{{ sudo systemctl status epics-trans.service }}} * Get the log {{{ sudo journalctl -u epics-trans }}} ==== Details of the systemd configuration ==== The systemd unit file for EPICS translator is "/lib/systemd/system/epics-trans.service". {{{ [Unit] Description=EPICS Translator for the KAGRA PLC system After=network.target [Service] Environment=EPICS_BASE=/home/controls/PLC/EPICS_Trans/base-3.14.12.2 Environment=EPICS_HOST_ARCH=linux-x86 Environment=TOP=/home/controls/PLC/EPICS_Trans/base-3.14.12.2 Environment=ASYN=/home/controls/PLC/EPICS_Trans/base-3.14.12.2/asyn ExecStart=/home/controls/PLC/EPICS_Trans/base-3.14.12.2/bin/linux-x86/kagraMps /home/controls/PLC/EPICS_Trans/base-3.14.12.2/iocBoot/iockagraMps/st_end.cmd StandardInput=tty TTYPath=/dev/tty50 StandardOutput=journal KillMode=process Restart=always [Install] WantedBy=multi-user.target }}} Assigning tty50 to the standard input is necessary to run the IOC properly because it expects to be run in a terminal. * Enable this service {{{ sudo systemctl enable epics-trans.service }}} == Registering new EPICS PVs to KAGRA DAQ == In order to record the values of newly added EPICS PVs in the KAGRA DAQ system, you need to do the following configuration work. * Login to one of the control workstations. * Go to /opt/rtcds/kamioka/k1/chans/daq * Put the name of the new PV in one of the existing *.ini files or create a new *.ini file. The format of the *.ini file is the following: {{{ [default] gain=1.00 datatype=4 ifoid=0 acquire=3 offset=0 units=V dcuid=4 datarate=16 [K1:PLC-VAC_EY_PRESSURE] units=Pa [K1:PLC-YEND_ADC_Ch5] }}} * If you add a new *.ini file, put the name in /opt/rtcds/kamioka/k1/target/fb/master so that the new *.ini file is imported by daqd. * Restart daqd by logging into k1dc0 and killing daqd. Before doing this, make sure that no one is doing measurements with the digital system.