1. 1 2001: Beijing State Notation Language EPICS State Notation Language (SNL) Ned D. Arnold APS (Ron Chestnut SLAC)

2. 2 2001: Beijing State Notation Language EPICS State Notation Compiler and Sequencer u Allows programming of sequential state-oriented operations to run in the IOC u The program interacts with the run-time database(s) via channel access u Latest manual : http://mesa53.lanl.gov/lansce8/Epics/sequencer/snl_1.9_man.html http://mesa53.lanl.gov/lansce8/Epics/sequencer/snl-1.9.ps http://mesa53.lanl.gov/lansce8/Epics/sequencer/snl_1.9_man.html

3. 3 2001: Beijing State Notation Language EPICS Uses u State machines u Startup sequences u Enforce prudent operational procedures u Watch for likely fault modes that are hard to detect via alarms u Implement complex closed loop control schemes u Coordinate control of multiple devices

4. 4 2001: Beijing State Notation Language EPICS Advantages u Can implement complicated algorithms u Can stop, reload, restart a sequence program without rebooting (VxWorks property) u Interact with the operator through string records and mbbo records u C code can be embedded as part of the sequence u All Channel Access details are taken care of for you u File access can be implemented as part of the sequence

5. 5 2001: Beijing State Notation Language EPICS To be compared with … u CALC records – single equation, interpreted u Database programming – complex networks u Subroutine Records – arbitrary code 10 input/outputs dbGet…. dbNameToAddr u Straight “C” code

6. 6 2001: Beijing State Notation Language EPICS Definitions u SNL : State Notation Language u SNC : State Notation Compiler u sequencer : The tool within the IOC that executes the compiled SNL code u Program : A complete SNL application consisting of declarations and one or more state sets u State Set : A set of states that make a complete finite state machine u State : A particular mode of the state set in which it remains until one of its transition conditions is evaluated to be TRUE

7. 7 2001: Beijing State Notation Language EPICS Basics u The SNL code structure follows a state transition diagram format state light_off { when (v > 5.0){ light = TRUE; pvPut(light); } state light_on } state light_on { when (v < 5.0){ light = FALSE; pvPut(light); } state light_off } light_Off state light_On state V > 5 Turn light on V < 5 Turn light off

8. 8 2001: Beijing State Notation Language EPICS Basics (cont …)  Each state has one or more when statements which specify which state to enter next if their condition is met u Action statements are executed during the transition from one state to another u Access to Process Variables via channel access is accomplished by simply assigning a PV to a sequence variable

9. 9 2001: Beijing State Notation Language EPICS A Complete State Program (with 2 state sets) program level_check float v; assign v to "ts1:ai1"; monitor v; short light; assign light to "ts1:bo1"; float vout; float delta; assign vout to "ts1:ai1"; ss volt_check { state light_off { when (v > 5.0) { /* turn light on */ light = TRUE; pvPut(light); } state light_on } state light_on { when (v < 5.0) { /* turn light off */ light = FALSE; pvPut(light); } state light_off } ss generate_voltage { state init { when ( ) { vout = 0.0; pvPut(vout); delta = 0.2; } state ramp } state ramp { when (delay(0.1) { if ((delta > 0.0 && vout >= 11.0) || (delta < 0.0 && vout <= -11.0) ) delta = -delta; /* change direction */ vout += delta; } state ramp; }

10. 10 2001: Beijing State Notation Language EPICS More Basics...  A state can have multiple when statements. The first one to be evaluated to be TRUE will be executed. This allows conditional branching within the sequence program.  When entering a state, all when conditions are evaluated in the order given in the source code  If no when condition is true, the sequence program task pends until an event occurs, which causes all when conditions to be re-evaluated u It is easy to create a loop and consume all available CPU time u When this happens, all CA clients connected to this IOC will disconnect

11. 11 2001: Beijing State Notation Language EPICS Exit{} and Entry{} u Extra Clauses which are triggered on ENTRY or EXIT from a state u Default behavior is execution ONLY when making a transition to another state u Default behavior overridden by options (-x and –e)

12. 12 2001: Beijing State Notation Language EPICS Entry and Exit example State ramp_width option –x; { entry{internal_state=RAMP_WIDTH; pvPut(internal_state); ramp_done=0;} when(ramp_done==1) { issue message; } state running when(delay(.1)) { do stuff to ramp; check for being done (ramp_done=1) } state ramp_width exit {publish information on ongoing ramp; taskDelay(1);} }

13. 13 2001: Beijing State Notation Language EPICS State Timers (delay()) u The delay( seconds ) function will test TRUE after seconds delay. u The timer starts each time the state is entered u The option –t causes the timer NOT to reset upon reentry to the same state state one option –t; { when(delay(10.5)) {timer has expired} state two when(reset==1) {do something; reset=0; pvPut(reset);} state one } state two {}

14. 14 2001: Beijing State Notation Language EPICS Example of “Multiple whens” when(interlockChasPwrBI && (gunLocal==0) && gunInterlocksRdyCC) { gunAutoStart = 0; pvPut(gunAutoStart); gunAutoStop = 0; pvPut(gunAutoStop); sprintf(seqMsg1, "Push Auto-Start to begin autostart..."); pvPut(seqMsg1); sprintf(seqMsg2, "Push Auto-Stop to begin autostop..."); pvPut(seqMsg2); % taskDelay(60); } state waitForRequest } state initialChecks { when(delay(2.0)) { sprintf(seqMsg1, "Initial Checks"); pvPut(seqMsg1); sprintf(seqMsg2, ""); pvPut(seqMsg2); % taskDelay(60); } state checks } state checks { when(interlockChasPwrBI==0) { sprintf(seqMsg1, "Electron Gun not ready..."); pvPut(seqMsg1); sprintf(seqMsg2, "Gun Interlock Chassis off "); pvPut(seqMsg2); } state initialChecks when(gunLocal) { sprintf(seqMsg1, "Electron Gun not ready..."); pvPut(seqMsg1); sprintf(seqMsg2,"Egun in local control "); pvPut(seqMsg2); } state initialChecks when(gunInterlocksRdyCC==0) { sprintf(seqMsg1, "Electron Gun not ready..."); pvPut(seqMsg1); sprintf(seqMsg2, "Interlocks not OK "); pvPut(seqMsg2); } state initialChecks

15. 15 2001: Beijing State Notation Language EPICS Other Features u Assignment of macros at program startup for multiple copies of same sequence (must specify +r compiler flag) program level_check ("unit=ts1") float v; assign v to "{unit}:ai1"; short light; assign light to "{unit}:bo1"; u Arrays (each element can be assigned to a PV) u Built-In functions (pg 17 of SNL Manual) u Dynamic assignment of PVs to variables u Connection Management and status In startup script … ld < level_check.o seq &level_check, "unit=ts1" seq &level_check, "unit=ts2"

16. 16 2001: Beijing State Notation Language EPICS Other Features u Event Flags (used to sync state sets and monitors) u evflag name; synch PV_name name; monitor PV_name; u efSet(name), efTest(name), efClear(name), efTestAndClear(name) u Escape to C code u % escapes a single line u %{ }% escapes a block of code u Log errors to a log file

17. 17 2001: Beijing State Notation Language EPICS Warnings on Events and Escaped Code u Escaped declarations are file scoped! (even if you use the +r option to create a reentrant program) u If you wish to access variables mapped to PVs in escaped code, you must say pvar->variable_name. Look at the generated “c” code if this is confusing. u Event flags are mapped to #define statements evflag namex; evflag namey; map to #define namex 1 #define namey 2 u These events are shared within one task; i.e. one seq & invocation.

18. 18 2001: Beijing State Notation Language EPICS Some TIME warnings u % TS_STAMP start_time; TS_STAMP current_time; double elapsed_time; u pvGet(pv_name); current_time = pvTimeStamp(pv_name); TsDiffAsDouble(elapsed_time,&current_time, &start_time); u Even if the code is reentrant (option +r), start_time and current_time are file-scoped. u seq &prog.o,[one parameter set] seq &prog.o,[other parameter set] Will share these variables.

19. 19 2001: Beijing State Notation Language EPICS Debugging u seqShow ioc> seqShow Program Name Task ID Task Name SS Name xx_RF_Cond10854616 xx_RF_Cond l1AutoConditioning bpmTraject10838832 bpmTrajectory bpmTrajectorySS xx_autoPha10680172 xx_autoPhasing autoPhasing 10573424 xx_autoPha_1 updatePresets xx_autoRfT10589876 xx_autoRfTiming autoRfTiming value = 0 = 0x0

20. 20 2001: Beijing State Notation Language EPICS Debugging u seqShow ioc> seqShow 10838832 State Program: "bpmTraject" initial task id=10838832=0xa56330 task priority=100 number of state sets=1 number of channels=56 number of channels assigned=56 number of channels connected=56 options: async=0, debug=0, newef=0, reent=0, conn=0 log file fd=3 log file name="/tyCo/0" State Set: "bpmTrajectorySS" task name=bpmTrajectory; task id=10838832=0xa56330 First state = "init" Current state = "waitToPlot" Previous state = "plotWithBeam" Elapsed time since state was entered = 0.4 seconds) value = 0 = 0x0

21. 21 2001: Beijing State Notation Language EPICS Debugging u seqChanShow,[“PV_name” or “-”] ioc> seqChanShow 10838832 State Program: "bpmTraject" Number of channels=56 #1 of 56: Channel name: "L1:PG1:PM1:BPM.XPOS" Unexpanded (assigned) name: "L1:PG1:PM1:BPM.XPOS" Variable name: "L1PG1PM1_X" address = 11931404 = 0xb60f0c type = float count = 1 Value = 0 Monitor flag=1 Monitored Assigned Connected Get not completed or no get issued Status=11 Severity=2 Time stamp = 05/21/99 16:43:35.085407596 Next? (+/- skip count)

22. 22 2001: Beijing State Notation Language EPICS Debugging u printf("Here I am in state xyz \n"); u string seqMsg1; assign seqMsg1 to “[PV_name]”; sprintf(seqMsg1, "Here I am in state xyz"); pvPut(seqMsg1); u Reload and restart u seqShow u td xxxxxx u ld < my_sequence_program.o u seq &my_sequence_program.o,[parameters]

23. 23 2001: Beijing State Notation Language EPICS Sequencer programs run also on Hosts u (Re)implemented by APS u Main program generated by +m option u Option –s on startup creates iocsh, which allows seqShow, etc. u ExampleApp supplied with 3.14 release describes some details

24. 24 2001: Beijing State Notation Language EPICS Examples u Control filling of PEP-II ring u Provide handshake between accelerator and experiment u Manage controlled ramping of RF processing u Manage shift summaries u Compensate for Attenuator Phase Shift when adjusted u Automatically check timing of BPM’s u E-gun startup u Modulator startup u Automatic Test Sequences (240 Inputs to the MPS) u BPM Trajectory Plot