0. BASIC Channel Access INTEROP
===============================

EPICS V4 client side commands support both the new protocol PvAccess,
and Channel Access.  However, by default V4 commands try only
PvAccess, so if you want to use CA, you must use "-p ca" or the full
URI style syntax of EPICS V4.

$ eget -p ca EVNT:SYS0:1:LCLSBEAMRATE
0                            [ok, we're not presently running the accelerator]

eget -p ca QUAD:LTU1:880:BACT

eget ca:///EVNT:SYS0:1:LCLSBEAMRATE

eget ca:///QUAD:LTU1:880:BACT

pvget -p ca WIRE:LTU1:755:{X,Y,U}WIRE{INNER,OUTER}  WIRE:LTU1:755:{X,Y,U}WIREOFFSET | sort



1. MODEL DATA
=============

Model data is example of using arguments to a PV. Arguments are given as
name value pairs (optionally with '=' between them).

Note that argument names *are case sensitive!* b != B. Also, if you
get the name wrong, the server won't complain, will ignore the invalid
argument. However, I have made MEME argument values case insensitive.

Both RMAT and TWISS take:
Name  Value             Default    Comment
----  ----------------  ---------  ------------------------------------------
run   <integer>         1          Run id number, as given by the model GUI.
                                   1==most recent gold, the default 
type  extant | design   extant     From real PV values (extant) or from Design 
Pos   beg | mid | end   end        From where in multi-component elements, the
                                   beginning, middle or end
mode  5 | 55 | 53 | 52  5          The timing mode. 5 for LCLS full machine.

RMAT PVs additionally take:
Name  Value             Default    Comment
----  ----------------  ---------  ------------------------------------------
b     device name       none       RMAT of A to B is returned
posb  beg | mid | end   beg        


1.1. TWISS PARAMETERS
---------------------

# Twiss parameters at device (extant by default)
$ eget -s XCOR:LI24:900:TWISS
non-normative type
structure 
    double energy 5.00512
    double psix 37.7625
    double alphax 13.6562
    double betax -2.78671
    double etax -0.00698294
    double etaxp 0.00107115
    double psiy 31.9488
    double alphay 116.762
    double betay 5.2592
    double etay 0
    double etayp 0
    double z 2438.72
    double leff 0
    double sleff 0
    int ordinality 1332


# Compare design to existing
eget -s XCOR:LI24:900:TWISS -a type=design

# Twiss at middle of a quad
eget -s QUAD:LI28:901:TWISS -a type=extant -a pos=mid


1.2. R MATRICES 
---------------

1.2.1. R matrix of one element

$ eget -s QUAD:LTU1:880:RMAT             ("classic" syntax)
    -0.156946      -0.15959             0             0      0.391116    0.00540698
     0.0133542     0.0110122             0             0    -0.0173222   -0.00021337
  -1.05117e-06  -1.98485e-07    -0.0074217      0.479216   0.000110175   1.87252e-06
   1.12246e-07   2.11945e-08  -5.16277e-05    -0.0523249  -1.17647e-05   -1.9995e-07
  -0.000522173   -0.00039278    2.5574e-08   3.49462e-08    -0.0174609  -0.000185892
     0.0346964    0.00655144             0             0      -3.63658    -0.0618066
     
eget pva:///QUAD:LTU1:880:RMAT?        (URI syntax)

eget pva://mccas0.slac.stanford.edu:39633/QUAD:LTU1:880:RMAT?   (URI with direct address)

eget -s QUAD:LTU1:880:RMAT -a type design

eget -s QUAD:LTU1:880:RMAT -a run=46696

eget -s QUAD:LTU1:880:RMAT -a run=46696 -a pos=mid

eget pva://mccas0.slac.stanford.edu:39633/QUAD:LTU1:880:RMAT?type=design   


1.2.2. R matrix from A to B. Basis of steering, bumps etc.

$ eget -s XCOR:IN20:491:RMAT -a b BPMS:IN20:525
      0.669591      0.694604             0             0  -3.08532e-19   2.41325e-19
     -0.570851      0.901275             0             0  -1.23627e-19   1.45491e-19
             0             0       1.33379      0.966896             0             0
             0             0      0.358415       1.00957             0             0
  -2.29302e-24   8.92892e-20             0             0             1   1.20724e-05
   1.00974e-28             0             0             0             0             1


eget -s XCOR:LI24:900:RMAT -a b=BPMS:LI25:901 -a type=design


1.3. MODEL DATA OF WHOLE MACHINE
--------------------------------

PVs named MODEL:* give data for whole beamlines. These PVs don't take
arguments. Rather there are a number of PVs for each major combination
of parameter kind (Rmat, Twiss), type (extant, design), beamline
etc. See ds example below to get a list of these MODEL Pvs.

# R-matrices of all devices from Cathode to dump, plus devices names,
  elements names, S etc, sorted by S.
eget -s MODEL:RMATS:EXTANT:FULLMACHINE

# R-matrics computed from nominal design model, but from Cathode to
  end of the 52 line
eget -s MODEL:RMATS:DESIGN:CATHODETO52SL2

# Courant-synder params, plus Energy and a few other things
eget -s MODEL:TWISS:EXTANT:FULLMACHINE

Many others not shown here; get complete list with "eget -s ds -a
name=MODEL:%"


2. MISCELLANEOUS GENERAL LCLS DATA
==================================

Information about devices and infrastructure of LCLS as a whole, is
available though EPICS V4 PVs. These PVs are named in general starting
"LCLS". Most of them result in large tables of device and element data
from Oracle.

(with a wide window, say 120 chars, this will fit)

# All active elements and devices, sorted by S (element name, device
  name, S position, whether obstruction)

$ eget -s LCLS:ELEMENTS 
             ELEMENT          ELEMENT_TYPE     EPICS_DEVICE_NAME             S_DISPLAY           OBSTRUCTION
               SOL1BKS                   MAD     - NO EPICS NAME -                 5e-10                     N
              CATHODES                   MAD     - NO EPICS NAME -                 1e-09                     N
                 CQ01S                   MAD     - NO EPICS NAME -               0.19601                     N
                 SOL1S                   MAD     - NO EPICS NAME -               0.19601                     N
                 XC00S                   MAD     - NO EPICS NAME -               0.19601                     N
                 YC00S                   MAD     - NO EPICS NAME -               0.19601                     N
                 SQ01S                   MAD     - NO EPICS NAME -               0.19601                     N
                YAG01S                   MAD     - NO EPICS NAME -               0.74899                     N
                 FC01S                   MAD     - NO EPICS NAME -                   0.8                     N
               CATHODE                   MAD         CATH:IN20:111                2014.7                     N
                SOL1BK                   MAD         SOLN:IN20:111                2014.7                     N
                  CQ01                   MAD         QUAD:IN20:121                2014.9                     N
                  SOL1                   MAD         SOLN:IN20:121                2014.9                     N
                  XC00                   MAD         XCOR:IN20:121                2014.9                     N
      ... (many rows snipped)
      
# All elements in general, sorted by device name
eget -s LCLS:ELEMENTINFO

# All Beam Synchronous PV "ROOTNAMES", with areas, Z and element name, sorted by linac Z
eget -s LCLS:BSA_PVS

Many others not shown here, see "eget -t -s ds -a name=LCLS:%"


3. DIRECTORY SERVICE (DS)
=========================
The data sources for the directory service are the IOC input files (for PVnames) and
the "lines" files emitted by the new MEME model system, see [2]. There you'll find
the tags used for line names, element names, element types etc.

# The names of PVs of a device, by giving the device name pattern:

$ eget -s ds -a name=XCOR:LI21:135:% 
                                  name
                  XCOR:LI21:135:ABORT
                 XCOR:LI21:135:ACCESS
              XCOR:LI21:135:ALLFUNCGO
                   XCOR:LI21:135:BACT
                 XCOR:LI21:135:BACTFO
             XCOR:LI21:135:BACTLIMITS
                 XCOR:LI21:135:BADIFF
... (many rows snipped)

The PV names of BDES PVs matching regular expression (restrict to sectors LI25-LI29)
eget -s ds -a regex='XCOR:LI2[5-9]:.*:BDES'
 
# The device names matching a wildcard pattern
eget -t -s ds -a name=XCOR:LI21:% -a show=dname

The device names of devices in L1
(DS only knows area tags like L1 for modelled devices, see modelled device topology of LCLS [1])
# eget -t -s ds -a lname L1 -a show=dname

# Of which lines is the line L1 a subline
eget -t -s ds -a tag=L1 -a show=lname
 
# The device names matching a pattern, that are also in a given line (L2)
eget -t -s ds -a name=XCOR:LI21:% -a show=dname -a lname L2

# Device name, given element name
eget -t -s ds -a tag=XC05 -a show=dname

# Element names given PV name pattern
eget -t -s ds -a name=XCOR:LI21:% -a show=ename

# So far teh ds can only outut one column, so a table of device names and element names is clumsy,
# but you can do it. Here's element names for all the devices PVs matching WIRE:LTU1:%:
eget -ts ds -a name WIRE:LTU1:% -a show dname | xargs -tI{} eget -ts ds -a dname {} -a show ename

# Names of devices only in the Dog Leg, sorted by z
eget -t -s ds -a tag=DL1 -a name=XCOR:% -a sort=z -a show=dname

# Verify a given PV name (uri syntax)
eget pva:///ds?name="QUAD:LI28:901:BDES"

# BPM X pv names, of BPMs in DL1, sorted by z 
eget -t -s ds -a tag=DL1 -a name=BPMS:%:X -a sort=z    

# Get device names of BPMS in DL1, and their values using eget
eget -t -s ds -a tag=DL1 -a name=BPMS:%:X -a sort=z | eget -p ca -f -

# X correctors and BPMS in DL1, showing use of regular expression
eget -s ds -a name='(XCOR|BPMS):.*' -a tag=DL1 -a show=dname -a sort=z

# QUAD polynomial PVs in LTU
eget -t -s ds -a tag=LTU -a name='QUAD:.*:POLYCOEF'

# Get PV names relating to LCLS global data
eget -t -s ds -a name=LCLS:%

# What's the device name of an element?
eget -s ds -a ename=XC06 -a show dname

# What's the BDES PV name of an element?
eget -s ds -a ename=XC06 -a name=%:BDES

# What's the element name of a device?
eget -s ds -a dname=XCOR:IN20:491 -a show ename

# Even, what's the element of a given PV?
eget -s ds -a name=XCOR:IN20:491:BDES -a show ename

# What are the device names of the instruments in the laser heater line?
$ eget -s ds -a etype INST -a tag LSRHTR -a show dname
           name
  DUMP:IN20:999
   HTR:IN20:467
  STPR:IN20:551

# Names of all instrument elements in machine, sorted by Z
eget -s ds -a etype INST -a show ename -a sort z 

# What are the element names of the instruments in the laser heater line?
$ eget -s ds -a etype INST -a tag LSRHTR -a show ename
    name
  HTRUND
    RST1
    SDMP

Get sets of PV values 
----------------------

# Verify that all PVs of a system actually exist. In this example, use bash expansion to
create the expected set of PV names, then verify them all by asking pvget to get their values:

$ pvget -p ca WIRE:LTU1:{715,735,755,777}:{X,Y,U}WIRE{INN,OUT}ER

# If you don't know the names, ask the directory service. This gets the INNER and OUTER PVs in X and Y
# for a set of all wire scanners in LTU: 
$ eget -ts ds -a name "WIRE:LTU1:%:(X|Y|U)WIRE(INN|OUT)ER" | eget -p ca -f -

# In general, first search for PV names with "eget -s ds", and pipe the output to 
# pvget or eget to get PV values. See examples below:

# Get PV names. Use eget transpose to get array
eget -ts ds -a name 'XCOR:LI22:%:BDES' -T            
XCOR:LI22:202:BDES XCOR:LI22:302:BDES XCOR:LI22:402:BDES XCOR:LI22:502:BDES XCOR:LI22:602:BDES XCOR:LI22:702:BDES XCOR:LI22:802:BDES XCOR:LI22:900:BDES

# Get PV values of PVs whose names match wildcard
pvget -p ca `eget -ts ds -a name 'XCOR:LI22:%:BDES' -T `
XCOR:LI22:202:BDES             -0.000973934
XCOR:LI22:302:BDES             0.00490518
XCOR:LI22:402:BDES             -5.82456e-05
...


# Get polynomial values too. Since they're fields, and ds doesn't know fields, I have
# to add that with xargs 
eget -t -s ds -a tag=LTU -a name='QUAD:.*:POLYCOEF' | xargs -tI{} eget -p ca {}.{A,B,C,D}

# A recent search for invalid data in LTU corrector field PVs
eget -tTs ds -a name %COR:LTU%:%:%DES | eget -p ca -f - | grep nan
XCOR:LTU1:558:BDES nan
XCOR:LTU1:558:IDES nan 

# A recent search for invalid CALBOK fields:
$ eget -t -s ds -a name='%COR:.*:CALBOK' | xargs -I{} eget -p ca {}.{SEVR,STAT} | grep INVALID 
XCOR:LI21:275:CALBOK.SEVR INVALID
XCOR:LI27:202:CALBOK.SEVR INVALID
XCOR:LI27:302:CALBOK.SEVR INVALID
...

# To get values of RPC style PVs (those that take arguments) whose names match wildcard,
use xargs (since eget does not support (yet) streaming RPC Pvs):
eget -s ds -a regex='XCOR:LI2[5-6]:.*:TWISS' | xargs -I{} eget -s {} -a type=design

# Get R-mats of all quads in LI21 (careful, will be problematic in IN20
# since there are QUAD devices that are not online modelled). 
eget -ts ds -a name QUAD:LI21:%:RMAT | xargs -tI{} eget -s {}

# Find the PV that says when slotted foil has finished moving. First find
# PVs with FOIL in their name, then having found all the PV names, see
# their values. 
eget -s ds -a name FOIL%
eget -ts ds -a name FOIL:LI24:807% | eget -p ca -f -

# Get a summary of all the PV values of a troublesome WIRE motor:
[physics@opi11 ~/greg/Development/ws]$ eget -ts ds -a name "WIRE:LTU1:755:MOTR%" | eget -p ca -f -
WIRE:LTU1:755:MOTR 550
WIRE:LTU1:755:MOTR_ENABLED_STS OFF
WIRE:LTU1:755:MOTR_ERROR_STS ERROR
WIRE:LTU1:755:MOTR_ERR_ACK_CMD NO ACK
WIRE:LTU1:755:MOTR_FATAL_ERR_STS OK
WIRE:LTU1:755:MOTR_HOMED_STS HOMED
WIRE:LTU1:755:MOTR_HOME_CMD OFF
WIRE:LTU1:755:MOTR_HOMPOS 550
WIRE:LTU1:755:MOTR_INIT Standby
WIRE:LTU1:755:MOTR_LTIMEOUT 20
WIRE:LTU1:755:MOTR_MOTION_ACT_STS OK
WIRE:LTU1:755:MOTR_PIDOFF 0
WIRE:LTU1:755:MOTR_PWR_SET ON
WIRE:LTU1:755:MOTR_RETRACT Standby
WIRE:LTU1:755:MOTR_SPC_MODE_CMD MAXv
WIRE:LTU1:755:MOTR_SPC_MOTION_ACT_STS POS
WIRE:LTU1:755:MOTR_STATE_ON_SEQ 0
WIRE:LTU1:755:MOTR_STATE_SEQ 0
WIRE:LTU1:755:MOTR_SWITCH_ON_CMD ON
WIRE:LTU1:755:MOTR_TIMEOUT 45
WIRE:LTU1:755:MOTR_TIMEOUTEN Enabled

# Poor man's edm diagnostic display to do the above updating
xterm -e watch -d 'eget  -ts ds -a name "WIRE:LTU1:755:MOTR%" | eget -p ca -f -' &

# Watch changes to PVs relevant to quad field value
watch -n 1 -d 'eget  -ts ds -a name "QUAD:LTU1:595:B%" | eget -p ca -f -'

# Get two or more list of things and "paste" together columns. This does device names and their Z.
 This example lists the device names with their element names of wires:  
  1. First make your 2 (or more queries). 
    eget -s ds -a tag WIRE -a show dname
    eget -s ds -a tag WIRE -a show ename
  2. Then get the command number of those two commands using "history"
    history 3
     769  eget -s ds -a tag WIRE -a show dname
     770  eget -s ds -a tag WIRE -a show ename
     771  history 3
  3. Then reexecute the egets together using paste:
    paste <(!769) <(!770)

# Or do it all in one long command. This gets names and z locations.
paste <(eget -ts ds -a regex "BPMS:LTU1:.*" -a show dname) <(eget -ts ds -a regex "BPMS:LTU1:.*" -a show z)

# Of course, we could have done the element name and device name thing 
# by just getting LCLS:ELEMENTS and grepping:
eget -s LCLS:ELEMENTS | grep WIRE


4. ARCHIVE DATA
===============
NOTE1: The archive service is designed to get PV data of any type efficiently, and can get data 
of more than one PV in a single call, even if they're of mixed types. That makes its command
line interface a bit unfriendly, but still usable.
NOTE2: For efficiency, the archive service retrieves data in seconds (and nanoseconds) past epoch.
Because programmers believe time began with unix, the epoch started at 4 PM on Dec 31st 1969.
You can convert the outputs of secondsPastEpoch with unix date command. eg

date -d @0
Wed Dec 31 16:00:00 PST 1969

date -d @1458526772
Sun Mar 20 19:19:32 PDT 2016 

# Get the default amount of archived data (8 hours) for a single PV. BDES rarely change, so, eg:  
eget -s hist -a pv=QUAD:IN20:425:BDES

eg [physics@lcls-srv01 ~/greg]$ eget -s hist -a pv=QUAD:IN20:425:BDES 
non-normative type
epics:nt/NTComplexTable:1.0 
    string[] labels [secondsPastEpoch,values,nanoseconds,severity,status]
    structure value
        long[] secondsPastEpoch [1458526772]
        double[] values [-4.81026]
        int[] nanoseconds [747002095]
        int[] severity [0]
        int[] status [0]

[physics@lcls-srv01 ~/greg]$ date -d @1458526772
Sun Mar 20 19:19:32 PDT 2016

# Get the last 1 minute of a single scalar PV
eget -s hist -a pv=QUAD:IN20:425:BACT -a from="1 minute ago"

Decode Dates with [physics@lcls-srv01 ~/greg]$ date -d @1458526772
Sun Mar 20 19:19:32 PDT 2016

[physics@lcls-srv01 ~/greg]$ eget -s hist -a pv=QUAD:IN20:425:BDES 
non-normative type
epics:nt/NTComplexTable:1.0 
    string[] labels [secondsPastEpoch,values,nanoseconds,severity,status]
    structure value
        long[] secondsPastEpoch [1458526772]
        double[] values [-4.81026]
        int[] nanoseconds [747002095]
        int[] severity [0]
        int[] status [0]

# Get bdes and bact in one go
eget -s hist -a pv=QUAD:IN20:425:BACT,QUAD:IN20:425:BDES -a from '5 minutes ago’

# Even get a waveform, a fast moving PV and a slow moving PV in one go.
eget -N -s hist -a pv=CUD:MCC0:BPMSWF:WAVEFORM11,QUAD:IN20:425:BACT,QUAD:IN20:425:BDES -a from="1 minutes ago"

# Archiver "operators" are supported by opetator name and pvname in parenthesis. Use quotes since
parethesis will otherwise be interpretted by the unix shell, not by the meme service.
eget -N -s hist -a pv="mean(QUAD:IN20:425:BDES)"


5. EPICS V4 METADATA
====================

pvlist tells you information about the EPICS V4 servers and their PVS which are on the network.

$ pvlist
GUID 0x41A898A257D34E12B048D596, version 1: tcp@[134.79.151.36:56765]
GUID 0x8CB4FBCB467E4AAF85CBFB99, version 1: tcp@[134.79.151.36:41930]
GUID 0xA7D85FBAF71845B4BB6E060D, version 1: tcp@[134.79.151.36:39633]
GUID 0xB075C37C347D46C883E18B52, version 1: tcp@[134.79.151.36:5055]

With argument of address, it gives PVs known by the server at that address:

$ pvlist 134.79.151.36:41930
ds                                 [the directory service, whose PV name is "ds"]

$ pvlist 134.79.151.36:39633
....                               [the optics serivce, giving many PVs (of type RPC)]
BPMS:LI25:901:TWISS
BPMS:LI26:701:TWISS
QUAD:LI28:301:TWISS
YCOR:LI27:503:TWISS
YCOR:UND1:1880:RMAT
KLYS:LI27:41:RMAT

You can see at a glance which servers are doing what with this. Clumsy but works:
pvlist | awk '{print substr($2,0,length($2)-1)}' | xargs -tI{} -n 1 sh -c 'pvlist {} | head -n 10'


[NOTE though that all such names should also be available through the directory service,
pvlist is really for diagnostics of the pv servers themselves]


[1] http://www.slac.stanford.edu/grp/ad/model/lcls.html#visualizations
[2] Device topologies http://www.slac.stanford.edu/grp/ad/model/output/lcls/latest/opt/LCLS_lines.dat