Translation Table

Introduction

The translation table is responsible for converting digitized values indexed by Crate, Slot, Channel into detector specific indexing. For example, BCAL: Module, Layer, Sector, End. Over 27k channels are defined for the GlueX detector with each subsystem having its own natural indexing system. The BCAL, for instance requires 4 indices (Module, Layer, Sector, End) while the Start Counter requires only one (Sector). This page provides information on the Translation Table including how to access it and how to change it.

History

The origin of the TT data was a large Excel Spreadsheet maintained by Fernando Barbosa in DocDB with document ID=2293. Scripts were written to read from this and write the information into a SQLite DB file. The SQLite DB file was then modified to include information formatted in a way convenient for use in the control system applications. This single SQLite file now serves as the definitive source of translation table information for both the controls and DAQ electronics. The file is kept in the subversion repository here:

https://halldsvn.jlab.org/repos/trunk/controls/epics/app/hvCaenApp/src/tt.db

This, however, is not the end of the story. Offline software requires a history mechanism for the TT so if values are changed (e.g. a cable is swapped during a maintenance period), then a new version can be used without preventing us from processing data taken with the old TT. Thus, for the purposes of Offline Software, the TT is converted into an XML file and stored in the CCDB. This also makes it easily accessible to offline software using the existing CCDB interface. In order to put the TT into the CCDB, it must first be converted into XML using one script and then inserted using another script. It is important to emphasize that the above mentioned SQLite file should be maintained as the definitive source of TT information, even for the offline software. If a change needs to be made, it should be made to that file and then regenerate the tt.xml file from that. Don't just modify a tt.xml file downloaded from the CCDB and reinsert it!

The addition of HV and LV channel info that supplemented what was found in the SpreadSheet means some care must be taken to preserve that information in the event that modifications to the SpreadSheet itself are made. A set of maintenance scripts has been written and are used to allow changes in the original SpreadSheet to be propagated into the SQLite file while preserving the controls info. Adding to the complexity of the system is a convention for assigning the rocid values that was adopted by the Trigger and DAQ groups. This requires modifying the SQLite DB to match that numbering scheme. All of this makes for a fairly complicated system, mainly due to having multiple sources of information. Because the amount of data is quite large and spread over a number of tables, updates must often be done via scripts, and the integrity of the data confirmed by scripts.

Implementation

Generating and Verifying

To generate a new TT from existing resources and distribute it for consumption, you must follow the procedure below.

1. Checkout the TT package from the repository:

> svn co https://halldsvn.jlab.org/repos/trunk/online/packages/TranslationTable
> setenv TTT $PWD/TranslationTable

2. Checkout a copy of the current SQLite file from the repository. (We must checkout the entire source directory so that the modified file can be committed back to the repository later.)

> svn co https://halldsvn.jlab.org/repos/trunk/controls/epics/app/hvCaenApp

3. Download the latest version of the Excel SpreadSheet from the DocDB (GlueX-doc-2293)

4. Use the xlsx2csv.py script to convert the Excel spreadsheet in CSV format

> $TTT/xlsx2csv.py -s 0 Crate\ \&\ Chassis\ -\ Channel\ Assignments.xlsx > tt.csv

5. Use the tt_csv2db.py script to convert the CSV file into an SQLite DB file

> $TTT/tt_csv2db.py tt.csv

6. Use the tt_fix_rocids.py script to adjust the rocid values to the numbering scheme used by the DAQ system. These should not ever change, but if they did, one would need to update the script accordingly. Details on how to do this are given in the comments at the top of the script.

> $TTT/tt_fix_rocids.py tt.db

7. Use the tt_copy_controls.py script to copy the Controls information from the existing SQLite file (checked out in step 2.)

> $TTT/tt_copy_controls.py tt.db hvCaenApp/tt.db

8. Verify the new SQLite file's changes against the old one using the tt_diffdb.py script. There is a lot of output so check it over carefully!

> $TTT/tt_diffdb.py tt.db hvCaenApp/tt.db

9. Use the tt_db2xml.py script to generate an XML file for use in the offline

> $TTT/tt_db2xml.py tt.db

10. Add the XML file to the CCDB using the add_custom_data.py script.
WARNING: Without modification, this script will write the file "tt.xml" into the MySQL-backed CCDB regardless of what your environment is set to! It will also write it to cover all run numbers (0 to infinity). You will need to MODIFY THE SCRIPT BY HAND to change these defaults.

> $TTT/add_custom_data.py

11. Commit the new SQLite file to the subversion repository. Make sure to include a detailed description of what changes were made in the subversion commit log

> cp tt.db hvCaenApp/tt.db
> cd hvCaenApp
> svn commit tt.db

12. You should notify the appropriate groups to make sure people are aware of the change. Consider e-mailing the halld-controls@jlab.org and halld-offline@jlab.org mailing lists.

Controls

The Controls Group implemented a table named Detector_Hierarchy and added two columns to the Crate table ("host" and "IP") and one column to the Channel table ("enable"). In addition some other modifications were needed including additional rows in the Channel table and adjustment of slot values in the Module table. The slot values mainly consist of shifting them down by one since most crates start numbering slots at "0".

In order to preserve this information if a new SQLite file is created, a script is used to copy it from the existing SQLite file into the new one. This is done using the script:

https://halldsvn.jlab.org/repos/trunk/online/packages/TranslationTable/tt_copy_controls.py

If this is done, be sure to use the tt_diffdb.py script to check the differences and ensure any found are correct before committing the new version to the repository.

Useful Links

The following are some useful links:

• scripts in svn repository:
  https://halldsvn.jlab.org/repos/trunk/online/packages/TranslationTable

Visual translation table broswer

• Visual translation table broswer