Skip to content
Snippets Groups Projects
Commit 6b0c5ccf authored by Rolf Bork's avatar Rolf Bork
Browse files

Updated user manual documentation. 

git-svn-id: https://redoubt.ligo-wa.caltech.edu/svn/advLigoRTS/trunk@3321 6dcd42c9-f523-4c6d-aada-af552506706e
parent a31d0193
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/EpicsInputUse.dox
+ 1
− 0
View file @ 6b0c5ccf
......@@ -7,6 +7,7 @@ The purpose of this RCG component is to define a Contec digitial I/O module that
/// \n
/// \n
/// \n\n 2. Related Documentation \n\n
/// \ref epicsPart2 "Setting EPICS Database Fields" \n
/// \n
/// \verbatim
3. General Description and Use within an RCG model.
......
doc/EpicsOutputUse.dox
+ 1
− 0
View file @ 6b0c5ccf
......@@ -7,6 +7,7 @@ The purpose of this RCG component is to define a Contec digitial I/O module that
/// \n
/// \n
/// \n\n 2. Related Documentation \n\n
/// \ref epicsPart2 "Setting EPICS Database Fields" \n
/// \n
/// \verbatim
3. General Description and Use within an RCG model.
......
doc/rcgappdevguide.dox
+ 34
− 171
View file @ 6b0c5ccf
/*! \page userguide RCG Application Developer Guide
\section ug0 1.0 RCG Overview
The RCG uses MATLAB Simulink as a drawing tool to allow for applications to be developed via a Graphical User Interface (GUI). A basic description of
this process, the RCG itself, and resulting application software is provided in the following subsections.
\subsection ug1 1.1 Code Development
Code development is done by graphically placing and connecting blocks in the MATLAB Simulink editor. The ‘building blocks’ supported by the RCG are included in the \subpage rcgParts "CDS_PARTS.mdl" file. Parts from the CDS library are copied (drag and drop) to the user application window and then connected to show processing/signal flow.
- \ref mdlExample "Example Models"
- \ref appDev2 "Code Model General Rules and Guidelines"
- \ref rcgParts "RCG PARTS LIBRARY"
- \ref appDev3 "Code Model Compilation"
- \ref appDev4 "Code Execution"
- \ref autoMedm "Auto-generated MEDM Screens"
\subsection ug2 1.2 Code Compilation and Installation
\subsection ug3 1.3 Runtime Software
\section ug0 1.0 Introduction
\verbatim
For the development of real-time controls application software, the LIGO Control and Data Systems (CDS) group has developed an automated real-time code generator (RCG). This RCG uses MATLAB Simulink as a graphical data entry tool to define the desired control algorithms. The resulting MATLAB .mdl file is then used by the RCG to produce software to run on an Advanced Ligo (aLIGO) CDS front end control computer.
The software produced by the RCG includes:
• A real-time code thread, with integrated timing, data acquisition and diagnostics.
• Network interface software, using the Experimental Physics and Industrial Control System (EPICS) software and EPICS Channel Access. This software provides a remote interface into the real-time code.
\endverbatim
\section ug1 2.0 Document Overview
This document describes the means to develop a user application using the RCG. It contains the following sections: \n \n
• Reference Section (3): The RCG produces software which integrates with various other components of CDS software. In addition, there are various files and services which must be configured prior to code operation. These items are covered under separate documentation, listed in the reference section. \n
• RCG Overview (4): Provides a brief description of the RCG, its components and resulting code threads. \n
• Application Development (5): Provides the basics for developing an application using the RCG. \n
• Software Execution (6): Describes how to start and stop the software application. \n
• RCG Software Parts Library (7): Describes the various components supported by the RCG. \n
\n
\section ug17 3.0 References
Additional RCG design overview documentation can be found at the following links:\n
<a href="https://dcc.ligo.org/LIGO-T080135-v5">LIGO T080135 aLIGO CDS RCG Application Developers Guide in DCC</a> \n
<a href="https://dcc.ligo.org/LIGO-T0900612-v2">LIGO T0900612 aLIGO CDS Design Overview</a> \n
\ref rcgSect4 "4.0 RCG Overview" \n
\ref rcgSect5 "5.0 RCG Application Development" \n
\ref rcgSect6 "6.0 Running the RCG Application" \n
\ref rcgSect7 "7.0 RCG PARTS LIBRARY"
\section usg1 8.0 Scripting with kaTools
\ref KaTools "KaTools"
\ref rcgsg2a "Runtime Overview"
......@@ -32,16 +45,16 @@ Many examples of models built for aLIGO use can be found within the CDS SVN Repo
It is required that for each real-time Front End (FE) computer, that a special model be built to handle timing and I/O connections for all remaining user models to be run on that FE computer. This special case model is referred to as an Input/Output Processor (IOP) model.
An example of a typical IOP model is shown in the following figures, the first of which is the “top” level, the second showing the detail of one of the top level subsystem parts, and finally the third, or bottom level of the code model. Some notes on the model layout: \n
\subsection iop1 Level 1
As a general rule, the top level of all aLIGO control models should only contain a \ref ParameterUse "Parameter" block (upper left), I/O parts and then remaining subsystem top level parts (See \ref appDev2 "General Guidelines"). This allows subsystem parts to become libary parts that can be shared between control models, with the only difference being the I/O channel connections specific to that particular control model.
As a general rule, the top level of all aLIGO control models should only contain a \ref ParameterUse "Parameter" block (upper left), I/O parts and then remaining subsystem top level parts. This allows subsystem parts to become libary parts that can be shared between control models, with the only difference being the I/O channel connections specific to that particular control model.
In the case of an IOP model, the I/O parts are NOT required to have connections, unless there is an intent to use some signals within the application code part of the IOP. In the example, it can be seen that the DAC modules are not connected to anything. Binary I/O modules, however, do require a ground input, only for model parsing reasons.
It is required that the IOP model contain:
GO TIt is required that the IOP model contain:
- \ref ParameterUse "cdsParameter" Block with following settings:
- adcMaster=1: This is what defines a model as an IOP model to the RCG.
- specific_cpu=1 or not defined (as in example). The IOP must always be assigned to CPU core 1 on an FE computer. CPU 0 is reserved for Linux and CPU core 2 up to total number of available cores is reserved for user model applications.
- If this FE computer is to be connected to the Dolphin real-time network, then pciRfm=1 must be set. This is only ever set in an IOP model ie not required for user models.
- rate=64K: An IOP must always run at the ADC input clock frequency.
- All of the \ref rcgPartsIo "I/O modules" that will be installed in the I/O chassis connected to this FE computer. The primary purpose of the generated code will be to map and control all I/O devices that are to be addressed by user code running on this FE.
- All of the \ref rcgSect71 "I/O modules" that will be installed in the I/O chassis connected to this FE computer. The primary purpose of the generated code will be to map and control all I/O devices that are to be addressed by user code running on this FE.
- A Contec1616dio part. This particular module will be used to control the timing slave within the I/O chassis. It will not be available for use in user application models.
<b> NOTE: The IOP model only writes data to the DAC modules relayed from the user applications ie an IOP model can not be set up to write its own data to DAC channels. Also, I/O to binary I/O modules is done directly by the user application, with the IOP only providing memory mapping and initialization functions.</b>
......@@ -72,153 +85,3 @@ A user application model is built in a similar fashion as the IOP model, example
\image html userAppEx1.png "Example User Application Model - Top Level"
*/
/*! \page appDev2 Code Model General Rules and Guidelines
Some overview notes before starting an application development process:\n
- Only modules shown in the CDS_PARTS.mdl file may be used in the application development. Simulink native parts that may be used are shown in the CDS_PARTS >> simLinkParts window. \n
- The tool is designed to work with the LIGO CDS standard naming convention, which includes: \n
- All channel names shall be upper case. \n
- All channel names shall be of the form A1:SYS-SUBSYS_XXX_YYY where: \n
- A1 is the Interferometer (IFO) site and number, such as H1, H2, L1, M1, etc., followed by a colon (:). The IFO part of the name is set using the cdsParameters part in the application model (see example in next section). \n
- SYS is a three letter system designator, such as SUS, ISI, SEI, LSC, ASC, etc., followed by a dash (-). \n
- SUBSYS and beyond are user definable, up to a maximum channel name length of 28 characters (limit set by EPICS software). Underscores are used to further break up the name, with any number of characters in between. \n
- The Matlab file name shall be of the form: \n
- IFO name (two characters eg h1. \n
- Subsystem name (three characters) eg sus, sei, isi, etc. \n
- Remainder of name is arbitrary, but should provide a further description of the system to be controlled and must make the name unique for a particular installation. \n
- Examples for aLIGO: h1susetmx, h1susetmy, h1seiham2. The RCG will pick off the first two characters as the interferometer (IFO) name and expect the next three characters to be the system name in order to produce a channel list consistent with (2) above. \n
- Every model shall contain one, and only one, \ref ParameterUse "Parameter Block". \n
- Every model shall contain at least one ADC part. \n
- For ease of duplication, the top level of models should be limited to I/O parts, with other parts nested in subsystem components.
*/
/*! \page rcgParts RCG Parts Library
The CDS_PARTS.mdl file, supplied with the RCG code checkout, provides all parts which are supported by the RCG in a single Matlab library. Along with the supported parts, brief documentation on part usage is provided by a Matlab DOC part.
- \subpage ParameterUse "Parameter Block"
- \subpage rcgPartsIo "I/O Components"
- \subpage rcgPartsSimulink "Standard Simulink Components"
- \subpage rcgPartsEpics "EPICS Components"
- \subpage rcgPartsFilts "FILTER Components"
- \subpage rcgPartsMatrix "Matrix Components"
- \subpage rcgPartsOscPhase "Oscillator/Phase Shifter Components"
- \subpage rcgPartsWatchdogs "Watchdog Components"
- \subpage CcodeUse "User Defined C Code Modules"
- \subpage DaqChanUse "DAQ Channels"
\image html CDS_PARTS.png "RCG Parts Library"
*/
/*! \page rcgPartsIo RCG I/O Parts Library
The I/O Parts Libary within the CDS_PARTS.mdl contains all of the RCG components which support I/O modules/methods, as shown in the following figure.
- \subpage AdcUse "ADC and ADC Selector"
- \subpage DacUse "DAC Modules"
- \subpage IPCxUse "Inter-Process Communication (IPCx)"
- \subpage Contec6464DioUse "Contec DIO-6464L-PE Module"
- \subpage DioUse "Acces 24bit Binary Input Module"
- \subpage RioUse "Acces 8bit Relay I/O Module"
- \subpage Rio1Use "Acces 16bit Relay I/O Module"
\image html IoParts.png "CDS_PARTS I/O Library"
*/
/*! \page rcgPartsEpics RCG EPICS Parts Library
\section epicsPart1 Overview
The EPICS Parts Libary within the CDS_PARTS.mdl contains all of the RCG components which support EPICS, as shown in the following figure. The RCG also allows the initialization settings for EPICS Input and Output records, as described in the \ref epicsPart2 "next section".
- \subpage EpicsInputUse "EPICS Input"
- \subpage EpicsOutputUse "EPICS Output"
- \subpage EpicsMomentaryUse "EPICS Momentary"
- \subpage EpicsBinInUse "EPICS Binary Input"
- \subpage EpicsRemoteIntlkUse "EPICS Remote Intlk"
- \subpage EzcaUse "EPICS EZCA Read/Write"
- \subpage EpicsStringInUse "EPICS String Input"
- \subpage EpicsMbbiUse "EPICS Multi-bit Binary Input"
- \subpage EpicsMbboUse "EPICS Multi-bit Binary Output"
- \subpage EpicsCounterUse "EPICS Counter"
\image html EpicsParts.png "CDS_PARTS EPICS Library"
\section epicsPart2 Setting EPICS Database Fields for Epics Input and Epics Output Parts.
EPICS database records have a number of parameters, or fields, which may be set as part of the database record definition file. For each model compiled with the RCG, a corresponding EPICS database file is created for runtime support. \n
By default, the RCG only sets the precision of EPICS input and output records in the database file (PREC=3), which provides 3 decimal places of precision when viewed on an MEDM screen. \n
The RCG does allow users to define parameter fields for the EPICS Input and Output part types within the user model, as described below. A complete list of parameters supported by EPICS AO and AI record types can be found in the EPICS user guide online. \n
To define these EPICS fields:
- Place an EPICS Input or Output part into the model and provide a name for the part.
- Open the block properties window for the part. By default, the Description field provides some basic info on the part (Figure 1 below).
\image html epicsField1.png "Block Properties (Default)"
- Delete the provided Description information. (While RCG will ignore this default information, it is probably best to delete it for ease of reading later).
- Add EPICS database parameter information, as shown in Figure 2 below, in the Description area.
- Each entry must be of the form ‘field(PARAM,”VALUE”)’, where:
- PARAM = The EPICS parameter definition, such as PREC, HIGH, LOW, etc. The most commonly used are:
- PREC (Precision), number of decimal places returned to MEDM screens for viewing. Note that this does not affect the calculation precision ie all EPICS values are treated as doubles in the runtime code.
- HOPR (High Operating Range)
- LOPR (Low Operating Range)
- Alarm Severities: HHSV, HSV,LSV,LLSV.
- Alarm Setpoints: HIHI, HIGH, LOW, LOLO
- VALUE = Desired default setting, which must be in quotes.
- Alarm Severities are limited to the following:
- MAJOR
- MINOR
- INVALID
- NO_ALARM (Default, if not specified)
- Other entries listed above are all taken as floating point numbers.
- Field definition entries may be separated by white space or new lines, or both, as shown in the example below.
\b WARNING: Presently, the RCG does not perform any checking of the validity of user definitions provided with the field entries. As long as the entry is of the right form, the RCG will add it to the database definition file. Therefore, it is the user responsibility to ensure entries are correct. Entry error checking is presently being worked for RCG release V2.7 and later.
\image html epicsField2.png "Block Properties w/EPICS field entries"
*/
/*! \page rcgPartsFilts RCG FILTER Parts Library
- \subpage FiltUse "Standard IIR Filter Module"
- \subpage FiltCtrlUse "Filter Module w/Control"
- \subpage FiltCtrl2Use "Filter Module w/Control 2"
- \subpage FiltPolyphaseUse "Polyphase FIR Filter Module"
- \subpage trueRmsUse "True RMS"
- \subpage ExcTpUse "GDS EXC/TP"
- \subpage FiltBiquadUse "Biquad IIR Filter Module"
\image html filterMods.png "CDS_PARTS FILTER Library"
*/
/*! \page rcgPartsSimulink RCG Simulink Parts Library
The Simulink Parts Libary within the CDS_PARTS.mdl contains all of the standard Matlab parts which are supported by the RCG, as shown in the following figure.
- \subpage UnitDelayUse "Unit Delay"
- \subpage SubsystemUse "Matlab Subsystem"
- \subpage MathFuncUse "Math Function"
- \subpage FcnUse "Matlab Fcn"
- \subpage GotoFromUse "GOTO/FROM"
\image html simParts.png "Simulink Library"
*/
/*! \page rcgPartsMatrix RCG Matrix Parts Library
- \subpage MuxMatrixUse "MuxMatrix"
- \subpage FiltMuxMatrixUse "Filter MuxMatrix"
- \subpage BitWordUse "Bit2Word and Word2Bit"
\image html MatrixParts.png "Matrix Library"
*/
/*! \page rcgPartsOscPhase RCG Oscillator/Phase Shifter Library
- \subpage PhaseUse "Phase"
- \subpage WfsPhaseUse "WFS Phase"
- \subpage OscUse "Oscillator"
- \subpage NoiseUse "Noise Generator"
- \subpage SatCountUse "Saturation Counter"
\image html OscPhase.png "OSC/Phase Library"
*/
doc/top.dox
+ 1
− 1
View file @ 6b0c5ccf
......@@ -14,7 +14,7 @@ This documentation is divided into the following sections:
*/
/*! \page intro CDS Overview Documentation
The Control and Data System (CDS) Real-time Code Generator (RCG) software was developed for the aLIGO project. \n
Related Documents \n
System hardware/software overviews may be found in the DCC. Two such documents are linked below: \n\n
<a href="https://dcc.ligo.org/cgi-bin/private/DocDB/ShowDocument?docid=60665">LIGO P1100052 New Control and Data Acquisition System in the Advanced LIGO Project</a> \n
<a href="https://dcc.ligo.org/cgi-bin/private/DocDB/ShowDocument?docid=7834">LIGO T0900612 aLIGO CDS Design Overview</a>
*/
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment