source: specdomain/src/specdomain/test/shutter.mac @ 963

Last change on this file since 963 was 963, checked in by jemian, 10 years ago

refs #8, big progress today, now able to get ReST-formatted extended comments from SPEC .mac files into Sphinx output using autodoc and subclassing the autodoc.Documenter class for SPEC.

Also, breaking up the test document into parts to make it easier to follow.

  • Property svn:eol-style set to native
File size: 16.4 KB
Line 
1
2# $Id: shutter.mac 907 2012-06-11 22:53:33Z jemian $
3# from Christian Schlepuetz (formatted for RoboDoc)
4
5#==============================================================================
6#%+H* common/shutter
7#     ==============
8#
9# NAME
10#   shutter.mac
11#
12# SUMMARY
13#   Commands to control a fast photon shutter.
14#
15# DESCRIPTION
16#   The macro causes the fast photon shutter to be opened immediately prior to
17#   any count command, and closed again upon its completion. A configurable
18#   delay time assures that the shutter is fully open before issuing the
19#   count command.
20#   The photon shutter is controlled via an EPICS binary output channel, and
21#   the shutter status is optionally monitored via a binary input channel (in
22#   which case the delay time is not used, but the monitor signal is used to
23#   check for completion of the opening process).
24#
25# AUTHOR
26#   Christian M. Schlepuetz (CS, cschlep)
27#
28# CREATION DATE
29#   2004/11/06
30#
31# COPYRIGHT
32#   Copyright 2006-2011 by the above authors (see AUTHOR/AUTHORS)
33#
34#   This program is free software: you can redistribute it and/or modify
35#   it under the terms of the GNU General Public License as published by
36#   the Free Software Foundation, either version 3 of the License, or
37#   (at your option) any later version.
38#
39#   This program is distributed in the hope that it will be useful,
40#   but WITHOUT ANY WARRANTY; without even the implied warranty of
41#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
42#   GNU General Public License for more details.
43#
44#   You should have received a copy of the GNU General Public License
45#   along with this program.  If not, see http://www.gnu.org/licenses/.
46#
47# VERSION
48#   $Date: 2010-11-04 19:06:06 -0400 (Thu, 04 Nov 2010) $
49#   $Author: cschlep $
50#   $URL: file:///data/svn/software/spec/trunk/common/shutter.mac $
51#   $Revision: 17 $
52#
53# DEPENDENCIES
54#   Chained macro definitions affected by this macro:
55#   - user_precount
56#   - user_getcounts
57#   - cleanup_always
58#
59# HISTORY
60#   2004/11/06 (CS):
61#   - modified the first original version to comply with naming and format
62#     conventions
63#   - implemented help-file support and wrote help texts.
64#
65#   2010/03/30 (CS):
66#   - added the following global variables to make macro more easily portable:
67#
68#     SHUTTER_CONTROL_PV      # EPICS PV name for the shutter control (bo)
69#     SHUTTER_CONTROL_OPEN    # EPICS control value for open shutter
70#     SHUTTER_CONTROL_CLOSED  # EPICS control value for closed shutter
71#     SHUTTER_STATUS_PV       # EPICE PV name for the shutter status (bi)
72#     SHUTTER_STATUS_OPEN     # EPICS status value for open shutter
73#     SHUTTER_STATUS_CLOSED   # EPICS status value for closed shutter
74#     SHUTTER_IS_ON           # flag for automatic shutter control
75#     SHUTTER_SLEEP_TIME      # SPEC sleep time after opening shutter
76#
77#   2010/07/23 (CS):
78#   - added SVN keywords (replacing CVS keywords)
79#
80#   2011/12/19 (CS):
81#   - reformatted code documentation to work with ROBODoc
82#   - added shutter_setup with following internal macros:
83#     * _shutter_print_setup
84#     * _shutter_set_option
85#     * _clear_screen
86#   - replaced SHUTTER_STATUS* with SHUTTER_MONITOR*
87#   - replaced global variables _OPEN with _OPEN_VAL and
88#     _CLOSED with _CLOSED_VAL
89#
90#%-
91#==============================================================================
92
93#==============================================================================
94# Define some global variables
95# ----------------------------
96
97    global SHUTTER_MAC
98           SHUTTER_MAC = DOFILE
99
100    # EPICS PV of the binary output which controls the shutter
101    #
102    global SHUTTER_CONTROL_PV
103           SHUTTER_CONTROL_PV = "X04SA-ES3-SC:FPS"
104
105    global SHUTTER_CONTROL_OPEN_VAL
106           SHUTTER_CONTROL_OPEN_VAL = "On"
107
108    global SHUTTER_CONTROL_CLOSED_VAL
109           SHUTTER_CONTROL_CLOSED_VAL = "Off"
110
111    # EPICS PV of the binary input which monitors the state of the shutter
112    # if SHUTTER_MONITOR_PV = "", no monitoring is performed
113    #
114    global SHUTTER_MONITOR_PV
115           SHUTTER_MONITOR_PV = ""
116
117    global SHUTTER_MONITOR_OPEN_VAL
118           SHUTTER_MONITOR_OPEN_VAL = "open"
119
120    global SHUTTER_MONITOR_CLOSED_VAL
121           SHUTTER_MONITOR_CLOSED_VAL = "closed"
122
123    global SHUTTER_IS_ON
124           SHUTTER_IS_ON = 0
125
126    global SHUTTER_SLEEP_TIME
127           SHUTTER_SLEEP_TIME = 0.1
128
129
130#==============================================================================
131# This macro file contains the following commands:
132#==============================================================================
133
134#------------------------------------------------------------------------------
135#%+M* shutter/sh_help, shutter_help
136#     ===============
137#
138# SUMMARY
139#   Displays the shutter help text.
140#
141# USAGE
142#   > sh_help
143#
144# NOTE
145#   The help text is generated by simply displaying the text file
146#   shutter_mac.txt, which should reside in the same directory as shutter.mac.
147#   If the file does not exist, a generic help text is shown.
148#%-
149
150def shutter_help 'sh_help'
151
152def sh_help '{
153#   =======
154
155  unix (sprintf ("dirname %s", SHUTTER_MAC), _1)
156  ll = length (_1)
157  if (substr (_1, ll, 1) == "\n") _1 = substr (_1, 1, (ll - 1))
158  file = sprintf ("%s/shutter_mac.txt", _1)
159  if (file_info (file, "-e")) {
160    unix (sprintf ("cat %s", file))
161  } else {
162    printf("\n  Macros available in file shutter.mac:\n")
163    printf(  "                           ===========\n")
164    printf("\n")
165    printf("  sh_help      - creates this help text\n")
166    printf("  shop         - opens the fast shutter\n")
167    printf("  shcl         - closes the fast shutter\n")
168    printf("  shon         - activate automatic shutter opening and closing\n")
169    printf("  shoff        - turn automatic shutter opening and closing off\n")
170    printf("  sh_status    - display whether the shutter is open or closed\n")
171    printf("  sh_show      - display shutter configuration and status\n")
172    printf("  sh_setup     - modify the shutter configuration\n")
173    printf("\n")
174  }
175}'
176
177
178#------------------------------------------------------------------------------
179#%+M* shutter/shop, shutter_open
180#     ============
181#
182# USAGE
183#   > shop
184#
185# SUMMARY
186#   Open the fast photon shutter
187#%-
188
189def shutter_open 'shop'
190
191def shop'{
192#   ====
193
194    epics_put (SHUTTER_CONTROL_PV, SHUTTER_CONTROL_OPEN_VAL)
195    if (SHUTTER_MONITOR_PV == ""){
196        sleep(SHUTTER_SLEEP_TIME)
197    } else {
198        while(epics_get(SHUTTER_MONITOR_PV) != SHUTTER_MONITOR_OPEN_VAL){
199            sleep(0.01)
200        }
201    }
202}'
203
204
205#------------------------------------------------------------------------------
206#%+M* shutter/shcl, shutter_close
207#     ============
208#
209# USAGE
210#   > shcl
211#
212# SUMMARY
213#   Close the fast photon shutter
214#%-
215
216def shutter_close 'shcl'
217
218def shcl'{
219#   ====
220
221    epics_put (SHUTTER_CONTROL_PV, SHUTTER_CONTROL_CLOSED_VAL)
222    if (SHUTTER_MONITOR_PV != ""){
223        while(epics_get(SHUTTER_MONITOR_PV) != SHUTTER_MONITOR_CLOSED_VAL){
224            sleep(0.01)
225        }
226    }
227}'
228
229
230#------------------------------------------------------------------------------
231#%+M* shutter/shon, shutter_on
232#     ============
233#
234# SUMMARY
235#   Activate automatic shutter opening and closing.
236#
237# DESCRIPTION
238#   If automatic shutter control is enabled, the shutter is opened just before
239#   an actual count command is executed and immediately closed again thereafter
240#   to prevent unnecessary sample and detector irradiation.
241#
242# USAGE
243#   > shon [<flag>]
244#
245#   When called with no <flag> argument, shon enables automatic shutter
246#   control. <flag> can be one of the following
247#     flag = 1 --> enable automatic shutter control (default)
248#     flag = 0 --> disable automatic shutter control
249#
250# NOTES
251#   When automatic shutter control is enabled, the fast photon shutter is
252#   always closed in a case of any error (this includes also Ctrl-C
253#   interrupts).
254#%-
255
256def shutter_on 'shon'
257
258def shon '{
259#   ====
260
261  if($# == 0){
262    _status = 1
263  } else if($# == 1){
264    _status = $1
265  } else {
266    printf("Error: wrong number of arguments in \'shon\'. Exiting...\n")
267    printf("Usage:\n")
268    printf("  shon <flag>\n")
269    printf("flag = 1 --> enable\n")
270    printf("flag = 0 --> disable\n")
271    exit
272  }
273
274  if(_status){
275
276    SHUTTER_IS_ON = 1
277
278    # add to user_precount (opening) and user_getcounts (closing)
279    cdef("user_precount","shop; ","aaa_shutter_user_precount_key",0x10)
280    cdef("user_getcounts","shcl; ","zzz_shutter_user_getcounts_key",0x20)
281
282    # add shcl to cleanup_always to close in case of errors
283    cdef("cleanup_always","shcl; ","aaa_shutter_cleanup_key",0x10)
284    printf("Automatic shutter opening is ON\n")
285  } else {
286
287    SHUTTER_IS_ON = 0
288
289    # remove from user_precount and getcounts
290    cdef("user_precount","","aaa_shutter_user_precount_key","delete")
291    cdef("user_getcounts","","zzz_shutter_user_getcounts_key","delete")
292    cdef("cleanup_always","","aaa_shutter_cleanup_key","delete")
293    printf("Automatic shutter opening is OFF\n")
294  }
295
296}'
297
298
299#------------------------------------------------------------------------------
300#%+M* shutter/shoff, shutter_off
301#     =============
302#
303# USAGE
304#   > shoff
305#
306# SUMMARY
307#   Turn automatic shutter opening and closing OFF.
308#%-
309
310def shutter_off 'shoff'
311
312def shoff '{
313#   ======
314
315  shon 0
316
317}'
318
319
320#------------------------------------------------------------------------------
321#%+M* shutter/sh_show, shutter_show
322#     ===============
323#
324# USAGE
325#   > sh_show
326#
327# SUMMARY
328#   Display the fast photon shutter setup and status
329#
330# OUTPUT
331#   This is a sample output:
332#
333#   Shutter setup:
334#
335#   1) Shutter control PV name                     : X04SA-ES3-SC:FPS
336#   2) Control PV value for shutter OPEN           : On
337#   3) Control PV value for shutter CLOSED         : Off
338#   4) Shutter monitor PV name ("" if none)        :
339#   5) Monitor PV value for shutter OPEN           : open
340#   6) Monitor PV value for shutter CLOSED         : closed
341#   7) Shutter delay time                          : 0.10 sec
342#   8) Auto shutter enable(1) / disable(0)         : 0
343#
344#   Shutter is OPEN
345#   Automatic shutter opening is ON
346#%-
347
348def shutter_show 'sh_show'
349
350def sh_show'{
351#   =======
352
353  _shutter_print_setup
354  sh_status
355
356}'
357
358
359#------------------------------------------------------------------------------
360#%+M* shutter/sh_status, shutter_status
361#     =================
362#
363# USAGE
364#   > sh_status
365#
366# SUMMARY
367#   Display the fast photon shutter status (OPEN or CLOSED)
368#
369# OUTPUT
370#   This is a sample output:
371#
372#   Shutter is OPEN
373#   Automatic shutter opening is ON
374#%-
375
376def shutter_status 'sh_status'
377
378def sh_status'{
379#   =========
380
381    if (SHUTTER_MONITOR_PV != ""){
382        if (epics_get(SHUTTER_MONITOR_PV)==SHUTTER_MONITOR_OPEN_VAL){
383          printf("Shutter is OPEN\n")
384        } else {
385          printf("Shutter is CLOSED\n")
386        }
387    } else {
388        if (epics_get(SHUTTER_CONTROL_PV)==SHUTTER_CONTROL_OPEN_VAL){
389          printf("Shutter is OPEN\n")
390        } else {
391          printf("Shutter is CLOSED\n")
392        }
393    }
394
395    if (SHUTTER_IS_ON == 1){
396      printf("Automatic shutter opening is ON\n")
397    } else {
398      printf("Automatic shutter opening is OFF\n")
399    }
400
401}'
402
403
404#------------------------------------------------------------------------------
405#%+M* shutter/sh_setup, shutter_setup
406#     ================
407#
408# USAGE
409#   > sh_setup
410#
411#   Then modify the dialog options
412#
413# SUMMARY
414#   Modify the shutter configuration.
415#%-
416
417def shutter_setup 'sh_setup'
418
419def sh_setup '{
420#   ========
421
422    local _setup_numitems, _setup_option, _tmp_option, _str1
423
424    # total number of setup items
425    _setup_numitems = 8
426
427    _clear_screen
428
429    _setup_option = 0
430    _tmp_option = -1
431    while (_tmp_option) {
432        _tmp_option = -1
433        while (_tmp_option < 0 || _tmp_option > _setup_numitems){
434            _shutter_print_setup
435            _str1 = sprintf("Enter 1-%d to change the parameters, 0 to quit",\
436              _setup_numitems)
437            _tmp_option = getval(_str1, _setup_option)
438            if(index(_tmp_option, "q") == 1 || index(_tmp_option, "Q") == 1){
439              _tmp_option = 0
440            }
441        }
442        _setup_option = _tmp_option
443        if (_setup_option != 0){
444            _shutter_set_option _setup_option
445        }
446        _setup_option = (_tmp_option + 1)%(_setup_numitems + 1)
447    }
448}'
449
450
451#==============================================================================
452# Internal macros
453#==============================================================================
454
455#------------------------------------------------------------------------------
456#%+iM* shutter/_shutter_print_setup
457#      ============================
458#
459# SUMMARY
460#   Prints the configuration options and current values to screen
461#
462# NOTE
463#   The option numbers must be kept in sync between _shutter_set_option and
464#   _shutter_print_setup
465#%-
466
467def _shutter_print_setup '{
468#   ====================
469
470    tty_cntl("ho")  # home cursor on left upper corner of screen
471    tty_cntl("cd")  # clear the rest of the screen
472
473    tty_cntl("so")  # highlight font
474    printf("Shutter setup:\n")
475    tty_cntl("se")  # turn off font highlighting
476
477    printf("\n 1) Shutter control PV name              \t: %s", \
478      SHUTTER_CONTROL_PV)
479    printf("\n 2) Control PV value for shutter OPEN    \t: %s", \
480      SHUTTER_CONTROL_OPEN_VAL)
481    printf("\n 3) Control PV value for shutter CLOSED  \t: %s", \
482      SHUTTER_CONTROL_CLOSED_VAL)
483    printf("\n 4) Shutter monitor PV name (\"\" if none) \t: %s", \
484      SHUTTER_MONITOR_PV)
485    printf("\n 5) Monitor PV value for shutter OPEN    \t: %s", \
486      SHUTTER_MONITOR_OPEN_VAL)
487    printf("\n 6) Monitor PV value for shutter CLOSED  \t: %s", \
488      SHUTTER_MONITOR_CLOSED_VAL)
489    printf("\n 7) Shutter delay time                   \t: %.2f sec", \
490      SHUTTER_SLEEP_TIME)
491    printf("\n 8) Auto shutter enable(1) / disable(0)  \t: %d", \
492      SHUTTER_IS_ON)
493    printf("\n\n")
494}'
495
496#------------------------------------------------------------------------------
497#%+iM* shutter/_shutter_set_option
498#      ===========================
499#
500# SUMMARY
501#   Sets a new value for a given option
502#
503# DESCRIPTION
504#   Sets a new value for a given option from the options menu that was created
505#   with the _shutter_print_setup command.
506#
507# NOTE
508#   The option numbers must be kept in sync between _shutter_set_option and
509#   _shutter_print_setup
510#%-
511
512def _shutter_set_option '{
513#   ===================
514
515    if ($1==1) {
516        SHUTTER_CONTROL_PV = getsval("Enter shutter control PV name",\
517            SHUTTER_CONTROL_PV)
518    } else if ($1==2) {
519        SHUTTER_CONTROL_OPEN_VAL = \
520            getsval("Control PV value for shutter OPEN",\
521            SHUTTER_CONTROL_OPEN_VAL)
522    } else if ($1==3) {
523        SHUTTER_CONTROL_CLOSED_VAL = \
524            getsval("Control PV value for shutter CLOSED",\
525            SHUTTER_CONTROL_CLOSED_VAL)
526    } else if ($1==4) {
527        _str = "Enter shutter monitor PV name"\
528               "(leave blank if shutter is not actively monitored)"
529        SHUTTER_MONITOR_PV = \
530            getsval(_str, SHUTTER_MONITOR_PV)
531    } else if ($1==5) {
532        SHUTTER_MONITOR_OPEN_VAL = \
533            getsval("Monitor PV value for shutter OPEN",\
534            SHUTTER_MONITOR_OPEN_VAL)
535    } else if ($1==6) {
536        SHUTTER_MONITOR_CLOSED_VAL = \
537            getsval("Monitor PV value for shutter CLOSED",\
538            SHUTTER_MONITOR_CLOSED_VAL)
539    } else if ($1==7) {
540        SHUTTER_SLEEP_TIME = getsval("Enter shutter delay time [seconds]",\
541            SHUTTER_SLEEP_TIME)
542    } else if ($1==8) {
543        _status = yesno("Enable the automatic shutter control?",\
544            SHUTTER_IS_ON)
545        shon _status
546    }
547}'
548
549#------------------------------------------------------------------------------
550#%+iM* shutter/_clear_screen
551#      =====================
552#
553# SUMMARY
554#   Clears the terminal screen
555#
556# DESCRIPTION
557#   Clears the screen without losing the screen history or messing up the
558#   scrolling capabilities (this has been a problem for certain terminals)
559#   by blanking out the entire height of the screen and returning the cursor to
560#   the top left corner.
561#%-
562
563def _clear_screen '{
564#   =============
565
566  # update the ROWS and COLS variables in case the terminal has been resized
567  tty_cntl("resized?")
568
569  # print as many newlines as there are ROWS in terminal
570  cl_text = ""
571  for (i=0;i<ROWS;i++){
572    cl_text = cl_text "\n"
573  }
574  printf(cl_text)
575
576  # move back to the top of the screen and clear to end of the screen
577  tty_move(0,0)
578  tty_cntl("cd")
579
580}'
581
582#==============================================================================
583# End of $Id: shutter.mac 907 2012-06-11 22:53:33Z jemian $
584#==============================================================================
Note: See TracBrowser for help on using the repository browser.