Experimental Physics and Industrial Control System (EPICS) Sequencer and State Notation Language Tutorial Slides

1
Experimental Physics and Industrial Control
System (EPICS)Sequencer and State Notation
LanguageTutorial Slides

• Bob Dalesio, Deb Kerstiens, Rozelle WrightOct
  1, 2001

2
Sequencer Version

• These slides describe SNL/SEQ version 1.9.5
• This version is available for downloading
  athttp//pipeline.keck.hawaii.edu3636/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
Start
Low vacuum
State A
pressure lt .0000049 Torr
Event
Transition
Open the valve
A to B
Action
High vacuum
State B
pressure gt .0000051 Torr
Close the valve
7
SNL General Structure and Syntax
program program_name declarations ss
state_set_name state state_name enter a
ction statements when (event) action_
statements state new_state_name when(event)
exit action statements state
state_name ....
8
SNL General Structure and Syntax
program name A 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
statename Is 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
• int variableIname
• short variableSname
• long variableLname
• char variableCname
• float variableFname
• double variableDname
• string variableStrname / currently limited
  to 40 characters/
• Vector types
• int arrayInamearray_length
• short arraySnamearray_length
• long arrayLnamearray_length
• char arrayCnamearray_length
• float arrayFnamearray_length
• double arrayDnamearray_length

10
Declarations - continued

• Assignment to channel access server channels
• float pressure
• assign pressure to Tank1CouplerPressureRB1
• double pressures2
• assign pressures to Tank1CouplerPressureRB1,
• Tank1CouplerPressureRB2,Tank1CouplerPressure
  RB3
• To use these channel in when clauses they must be
  monitored
• monitor pressure
• monitor pressures
• Declaring Event Flags
• evflag event_flag_name / event for state sets
  to set, clear,
• / and test
• sync pressure flag_monitor / flag monitor
  is set when pressure

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 lt 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() lt
  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
InitalState
pressure lt .0000049 RoughPump off
CryoPump on Valve open
pressure gt .0000051 RoughPump on
CryoPump off Valve closed
pressure lt .0000049 RoughPump off
CryoPump on Valve open
Low Vacuum
High Vacuum
pressure gt .0000051 RoughPump on
CryoPump off Valve closed
10 minutes RoughPump off CryoPump
off Valve closed
Fault
15
Declarations for Example
double pressure assign pressure to
Tank1Coupler1PressureRB monitor
pressure short RoughPump assign RoughPump to
Tank1Coupler1RoughPump short CryoPump assign C
ryoPump to Tank1Coupler1CryoPump short Valve a
ssign Valve to Tank1Coupler1IsolationValve stri
ng CurrentState assign CurrentState to
Tank1Coupler1VacuumState
16
State Transitions for the Example
program vacuum_control ss coupler_control stat
e init when(pressure gt .0000051) state
low_vacuum when(pressure lt .0000049)
state high_vacuum state high_vacuum when(pr
essure gt .0000051) state low_vacuum state
low_vacuum when(pressure lt
.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 gt
.0000051) RoughPump 1 pvPut(RoughPump)
CryoPump 0 pvPut(CryoPump) Valve
0 pvPut(Valve) state low_vacuum when(pr
essure lt .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(CurrentStat
e,High Vacuum) pvPut(CurrentState) wh
en(pressure gt .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(press
ure lt .0000049) RoughPump
0 pvPut(RoughPump) CryoPump
1 pvPut(CryoPump) Valve
1 pvPut(Valve) state high_vacuum when(de
lay(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 -gt example.c
• Compiles the resultant C code with the C
  compiler
• cc example.c -gt 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
• ts1gt you should get a prompt
• 2. Load the object module(
• ts1gt ld lt ltdirectory containing
  executablegt/example.o
• 3. Execute the state program
• ts1gt 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
• ts1gt seqShow

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 hv03temp1 150
• 3. Print database values using CAU
• cau get hv03temp1
• 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

• -gt seqShowProgram Name Task ID Task Name
  SS Namelights 28868216
  lights ss1
  28857812 lights_1
  switch_to_auto

24
Example of seqShow output(continued)

• -gtseqShow "lightsState Program "lights
  initial task id288682160x1b87e78 task
  priority100number of state sets2number of
  syncQ queues0number of channels16number of
  channels assigned16number of channels
  connected16options async0, debug0, newef1,
  reent0, conn1
• log file fd8 log file name"/pty/telnet.SStat
  e Set "ss1task namelights task
  id288682160x1b87e78First state
  "initCurrent state "autoPrevious state
  "autoElapsed time since state was entered 0.0
  seconds)

25
Example of seqShow output (continued)

• State Set "switch_to_autotask
  namelights_1 task id288578120x1b855d4First
  state "manCurrent state "autoPrevious
  state "manElapsed time since state was
  entered 10794.0 seconds)

26
Additional Features

• Connection management
• when ( pvConnectCount() ! pvChannelCount() )
• when ( pvConnected(Vin) )
• Macros
• assign Vout to "unitOutputV"
• (must use the r compiler options for this if
  more than one copy of the sequence is running on
  the same ioc)
• ts1gt seq example, "unitHV01"
• 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
• ts1gt 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)