1. Experimental Physics and Industrial Control System (EPICS) Sequencer and State Notation Language Tutorial Slides Bob Dalesio, Deb Kerstiens, Rozelle Wright Oct 1, 2001

2. Sequencer Version These slides describe SNL/SEQ version 1.9.5 This version is available for downloading at http://pipeline.keck.hawaii.edu:3636/realpublic/epics/seq/ Documentation for Version 2.0.0 which is being distributed with EPICS 3.14 is available at this same site. Version 1.9.5 has all the functionality of Version 2.0.0 except that SEQ does not run on UNIX.

3. Outline What is state notation and what function does it serve Components of a state notation program Building, running and debugging a state notation program Additional Features Some Notes on the Runtime Sequencer

4. Purpose A language to facilitate sequential programming in the EPICS real- time environment Fast execution - compiled code Programming interface to extend EPICS in the real-time environment Easy for first-time user to learn and apply

5. Common Uses of the State Notation Language Provide automated start-up sequences like vacuum or RF where subsystems need coordination Provide fault recovery or transition to a safe state Provide access to the Unix file system for save/restore or restoration of parameters on reboot Provide automatic calibration of equipment

6. State Transition Diagram State A State B Event Action Transition A to B Start Low vacuum High vacuum pressure <.0000049 Torr Open the valve pressure >.0000051 Torr Close the valve

7. SNL: General Structure and Syntax program program_name declarations ss state_set_name { state state_name { enter{ action statements } when (event) { action_statements } state new_state_name when(event) … exit{ action statements } state state_name {.... }

8. SNL: General Structure and Syntax program nameA Program contains many state sets. The program name is used as the handle to the sequencer manager for state programs. ss name{A state set becomes a task in the vxWorks environment. state name{A state is an area where the task waits for events. The related task waits until one of the events occurs and then checks to see which it should execute. The first state defined in a state set is the initial state. option flag;A state specific option when (event) {Is used to define the events for which this state waits. } state statenameIs used to define the new state after the actions are taken. entry{Do these actions on entry to this state from another state (using option -e; will do these actions even if it enters from the same state) } exit{Do these actions before exiting this state to another state. (using option -x; will do these actions even if it exits to the same state.) }

9. Declarations Occur before a state set and have a scope of the entire program. Scalar types intvariableIname; short variableSname; long variableLname; char variableCname; float variableFname; double variableDname; string variableStrname; /* currently limited to 40 characters*/ Vector types intarrayIname[array_length]; shortarraySname[array_length]; long arrayLname[array_length]; chararrayCname[array_length]; floatarrayFname[array_length]; double arrayDname[array_length];

10. Declarations - continued Assignment to channel access server channels floatpressure; assignpressure to “Tank1CouplerPressureRB1”; doublepressures[2]; assignpressures to {“Tank1CouplerPressureRB1”, ”Tank1CouplerPressureRB2”,”Tank1CouplerPressureRB3”}; To use these channel in when clauses they must be monitored monitor pressure; monitor pressures; Declaring Event Flags evflagevent_flag_name;/* event for state sets to set, clear, /* and test syncpressure flag_monitor;/* flag monitor is set when pressure /* changes (posts a monitor)

11. Events An event is the condition on which statements following a when are executed and a state transition is made Possible events: Change in value of a variable that is being monitored example: when(achan < 10.0) A timed event (not a task delay!) example: when(delay(1.5)) The delay value is in seconds. It is delclared internally as a double and constant arguments to the delay function must contain a decimal point. A delay is normally reset whenever the state containing it is exited. Use the state specific option -t to keep it from being reset when exiting to the same state..

12. Events (continued) An internally generated event (event flag) examples: when(efTestAndClear(myflag)) when(efTest(myflag)) efTest does not clear the flag. efClear must be called sometime later to avoid an infinite loop. The event flag can be set internally by efSet(event_flag_name) or if the flag is synced to a monitored channel it will be set when the channel changes. Change in the channel access connection status. examples: when(pvConnectCount() < pvChannelCount()) when(pvConnected(mychan) )

13. Actions almost any C expression switch is not implemented and code using it must be escaped. % escape one line of C code %{ escape any number of lines of C code }% Built-in action function: pvPut (variable_name); pvGet (variable_name); efSet (event_flag_name); efClear (event_flag_name);

14. State Definitions and State Transitions Low Vacuum pressure >.0000051 RoughPump on CryoPump off Valve closed pressure <=.0000049 RoughPump off CryoPump on Valve open InitalState High Vacuum pressure <=.0000049 RoughPump off CryoPump on Valve open pressure >.0000051 RoughPump on CryoPump off Valve closed Fault 10 minutes RoughPump off CryoPump off Valve closed

15. Declarations for Example double pressure; assign pressure to “Tank1Coupler1PressureRB”; monitor pressure; shortRoughPump; assignRoughPump to “Tank1Coupler1RoughPump”; shortCryoPump; assignCryoPump to “Tank1Coupler1CryoPump”; shortValve; assignValve to “Tank1Coupler1IsolationValve”; stringCurrentState; assignCurrentState to “Tank1Coupler1VacuumState”;

16. State Transitions for the Example program vacuum_control ss coupler_control { state init{ when(pressure >.0000051){ } state low_vacuum when(pressure <=.0000049){ } state high_vacuum } state high_vacuum{ when(pressure >.0000051){ } state low_vacuum } state low_vacuum{ when(pressure <=.0000049){ }state high_vacuum when(delay(600.0)){ }state fault } state fault{ }

17. States for the Example - Init state init{ entry{ strcpy(CurrentState,”Init”); pvPut(CurrentState); } when(pressure >.0000051){ RoughPump = 1; pvPut(RoughPump); CryoPump = 0; pvPut(CryoPump); Valve = 0; pvPut(Valve); } state low_vacuum when(pressure <=.0000049){ RoughPump = 0; pvPut(RoughPump); CryoPump = 1; pvPut(CryoPump); Valve = 1; pvPut(Valve); } state high_vacuum }

18. States for the Example state high_vacuum{ entry{ strcpy(CurrentState,”High Vacuum”); pvPut(CurrentState); } when(pressure >.0000051){ RoughPump = 1; pvPut(RoughPump); CryoPump = 0; pvPut(CryoPump); Valve = 0; pvPut(Valve); } state low_vacuum } state low_vacuum{ entry{ strcpy(CurrentState,”Low Vacuum”); pvPut(CurrentState); } when(pressure <=.0000049){ RoughPump = 0; pvPut(RoughPump); CryoPump = 1; pvPut(CryoPump); Valve = 1; pvPut(Valve); }state high_vacuum when(delay(600.0)){ }state fault } state fault{ entry{ strcpy(CurrentState,”Vacuum Fault”); pvPut(CurrentState); }

19. Building a state program 1. Use editor to build the source file: file name must end with ".st", e.g. "example.st". 2. “gmake” automates these steps: Runs the C preprocessor Compiles the state program with SNC to produce C code: snc example.st -> example.c Compiles the resultant C code with the C compiler: cc example.c -> example.o The file "example.o” becomes part of the application library, which is ready to be loaded by VxWorks. 3. Note: For class purposes, we will be reloading the object code as a module instead of rebooting to reload the library.

20. The Run-Time Sequencer 1. The sequencer executes the state program in the VxWorks environment. 2. The sequencer supports the event-driven execution; no polling needed. 3. Each state set becomes a VxWorks task. 4. The sequencer manages connections to database channels through "channel access". 5. The sequencer provides support for channel access (put, get, and monitor). 6. The sequencer supports asynchronous execution of delay and event flag functions. 7. Only one copy (object module) of the sequencer is required on each IOC. 8. Query commands display information about executing state programs.

21. Executing a state program Assume that VxWorks is running in an IOC and the proper database is loaded. 1. Telnet to the IOC: telnet ts1 log in ts1>you should get a prompt 2. Load the object module:( ts1> ld /example.o 3. Execute the state program: ts1> seq &example this is the program name This will create one task for each state set. 4. Exercise the program. 5. Print a summary of state programs ts1> seqShow 6. If it doesn’t work properly: Delete the tasks that were created in step 3. ts1> td "example” Go back to step 2.

22. Hints for debugging a state program 1. Use printf statements in program: printf("entering state: light_on"); 2. Manually enter database values using CAU: cau: put hv03:temp1 150 3. Print database values using CAU: cau: get hv03:temp1 150.00 4. Use special state program query commands: seqShow displays information on all running state programs seqShow "example" displays detailed information on program seqChanShow "example" /* all channels */ seqChanShow "example”,”-”/* disconnected */ displays information on all channels 5. Use spy to find a sequence with an infinite loop with no delays

23. Example of seqShow output -> seqShow Program Name Task ID Task Name SS Name lights 28868216 lights ss1 28857812 lights_1 switch_to_auto

24. Example of seqShow output(continued) ->seqShow "lights” State Program: "lights” initial task id=28868216=0x1b87e78 task priority=100 number of state sets=2 number of syncQ queues=0 number of channels=16 number of channels assigned=16 number of channels connected=16 options: async=0, debug=0, newef=1, reent=0, conn=1 log file fd=8 log file name="/pty/telnet.S” State Set: "ss1” task name=lights; task id=28868216=0x1b87e78 First state = "init” Current state = "auto” Previous state = "auto” Elapsed time since state was entered = 0.0 seconds)

25. Example of seqShow output (continued) State Set: "switch_to_auto” task name=lights_1; task id=28857812=0x1b855d4 First state = "man” Current state = "auto” Previous state = "man” Elapsed time since state was entered = 10794.0 seconds)

26. Additional Features Connection management: –when ( pvConnectCount() != pvChannelCount() ) –when ( pvConnected(Vin) ) Macros: –assign Vout to "{unit}:OutputV"; –(must use the +r compiler options for this if more than one copy of the sequence is running on the same ioc) –ts1> seq &example, "unit=HV01" Compiler options: –+r make program reentrant (default is -r) –-c don't wait for all channel connections (default is +c) –+a asynchronous pvGet() (default is -a) –-w don't print compiler warnings (default is +w) –+e eftest automatically clears flag (default is -e)

27. Additional Features(continued) Pass parameters to programs at run time: –#----- this line is executed in the st.cmd file –ts1> seq &example, "bias = 2.55" –pStr = macValueGet("bias"); /* this statement in the.st file gets value */ Access to alarm status and severity: –pvStatus(var_name) –pvSeverity(var_name) Queueable monitors -- saves monitors in queue in the order they come in -- no missing monitors. –syncQ variableName to eventFlagname [optionally the length of the queue] –pvGetQ( variableName ) removes oldest value from variables monitor queue. Remains true until queue is empty. –pvFreeQ( variable Name)