BM02 is currently controlled by SPEC applications, for which a tutorial can be found on the ESRF intranet web site.

These applications are generally already running when the user arrives. If they are not running, they can be started typing their name in a Konsole window of the linux PC called "d2cc" :

  • mono: to control Optics, including mirror1 and mirror2
  • slits or slitsaxs: to control the optic slits and the goniometer slits or saxs slits respectively.
  • fourc: to control the 7-circle diffractometer.
  • saxsint, saxsext, saxsht, gisaxs: to control the Small Angle Scattering Camera
  • esrfCCD : to control the small camera used for direct beam alignment. To avoid saturation, adapt the acquisition time with ccdlive time. Once done please exit the session.
  • tablegonio : to align the goniometer with respect to the direct beam. Once done please exit the session and switch off the motors, to make sure the goniometer stays in place.

In all those cases, the same program is used. The applications differ only by motor names and specific initializations : the general commands and datafile format are common to all applications.

The following different applications can be triggered from d2cc computer only !!!

From the other computers, they can be runned in simulation mode (-s) only.


  1. pay attention when typing "mv" commands, motor names are checked, but numbers are also recognized as motor num.
    ex: mv tth 5 will move tth to 5
          mv 1 5  will move motor number 1 to 5
  2. The number of intervals in a scan is limited to 4000.
  3. Several movement can be triggered simultaneously, but MIND TO AVOID COLLISIONS!!!
  4. In not-attended mode a scan controlled by the monitor is more convenient than a scan with time control: it allows to overcome reinjections or beam losts...
  5. You can stop each scan by typing ^C. This should be done for example if you start scannning a motor to a unwanted position. dscan will return to the old position after ^C. An error message may occur telling you that the motor didn't reached its final position. In addition, a mismatch between the values of the motor position in SPEC and from the controller may occur. In this case, always answer the question to change the value with no, unless you are sure about what you are doing. In general, all motors have limit switches (hard limit) and/or soft limits controlled by the software, so that it should not be possible to destroy anything.



The users are kindly ask not to change any configuration in the SPEC applications without contacting the beamline personnel.



Spec coordinates :

Two systems of coordinates are used in spec : users and dial. They are displayed by the same order wa, but all the commands use only the users coordinates. The dial coordinates can be considered as absolute; they can be used to define limits (see also Bugs).



Spec basic commands are :

lsdef display the basic spec commands
hi history, print the previous triggered commands (with their number)
wa display the positions of all motors using user-coordinates and dial-coordinates.
pon send the following commands and the answers to the printer.
poff send back the following commands and the answers to the terminal.
ct (time) send back the value of the counters integrated over the time to the terminal. (By default time =1s)
pct (time) send back the value of the counters integrated over the time to the spec datafile
(u)mv motor value (motor2 value2) move a motor to an absolute position given in user-coordinates (and display its current position). It can move simultaneously a 2nd motor.
(u)mvr motor value (motor2 value2) move one (or 2) motor(s) of the relative value given in user-coordinates (and display its current position)
tw motor value move a motor by steps
twct motor value move a motor by steps and every time, send back the values of the counters integrated over 1 second
ascan motor begin end steps time perform a scan and display the counts. The position begin and end are given by their absolute values. The interval is divided into steps, when finished the motor remains at the last position. Negative time gives control to the monitor counting : Works only if mon is plugged to vct1_3. Data are automatically added to the file: ($HOME)/dataspec/prg_name.($DATE).
dscan motor begin end steps time act like ascan but perform a relative scan and display the counts. The position begin and end are given by their relative values. At the end, it returns to the initial position.
afscan motor begin end steps time act like ascan but perform a fast scan (a ramp of time between two "steps" when there is no stop).
dfscan motor begin end steps time act like dscan but perform a fast scan (a ramp of time between two "steps" when there is no stop).
timescan time sleeping_time infinite scan moving no motors; stop by ctrl C.
pplot The displayed spectrum can be plotted on the laser printer.
plotselect number1 number2 ... These basic SPEC scans are automatically plotted on the screen. It is possible to switch the displayed counter with this command; numbers are the channel numbers in the counter array.
counters allows you to choose which counter is associated with the monitor and which with the detector: MON=1 or 2 and DET=1 or 2. ( ! in the monitoring mode the vtc6_1 should be physically connected to the MON)
cen moves to the center between half height points of the last scan. It is equivalent to "mv motor CEN"; CAUTION, use after a scan using only one motor.
cenmass moves to the center of mass of the last scan; equivalent to "mv motor COM"
pic moves to the postion of the highest detector counting of the last scan; equivalent to "mv motor PEAK"
laser prints the display (plot) window, clic with the left side button of the mouse in the display window to be printed.
Escan begin end steps time perform a photon_energy scan and display the counts. The position begin and end are given by their absolute values (in keV).
getE display the photon energy (in keV). MIND the photon energy is NOT transferred from an application to one another, so, when opening an other application do not forget to type wa and then getE (eventually use resetE energy).
setE value set the user angle of the monochromator to match with the chosen value (in keV). BE VERY CAUTIOUS at this STEP!!! Do not forget to do it in all opened applications.
resetE value TO be Preferred: ask to verify before the setE command is triggered
moveE value moves to the absolute energy in keV (the value is not transferred to the other applications!!!)
lm print the user and dial soft limits for all motors of the application.
set_lm motor begin end set the soft user limits.
flux aper thick dist gives the ratio of flux to the monitor with the scattering of a kapton foil of thickness 'thick' in view of a PM with an aperture 'aper' at a distance "dist" for the energy registered in the application.

You can stop each command or scan by typing ^C.
This should be done for example if you started scannning a motor to a unwanted position will return to the old position.
To quit the SPEC applications, always use ^D or quit. This will store the current definitions.

Macros (see manual p. 25)

In SPEC it is possible to built higher level commands combining a sequence of basic instructions.

  • Use a text editor in a X-window, and input the commands as it would be typed interactively with the terminal.
  • You also can write your own macro function. The syntax is similar to the C language. Grammar rules and operators are defined p 52-59 of the manual.

    def macroname '

To execute the command file:

qdo macro_name executes the command file macro_name. Does not echo the commands.
do macro_name similar to qdo, except that commands are echoed.

WARNING: If an error occurs at one line (i.e. scan outside software limits), the command file is INTERRUPTED, that is the following lines are not executed. 

prdef macro_name print the definition of the macro.
lsdef give the list of all available macros.
lsdef *aaa* give the list of macros which name contains the string 'aaa'.


Dataspec files :

Data are stored in an ASCII file, in the subdirectory dataspec. The default filename is application_name.($DATE). Each scan is stored with a heading containing the type of scan, (H K L of the current position for hklscan of fourc), geometry parameter... Then comes the list of angles, time, monitor and counts. The last line (#R) contains information of a basic analysis of the scan: SCAN_N, pl_xMAX, pl_MAX, pl_FWHM, pl_CWHM, pl_COM, pl_SUM (corresponding to scan Number, Xvalue of YMax, Max counts, FWHM, position of the center used for computing FWHM, Center of mass, Sum of counts).

For a summary of the experiment, you can use:

  • contents [-c] filename (-c means comments will be printed, too.)
  • This will print out a summary of all scans stored in the data file filename.
    Type contents filename > text to store the result in the file text(for printing).
  • The showscans program will perform a plot summary (12 plots per page) of all the scans in the data file.
  • showscans [options] file [file_options]
    -zi filter (default: psfilter) use -zi X11
    -ft font (2)
    -sy symbol (L)
    -eb error_bar_mode (0)

    -f from_scan_number (0)
    -t to_scan_number (9999)

    Type showscans -zi x11 file for a screen plot and showscans -zi 'psfilter @lp' file for an exit on the printer.
    • awk -f titres.awk datafile > file.lis
    • This extracts from the datafile the scan headers and #R informations and stores them in file.lis

    How to plot

    Please refer to Graphics applications


    You have for instance :

    - spec2grace : To plot a 1 Dim scan, use the command spec2grace datafile. This will read the file and plot it with the grace software

    . The options are given typing a question mark.

    - Cplot : Data can also be plotted and analysed using the Cplot package.

    Specific commands

    Shutters :

    To control the Main shutter of the experimental hutch:

           manually from the terminal:

    shutter open


    shutter close


           automatically inside a scan:




    To control the rapid shutter for the CCD camera
    to remain open wathever the counting mode
    unable automatic mode synchronized with the camera

    Filters :


    The attenuator system uses 16 states indexed from 0 (nothing) to 15.

    From terminal the 'short' command 'foil' can be used to control them:

    • foil number on | off
    • foil all on | off
    • foil + | -
    But the macro 'foil' is not allowed in other macros, full commands must be used:
    • set_foil_state number, where number ranges from 0 to 15
    • increase_foil_state
    • decrease_foil_state
    The attenuators can be increased or decreased automatically during a scan if changes in intensity are not to quick:
    • foil auto on
    • when foil auto is on, the filters will be automatically changed if the detector rate is greater than 75000 counts/sec or lower than 1000 counts/sec (default values). These values can be changed with foil auto on max min.
    • the true counting rates will be stored in 'pseudodet' and corrected values according to absorption coefficient of the filters involved will be stored in 'det' so as to have a 'viewable' data curve on the plot screen.
    • transparencies of the filters can be either calculated by spec when it changes a filter (quick calculation using only 1 point) or entered manually by typing foil_calibration. If you have already stored the values in a file, you can re-read them with foil_calibration name_of_file.
    • to come back to the automatic calculation type : foil_uncalibration.
    • You can stop automatic change of filters by typing : foil auto off
    • foil_choice

    • To be used if you want to measure a peak with only 1 filter : go to the maximum of the peak, type foil_choice. It will put foil auto off and decrease the filters while the max is smaller than 20000 counts/sec.

    Furnace control :

    To control the Eurotherm PID (which should have been previously adjusted by the dedicated  PC) as a motor:

    mv(r) euroc temperature


    ct, twct, pcct & winct should give the temperature in celsius "eurot = temperature".

    Displex control :

    To control the displex (which should have been previously configurated as a motor ):

    mv(r) cryoset temperature


    ct, twct, pcct & winct should give the temperature in kelvin "cryoa = temperature cryob = temperature".

    CCD camera triggering

    • The CCD camera is driven by a Princeton Instrument program which runs on a PC. FIRST, define the filename
    • To use the camera properly, a small shutter has been added on the goniometer. It controls the X-ray exposure time and has to be correctly wired.
    • To control it by SPEC;

        - verify that the dialog application has been triggered when opening  Winview 2 3.4.4 , F:" open "controlwv.wbt"
        - select "Poste de Travail" by the right button of the mouse, select "se connecter à un lecteur reseau" and search your name in the G:'s users list ; enter your password and verify that both F: and G: are present in the "poste de travail" applications.

    lsdef win* : list all ccd macros in spec
    winviewInit : initialise dialog with PC (name of file,...)
    If those commands do not exist, first load them : qdo d2_macros/controlWinview.mac.

    Start with winviewInit, answering the questions. In case of pb type : winMan.

    Fixed image : winct [time] [num frame]

    Triggers simultaneously the CCD acquisition, the counters and opens the rapid CCD shutter. if num frame is not given, it keeps the last given value.
     After the time (by default 1s), closes the CCD shutter, stops the counters and reads the CCD memories and creates the filename.spe (in 2 bytes) file. An abort (^C) may lead to unsignificant datas. The monitor values are registered in the>. Before activating, be sure that the PC is iddle: the "Acq and "F' icons of Winview should be green. Otherwise you will have trouble (conflict between the PC and spec orders).


    To have a look (or print) the monitors values, the command is .

    Image while moving a motor :

    • windscan (winascan) motor start end step time to move a motor and take an image at each position
    • wininteger th_start th_end time_of_oscillation scan th from start to stop (no return) at base_rate speed while acquiring one image.
    • winoscille th_start th_end time_of_oscillation oscille theta from start to end and back at base_rate speed.

    the analyser stage

    A macro called analyser.mac can be loaded to deal with analyser.
    • analyser_help : to get some Help on analyser macros, Usage: analyser_help
    • analyser_calc : calculates theorical positions for analyser at current energy, Usage: analyser_calc
    • analyser_resol : calculates energy resolution giving the analyser scan fwhm(ttha), Usage: analyser_resol fwhm(ttha) [ttha]
    • analyser_init : initialises the crystal analyser, Usage: analyser_init [num]
    • graphite : sets the graphite parameters
    • si111 : sets the Si 111 parameters
    • si311 : sets the Si 311 parameters
    • ge111 : sets the Ge 111 parameters
    • analyser_positive : crystal surface facing upwards
    • analyser_negative : crystal surface facing downwards
    • analyser_Escan : Energy scan for the analyser, Usage : analyser_Escan eini eend step time"

    mono, specific commands



                angle of the monochromator


                   tilt angle of the second crystal


             parallelism of the two crystals


              vertical translation of the whole monochromator mechanics


                    distance between first and second crystals


                    translation of second crystal parallely to its surface


               rotation of second crystal around the normal


                    no longer in use


               first motor of the bender


               second motor of the bender


                      vertical translation of the antiscattering window at the entrance of the monochromator

    v2                  vertical translation of the antiscattering window at the exit of the monochromator

     The monochromatic intensity of the beam just after the second crystal can be followed by the diodes:

    gives in Volt (0<d2<10V) the values of the two diodes


    scand2 motor begin end steps time
    same as ascan for the two diodes.


    dscand2 motor begin end steps time
    same as dscan for the two diodes.





    gives a short explanation (in french) of the action of the following macros written to set up the optic of the beamline.
    The value of the selected energy is expressed in keV (range 5-25), or as a wavelength in Angstrom (0.5-2.5), other values are invalid. Some macros depends of the experiment which is carried out, if you want to calculate value for the small angle camera you have to set the variable d2_optic_saxs to one:

    General macros of "mono"



                tricks the parallelim of the two crystals, followed by the diodes signal d2, then by the monitor VTC6-3. The maximum flux may need a final manual adjustement by the  mvr gamma +-.0005; ct


    adujst_optic energy_or_lambda
    sets the mirrors and the monochromator to their nominal value, the angle of the monochromator is always reseted to a reasonable value, to obtain an accute setting of this value, an absortion edge has to be recorded in the pseudo channel-cut mode.


    adujst_Zspot delta_z
    moves the beam in the vertical plane of delta_z millimeters at the sample position, this is done using the second mirror.


    adujst_Yspot delta_y
    moves the beam in the horizontal plane of delta_y millimeters (positives values are to the freeway) at the sample position, this is done using a rotation of the khi of the second crystal.

    macros concerning only the monochromator

    adujst_mono energy_or_lambda
    sets all the motors of the monochromator, in the fix_exit_mode, to their nominal value without moving mirrors


    displays the required values of all the motors concerned by the monochromator using taking off its energy from the Bragg angle


    print_settings_mono energy_or_lambda
    displays the required values of all the motors concerned by the monochromator to set it at the required energy without moving the mirrors


    print_settings_mono energy_or_lambda mir_ener_lambda
    displays the required values of all the motors concerned by the monochromator to set it at the required energy if the mirrors are set to the value corresponding to mir_ener_lambda

    macros concerning only the mirrors

    adjust_mirror energy_or_lambda
    sets mirrors at the required energy, the mirror angle are choosen for an optimal harmonic rejection, the monochronochromator must be set after the command using the adjust_mono macro


    print_settings_mirror energy_or_lambda
    displays the required values to set mirrors at the required energy

    macros concerning focussing

    adjust_depth_mirror num depth


    adjust_weigth_mirror num depth
    allows to modify the vertical focusing using mirror num. To modify the focusing on the sample num=2. Weigth is the position of the lead weigth whichapply the torque ( in mm). Depth is expressed in mm . they can be compared with the value given by print_settings_mirror
    courb value
    allows to modify the horizontal focusing using the monochromator. value is an empirical value between 0 and 1.

    slits, general commands

    All movements (given in mm) of the edges of slits are independant .
    The zeros are at the hard limits positions when completely open. In relative movement, a positive value corresponds to closing the slit!
    The following symbols are used for the positions:
    "s" for slit, a real motor moving a single edge  of  the slits nb, associated with:
    "u" for up
    "d" for down
    "f" for front , i.e. on the side of the gangway
    "b" for back, i.e. on the side of the ring
      (ex: mvr su1 10. closes of 10mm the upper edge of SLITS 1 )

    "h" or  "H" , for horizontal, i.e. moving together "f" and "b"
    "v" or "V" , for vertical , i.e. moving together  "u" and "d", associated with:
    "g" for gap, i.e. pseudomotor to change the gap of two associated  edges (ex: mvr vg2  -5.)
    "o" for offset,  i.e. pseudomotor to change the offset of two associated  edges (ex: mvr ho2  -0.05)
    refH or refV slit_number
    in order to have a precise zero reference on slits number slit_number ( available on slits 1, 2, 3, 4, 6, 7 and 0).

    The considered slits depend on the application:
    slits : for the diffractometer, includes s1, s2, s3, s4, s6, s7 (and s5).
    slitsaxs : for the saxs camera, includes s1, s2, s3, s4 and s0.

    FOURC, general commands



    tth                 angle of the detector arm



                     three Eulerian angles of the sample






                rotation of the detector arm around the vertical


                  angle of the analysor arm

    omegaa       angle of the analysor



                angle of the monochromator


                   tilt angle of the second crystal of the mono


             parallelism of the two crystals of the mono

    Coupled movement of omega and 2theta :


    mv_th2th angle
    Absolute movement of tth by angle and of th by angle/2


     IT WILL NOT CONSERVE THE OFFSET!!! (th =tth/2 after this movement!


    OTHERWISE PREFER mv tth angle2 th angle1


    mvr_th2th angle
    relative movement of tth by angle and of th by angle/2: IT WILL CONSERVE THE OFFSET!!!

    th2th beg_angle end_angle intervals time (or monitoring with '-' sign)
    scan with relative movement of tth by angle and of omega by angle/2; returns to initial angles at the end of the scan


    Dedicated cristallography macros and scans: simplest instructions:

    setlat then enter the asked values

    ca h k l calculates the diffractometer angles for the h k l reflection (using the energy registered in the application).


    SAXS, general commands

    There are now several spec applications, depending of the sample holder you use:

    saxsint for the sample holder under vacuum.

    saxsext for the sample holder in air.

    saxsht for sample holders allowing z axis rotation.

    gisaxs for sample holders allowing y axis rotation.

    The motors are called (with positions given in mm):

    • xsamp, zsamp, (zsamp) for sample holders (!!! mind the power supply is adapted to your motor; ask it to your local contact before any permutation of cables)
    • XstoP, ZstoP for the beam stop
    • Xdet, Zdet for the detector holder


    • kapton on/off to retract or not the rear monitor Kapton foil
    • samplePosition editing a table: at each number, we associate a sample and its X,Z coordonates.
    • mvpos nb moves the sample holder to the  position given in previous table for sample number nb
    • winct [time][num frame] For detailed description and triggering , clic here Before activating be sure that the PC is iddle: the "Acq and "F' icons of Winview should be green. Otherwise you will have trouble (conflict between the winview PC and spec orders.
    • saxsTable
      edit the successive samples to be probed and acquisition times to be recorded.
    • run_saxs nb or auto nb
      run the previous macros (several winct...; see precautions), i.e. copy CCD images as a ".spe" file in the chosen directory and write the monitoring in the dataspec/saxs.($DATE) file.
      nb=0 : no temperature control. nb > 0 : please contact C. Rochas.
    • see also macros for CCD triggering



    -At spec initialization, it sometimes ask for modifying registers, this is related to spec coordinates. Please answer NO.

    - Sometimes, spec does not understand any commands giving wrong diagnostics. In such a case, get out of the application and reopen it using the -f arguments : mono -f, by example, if you whish to play with the monochromator.

    - Within some spec implementation, out of range values are displayed by spec, for instance the value of a  motor1. In order to correct this, the following procedure can be use (MIND, verify that HARD LIMITS are ACTIVE!!!):
    for exemple

    ... then either type, for exemple
    set motor1 20.000
    set_dial motor1 2 0.000
    or type
    set_lm motor1 -200 200
    and verify by
    answer NO  if it is asked for modifying registers.

    - if during a movement  with a coder, it appears:
    motor to xyz --> move to x'y'z'
    The domain of acceptance of the value may be too short (by default generally .001 degree for main rotations). To enlarge it, type:
    retry on domain

    - If during a scan , it appears

    - Cancel the scan by ctrl C
    - check that the shutters or slits are opened...
    - the program loop until the monitor has reached a certain value defined by VALID_MON= (50 by default);


    if you want to overpass this limitation (usefull for automatic scans when there is beam crash or reinjection),type :


    spec implantation

    All beamline control at ESRF are done using a networking architecture for which we can assume three levels :

    the motor controller, which really moves can be either a VPAP system or an ITL indexor from Micro Controle.

    they are driven by a server on a VME crate running OS9

    the application program ( spec or others ) send orders to the VME see also BUGS in spec-coord.