Better comments on database logic; Updated README

README.md

 
-e3-ts2evm  
+e3-ts2evm - Test Stand 2 Event Master (EVM) IOC 
 ======
-ESS Site-specific EPICS module : ts2evm
+## Description
+ts2evm is an E3 module dedicated to Test Stand 2 Timing System. It runs on top of the **mrfioc2** support for the MRF MTCA Event Master (mTCA-EVM-300). This module is intended to be used by the IOC that controls TS2 EVM.
+## Operation
 
+ts2evm will configure the EVM sequencer tables in order to periodically generate the main timing events for the TS2 operation:
+- Modulator Start (Event 20)
+- RF Start (Event 15)
+
+The generation of these events in time domain are defined by high level parameters:
+- Cycle Frequency
+- RF start delay from modulator start
+- RF pulse width
+
+The module also allows two modes of operation for the EVM events:
+- Free Running (with periods defined the cycle frequency - max. 14 Hz)
+- On Demand (Discrete number of cycles)
+
+## Implementation
+
+The business logic of this module is implemented using EPICS database logic and aSub records for the manipulation of the EVM sequencer arrays.
+
+The main concept of this module is bases on the [ESS SuperCycle](https://github.com/icshwi/supercycleEngine.git) engine:
+
+## Dependencies
+- [mrfioc2](https://gitlab.esss.lu.se/e3/wrappers/ts/e3-mrfioc2.git)
+- [busy](https://gitlab.esss.lu.se/e3/wrappers/core/e3-busy.git)
+## OPI Demonstration
+![alt text](opi/evm-opi.gif "TS2 EVM Demo")

cmds/example.cmd

@@ -29,7 +29,7 @@ iocshLoad("$(essioc_DIR)/common_config.iocsh")
 #- time2ntp("EVM", 2)
 #
 #- Creates NTTable
-evmConfigure $(PREFIX):EvtTable
+evmConfigNTTable $(PREFIX)
 #
 #- Start IOC
 iocInit()

ts2evmApp/Db/ts2_evm_sequencer.template

@@ -92,7 +92,8 @@ record(fanout, "$(P)$(R=)#SeqSelecPrep") {
 }
 
 ########################################################
-# aSub process
+# aSub process - calculates the sequencer tables
+# based on user inputs
 ########################################################
 record(aSub, "$(P)$(R=)#Seq-Write-aSub") {
     field(DESC, "Sequencer arrays")
@@ -157,6 +158,9 @@ record(aSub, "$(P)$(R=)#Seq-Write-aSub") {
     field(TPRO, "$(TPRO_DBG=0)")
 }
 
+########################################################
+# Just make sure SoftSeq-TS2 are processed
+########################################################
 record(fanout, "$(P)$(R=)#SeqProcSeqTables") {
     field(DESC, "Process sequencer setpoint tables")
     field(SELM, "All")
@@ -167,6 +171,10 @@ record(fanout, "$(P)$(R=)#SeqProcSeqTables") {
     field(TPRO, "$(TPRO_DBG=0)")
 }
 
+########################################################
+# Auxiliary record to indicate if EVM sequencers should
+# be enabled (used by On Demand mode)
+########################################################
 record(calc, "$(P)$(R=)#Seq-Enable-Cond") {
     field(INPA, "$(P)$(R=)Mode NPP")
     field(INPB, "$(P)$(R=)StartFixedCycles NPP")
@@ -178,6 +186,11 @@ record(calc, "$(P)$(R=)#Seq-Enable-Cond") {
     field(FLNK, "$(P)$(R=)#SeqMainProcess PP")
 }
 
+########################################################
+# Main processing sequence, triggered after any action
+# on the settings PVs. Target EVM sequencer (1 or 2) is
+# always toggling.
+########################################################
 record(seq, "$(P)$(R=)#SeqMainProcess") {
     field(SELM, "All")
     
@@ -222,6 +235,10 @@ record(seq, "$(P)$(R=)#SeqMainProcess") {
     field(TPRO, "$(TPRO_DBG=0)")
 }
 
+########################################################
+# Trigger the processing of the record that decides
+# if sequencer should be enabled or not
+########################################################
 record(fanout, "$(P)$(R=)#Seq-Enable-Disable") {
     field(SELM, "Specified")
     field(SELL, "$(P)$(R=)#Seq-Enable-Cond")
@@ -231,6 +248,10 @@ record(fanout, "$(P)$(R=)#Seq-Enable-Disable") {
     field(TPRO, "$(TPRO_DBG=0)")
 }
 
+########################################################
+# Verify current event parameters based on the actual
+# status of the EVM hardware sequencer
+########################################################
 record(aSub, "$(P)$(R=)#Seq-Verify") {
     field(DESC, "Verify params")
     field(SNAM, "seqVerify")

ts2evmApp/Db/ts2_nttable.template

+########################################################
+# Auxiliary record that holds the string of the prefix
+########################################################
 record(stringin, "$(P)$(R=)#prefixVal") {
     field(DESC, "Prefix of the PVs")
     field(VAL,  "$(P)$(R=)")
@@ -5,10 +8,14 @@ record(stringin, "$(P)$(R=)#prefixVal") {
     field(PINI, "YES")
 }
 
+########################################################
+# aSub record that causes the update of the NTTable PV
+# TODO: proper method to find the PVA record, currently
+# it relies on the prefix "$(P)$(R) as an input to this aSub"
+########################################################
 record(aSub, "$(P)$(R=)#ntTableProc") {
     field(SNAM, "processNtTable")
 
-    #! field(PINI, "YES")
     field(DESC, "Process NTTable record")
 
     field(FTA, "STRING")
@@ -22,10 +29,6 @@ record(aSub, "$(P)$(R=)#ntTableProc") {
     field(NOC, "8")
     field(INPC, "$(P)$(R=)SoftSeq-TS2-EvtCode-RB NPP")
 
-    #! TODO finalise the implementation
-    #field(OUTA, "$(P):$(R):TTCheckAndLoad-Sts PP")   #! status of the check
-    #field(FTVA, "STRING")
-
-    field(TPRO, "1")
+    field(TPRO, "$(TPRO_DBG=0)")   
     field(DISA, "0")
 }

ts2evmApp/src/ioc_utils.cpp

@@ -71,28 +71,30 @@ void evmTableHooks(initHookState state)
 
 static const iocshArg funcArg0 = { "NTTable PV Name", iocshArgString };
 static const iocshArg *funcArgs[] = {&funcArg0};
-static const iocshFuncDef evmTableFuncDef = {"evmConfigure", 1, funcArgs};
+static const iocshFuncDef evmTableFuncDef = {"evmConfigNTTable", 1, funcArgs};
 
 static void evmTableCallFunc(const iocshArgBuf *args)
 {
     if (!configureFunctionCalled) {
         if(!args[0].sval) {
-            throw std::runtime_error("evmConfigure: missing argument. Usage: evmConfigure [NTTABLE_NAME]");
+            throw std::runtime_error("evmConfigNTTable: missing argument. Usage: evmConfigNTTable [PREFIX]");
         }
 
-        /* Create record with NTTable */
+        // Get main prefix of the IOC records and adds the standard suffix ":EvtTable"
         string ntTableRecordName(args[0].sval);
+        ntTableRecordName += ":EvtTable";
+        
+        // Create record with custom PVRecord class and add it to IOC
         ntTableEvmRecordPtr record = ntTableEvmRecord::create(ntTableRecordName);
-
         bool result = PVDatabase::getMaster()->addRecord(record);
         if(!result) 
-            errlogPrintf("evmConfigure: NTTable record %s was not added to the IOC\n", ntTableRecordName.c_str());
+            errlogPrintf("evmConfigNTTable: NTTable record %s was not added to the IOC\n", ntTableRecordName.c_str());
 
         configureFunctionCalled = true; 
 
 
     } else {
-        errlogPrintf("evmConfigure: IOC already running, this function call causes no effect\n");
+        errlogPrintf("evmConfigNTTable: IOC already running, this function call causes no effect\n");
     }
     
 }

ts2evmApp/src/ntTable.cpp

+/**
+ * @file ntTable.cpp
+ * @author Joao Paulo Martins (joaopaulo.martins@ess.eu)
+ * @brief 
+ * @version 0.1
+ * @date 2022-08-22
+ * 
+ * @copyright Copyright (c) 2022 European Spallation Source ERIC
+ * 
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * 
+ */
+
 #include <map>
 
 #include <aSubRecord.h>

ts2evmApp/src/ntTable.h

@@ -13,10 +13,7 @@
 class ntTableEvmRecord;
 typedef std::tr1::shared_ptr<ntTableEvmRecord> ntTableEvmRecordPtr;
 
-/**
- * @brief infoTable Record Class Definition
- * 
- */
+// ntTableEvm class definition, inherited from PVRecord class
 class epicsShareClass ntTableEvmRecord :
     public epics::pvDatabase::PVRecord
 {