EPICS interface for the PLC system

Contents

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 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 "Adding a new database file" below.
Restart the EPICS translator IOC.
If you need to access PLC registers which are not read in kagraMpsArray.db, see 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 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 "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.