#==============================================================
#
#  Name: README
#
#  Rem:  This is the LCLS Magnet Controls
#        EPICS IOC Application 
#
#  Side: None
#
#  Auth: 28-Nov-2007, K. Luchini      (LUCHINI)
#  Rev:  dd-mmm-yyyy, Reviewer's Name (USERNAME)
#--------------------------------------------------------------
#  Mod:
#        dd-mmm-yyyy, Reviewer's Name (USERNAME)
#          coment
#
#==============================================================
#
Hardware
---------
There are currently three types of power supply controllers:
1. Ethernet Power Supply Controllers (EPSC)- for intermediate power supplies
2. MCOR Controllers - for low current power supplies. (2-types of MCOR controller)
  a) standard biRa mcor slot-0 controller. This controller has amp-32 connections from back of mcor crate
   that connect to vme scsi-ii ports on trans-300 boards (ports a and b).
  b) slac emcor slot-0 controller. This controller has an ethernet interface and runs linuxRT
3. PLCs - for Bulk power supplies and Pulsed Magnets

The PLCs and EPSCs are connected to the control system via ethernet on the LCLSINST subnet.
The Standard BiRa MCOR Controller data is controlled and monitored via VME ipac adc/dac modules.The Acromag IP231-16E
dac and Hytec IP8413 (SLAC) adc, but modules are 16-bit, 16-channe, +/-10V. Read connections using the
Acromage Trans-200 modules with SCSI-II connectors is used. A special cable is built at SLAC for the 
connection between the MCOR and the VME Trans-200 with an 36Amp(M) and a SCSI-2(M) connectors. The SLAC
MCOR Controller has an embedded processor running LinuxRT with an Ethernet interface to the control system.

   MCOR      --->       VME                                           
   +/-10V              Motorola MVME61006E-0163 (powerPC), 2-LAN ports, 1-serial
                       Micro Research PMC-EVR 230
   Power modules       Acromag AVME9670 64X IP Carrier
    +/-12A             Acromag IP231-16E Dac +/-10V,16-bit,16-channels
    +/-6A              Hytec IP8413  +/-10V,16-bit,16-channels (differential)
    +/-2A              Acromag Trans-200 with 4 SCSI-2 ports,80mm rails
 
I currently setup one ip carrier module with the Hytec ip-hy8413-adc in port-A and an Acromag ip231-16e in port-B, for 
a single MCOR crate. However, one ip carrier can handle two MCOR crates or up to 32-channels of analog I/O, using port-C
and port-D for the second adc and dac, respectively.

Network connections needed
 for VME:
   2-ethernet: LAN1 on the lclsca, LAN2 on the LCLSFBCK (if fastfeedback required). Swith port set to autonegotiate
   1-serial. Speed set to 9600, 8 data-bits, 1 stop-bit, no parity, No hw flow ctrl in/out
   1-fiber optic for the evr (multi-mode)
   1-serial connection. Speed set to 115200, 8 data-bits, 1 stop-bit, no parity (see: digi-port server and mvme6100 debug port for pinouts)
 for EMCOR
   2-ethernet: LAN1 on the lclsca, LAN2 on the LCLSFBCK (if fastfeedback required). Swith port set to autonegotiate
   1-usb. Speed set to 9600, 8 data-bits, 1 stop-bit, no parity, No hw flow ctrl in/out
   1-fiber optic for the evr (multi-mode). Does not support daisy-chaining.
   1-serial connection Speed set to 115200, 8 data-bits, 1 stop-bit,  no parity. Pinouts are setup to be straight through to a digi-port server.
 for EPSC:
   1-ethernet connection for the lclsinst subnet. Switch port must be set to 100-full. 
   1-serial  connection. Speed set to 115200, 8 data-bits, 1 stop-bit, no parity, No hw flow ctrl in/out (optional. See PCD engineer)
 for PLC (allen-bradley, beckhoff)
   2-ethernet connections. 1-ethernet on the lclsinst for the plc and 1-ethernet on the lclsutil for the touch panel.
                           Both switch ports set to autonegotiate.
   Note: for pulsed magnes, you will need a minimum of 2-fiber optic cables from EVR output trigger ports (0,1) for
   abort and standby signals. Some pulsed magnets have additional triggers required.
 for Genesys PS:
    1-serial connection.  Speed 9600 baud. Set port address to default (6). See Genesys ps documentation for cable pinouts.


Magnet Configurations
----------------------
Magnets may be configued as 
  individual magnet
  individual magnet with trim coils which are powered separately from the main
  group of magnets connected in series

It is important to note that some magnet functions, such as standardize have an additional grouping or configuration
applied (see the PRD 1.1-015).
http://www.slac.stanford.edu/grp/lcls/controls/global/subsystems/mgnt/doc/prd/1.1-015-r3-standardization.doc


Adding Magnets
==================
I. MAD DECK
1) When adding a magnet, send email to the physicists and carbon copy the following individuals:
   Mark Woodley
   Henrik Loos
   Rick Iversion
   Andrea Chan

to determine when the new magnet(s) will be added to the MAD DECK. This date MUST be prior to 
the magnet installation date. 

The new MAD DECK (output file) will need to be uploaded into Oracle, by Andrea, so that the High Level Applications,
such as LEM  (matlab,XAL) and the model serve can locate the new devices. Once a new optics deviecs have been 
added to the Oracle database (SLACDEV), the EPICS device referred to as the channel access device name (PRIM,AREA,UNIT)
MUST be manually added to Oracle by the software developer. The unit number, or location of this devices needs to be 
approvd by the ICD Naming Czars. Be aware that this work is all done on SLACDEV Oracle database preferrable, which 
will be released to procduction on the day of commissioning.This work can however be done in production, in 
coordinate with Andrea and Ellie, afterwhich care must be taken to update SLACDEV so that production and development
systems stay in synch.

Note: When the Oracle database is updated, such that then"Active" field of a devices, can be changed by the developer
to a variety of states, such as "Not Installed","Installed", "Commissioned", "Decommissioned", "No power leads",
"Removed", etc, the Oracle database  release from SLACDEV to SLACPROD must be done on the day of commissioning.

2) Send an email to Scott Anderson at MMF, and cc Henrik Loos, and ask when MMF is scheduled to measure the
new magnets. Ask Scott if he can send you the data from the measurements. Also ask where this file will
be stored (Z-drive directory), and if you will have access to this file. Note that this data file should
be added to the Oracle database as part of the magnet traveler.

3) Send an email to Henrik Loos, after the MMF data file has been received, to ask if he can generate
the magnet polynomial coefficients that will be used to convert B-field to Current. Once you get these
coefficients, and you have a EPICS device name for the magnet (DEVICE TYPE,AREA,LOCATION), update the 
magnet IOC application EPICS database file (e.g. <nodename>_poly.substitutions).

4) Determine a first pass unit number (i.e. LOCATION) for the device based on z-position.
Check the Oracel database and determine  the unit number of the optics devices that are located
on either side of the new magnet, based on Z-position. Get approval from the Naming Czars and the
area physicist regarding this unit number, before the EPICS device name is introduced into the production
control system.

5) If ps controller has a serial or ethernet interface:
    ETHERNET INTERFACE:
      EPSC
      PLC (w/touch panel)
      BECKHOFF
      EMCOR (2 lan)


   If the devices has an Ethernet interface that will connect to a network switch,
   Send email to Charlie Granieri requesting an ip address and nodename and indicate
   which subnet for this devices. If your device should not be set to autonegotiate,
   then specify the rate. Once the devices is online, make sure to verify the rate set
   on the switch.
    
   Naming Convention
      EPSC:      psc-<area>-mg<2-digit #>   Do not set to autonegotiate.
      PLC:       plc-<area>-mg<2-digit #>
      BECKHOFF:  bkhf-<area>-mg<2-digit#>
      EMCOR:     vioc-<area>-mg<2-digit#>   This is an embedded EPICS ioc.
  
   Note: the 2-digit number range is 01-99
         the ip addresses and nodenames should appear on the SLAC drawings. 

   Once the ip addresses and nodenames have been assigned forward this information
   to the Power Conversion Engineer, Briant Lam, and the Power Converison Coordinater,
   John Hugyik. In the email request, the rack location of the ps controller with the
   ethernet interface. 

   Send an email to Charlie Granieri, requesting ethernet cables to the power supply
   controllers, with the rack location of the device or to the cat6 patch panel.
   Charlie will need this information to specify his cable list.
 
   SERIAL INTERFACE:
     Genesys Power Supply
     EMCOR (debug port)

   If the devices has a serial interface that will connect to a DIGI (terminal server),
   send email to Charlie requesting a serial port in production. Send the rack location of
   the devices with the serial ports needed, and configuration (if non-standard). 

   Once Charlie has assigned the terminal servier port and configured the devices, log onto the
   terminal servier in production and update the port description for your device. Also, double
   check the port configuration.
 

6) EPICS Databasea files that must be modified when adding a new magnet:
  a) <nodename>.substitutions                      - the nodename is the ioc that will communicate with the 
                                                     ps controller. This is usually near the power supplies.
  b) <nodename>_poly.substitutions                 - polynomial coefficients for converting B-field to Current
  c) <nodename>_<mcor,epsc,plc,gene>.substitutions - low-level power supply controller database
  d) <nodename>_allstar.template                   - Add new magnet
  e) <nodename>_func.substitutions                 - Add new magnet
  f) <nodename>_lgps.template                      - If ps controller is an MCOR, add new magnet devices
  g) iocBoot/<nodename>/init_seq.cmd               - Start new sequence for maggnet
 
  if adding a new MCOR crate, then you will need to edit
  h) iocBoot/<nodename>/init_ipac.cmd              - Add init for new ipac adc and dac. If new carrier
                                                     is needed then initalize new carrier. Note that information
                                                     adc and dac is needed in the file <nodename>_mcor.substitutions.

 
Special Considerations
===========================
Wildcard function control database. A database for each machine sector, injector,li21-li30,bsy0,ltu1,und1 and dmp1
have individual files with database pvs grouping by magnet type and power supply: bend,quad,xcor,ycor,btrm and lgps.
Only magnets devices that control a power supply should be added to the following databases:

  <nodename>_allstar.substitutions 
  <nodename>_func.template


Configuartions
====================
IOC Manager     - IOCManager
Alarm Manager   - ALARMS
Alarm Handler   - AlarmConfigTop-mgnt, AlarmConfigTop-ntwk
ChannelArchiver - Send archive list to Murali Shankar.
ChannelWatcher  - Use for logging and restore as of June 2015.
  Will switching to autosave during august 2015 down.
  Update the mgntApp/srcRestore/<NODENAME>.cwsubstitutions 
  for all devices add units to mgnt_common.cwConfig  
  if the ps controller is an EPSC, add PSC unit to mgnt_epsc.cwConfig
  if the ps controlled by an EMCOR, add mcor crate to mgnt_emcor.cwConfig
  if the ps controlled by an EMCOR, add mcor crate to mgnt_mcor.cwConfig  
  if the ps controlled by a plc, add PS unit to mgnt_plc_ps.cwConfig and plc node to mgnt_plc.cwConfig and mgnt_plcAdmin.cwConfig
  if a new ioc, then add iocAdmin.cwConfig 
SCORE: Determine which area to add the magnet device. If the magnet is a string then only add the master.
SCORE Oracle Database
Aida (verify that new unit has been added to aida by using aidalist)
LEM 
Model XAL Database
LCLS Infrastructure Database
MPS
PPS 
BCS

Displays
---------
Network sector display
Event sector display
Magnet sector display by type
Magnet sector all units display
Magnet sector sector graphical display
Magnet diagnostic displays
Pulsed Magnets - may have unique displays.
lemServer.edl - This display contains all magnet devices (no LGPS)-  See william colocho

=====================================================================================
Upgrading from Standard BiRa MCOR Slot-0 Controller to SLAC EMCOR Slot-0 Controller
=====================================================================================
In Magnet IOC Application:   epics/ioc/Magnet/Magnet_new   (cvs module: Magnet)
1) Add boot directory and files in iocBoot
  vioc-<sector>-mg<xx>  - directory where xx is the mcor crate number 01-99
     Makefile              - build file. Specify ARCH (linuxRT-x86,RTEMS-beatnik,linux-x86)
     .cvsignore            - list genrated files that cvs should ignore
     st.cmd                - startup script, see vioc-li28-mg01. 
                             How you edit this file depends upon method used in 3 below.
                             Do not add the event databases until testing has completed. 
     init_seq.mcor.cmd     - script to start mcor sequences
     init_sq.epsc.mcor     - scipt to start epsc sequences

2) Edit existing iocBoot st.cmd file for existing RTEMS ioc and load only the event and iocAdmin databases
   ioc-<sector>-mg<xx>  - directory where xx is the rtems ioc number (usually 01-02)
   Note: the magnet vme iocs that do not need to pass along triggers to pulsed magnets 
   will be decommissioned during the august down.

3) Edit existing db files for RTEMS ioc.
Two methods can be done:
  Generate a separate substitutions file for each mcor crate, using the existing substitutions file
  The new mcor file (one per crate) should use the file naming convention
     vioc-<sector>-mg<xx>_mcor.substitutions   where xx is the mcor crate number 01-11
  This file should include the following templates found in mgntApp/Db/common
      mgnt_emcor_chan.template
      mgnt_emcor_controller.template
  Next, you can do one of the two methods below:

  Method 1) Edit the existing file for an RTEMS ioc. this only works for sectors with one mcor crate.
     ioc-<sector>-mg<xx>.substitutions
     changing the filee  mgnt_smps.db to mgnt_epsc_smps.db

  Method 2) Create a new file vioc-<sector>-mg<xx>.substitutions where xx is the mcor crate number 01-99.
     and include existing databases, where possible.

5) Edit ChannelWatcher srcRestore file and add mgnt_emcor.template, once instance per crate

6) Edit Archive file srcArchive to add crate PVs. Add archive list to cater so Murali can add
the pvs to the archiver when the new ioc is released to production.

8) Update IOCManager to add new mcor ioc.

9) Update AlarmConfigs-ntwk to add new IOC alarm

10) Update displays to change the diagnostic display from mgnt_mcor.edl to mgnt_emcor.edl
    mgnt_<sector>_xcor.edl
    mgnt_<sector>_ycor.edl
    mgnt_<sector>_quad.edl
    mgnt_<sector>_bend.edl
    mgnt_<sector>_all.edl    
    mgnt_<sector>_main.edl  also add new mcor ioc to summary. Add STATSUMY in calc for alarm on btn.
    mgnt_<sector>_tol.edl
    ntwk_<sector>_main.edl  add new mcor ioc


    
   

  






