-- DavidSchuller - 30 Mar 2023

---

Full Listing of commands and features in the BAM-2 automounter interface

Similar information exists on the MacCHESS web site Software control of the BAM-2 automounter, but this wiki page is the most complete and up-to-date source of information on this topic.

Panel by panel

General layout:

The interface features a status panel at the top. The lower section is tabbed between a User panel and an Admin panel .

---

Status panel:

CAM2 State - Current status of the BAM-2, color-coded

• RED - robot motors unpowered for safety. Robot control buttons in hutch must be pushed to recover from this state. See the section below on "BAM-2 State Control."
• YELLOW - Standby. Robot motors are powered, but software is not currently processing commands. Click "Enable" button to transition to Ready.
• GREEN - Ready. Robot motors powered and interface is processing commands.

rsp - (responses, latest 3) Brief output from recent commands, such as "MOUNT_DONE", "MOUNT_FAIL", "Goniometer is already loaded, auto-unloading first"

Currently mounted - Which sample (puck and pin) is believed to be mounted on the goniometer.

Check boxes:

• Gonio Occupied - Output from laser sensor aimed at sample base on the goniometer. Box should be checked only when a sample is mounted.
• Xray Lockout - Status of Xray_Lockout mode. See "Admin" section.
• Chill Bypass - Status of Chill Bypass toggle feature. See "Admin" section.
• Warm Bypass - Status of Warm Bypass toggle feature. See "Admin" section.
• DTemp Bypass - Status of DTemp Bypass toggle feature. See "Admin" section.
• Flying Start - Status of Flying Start toggle feature. See "Admin" section.
• Queue Depth - How many commands are queued up to be executed. See "Admin" section for Pause Queue, Clear Queue, Resume Queue commands.
• ProbHm Bypass - Status of ProbeHome Bypass toggle feature. See "Admin" section.
• SensorG Bypass - Status of SensorG Bypass toggle feature. See "Admin" section.
• SensorD Bypass - Status of SensorD Bypass toggle feature. See "Admin" section.
• AutoUnload - Status of AutoUnload toggle feature. See "Admin" section. On by default.
• Dewar Temp - Temperature (C) of sample dewar. Should be around -190 when filled with nitrogen. See "Admin" section for DTemp Bypass feature.
• Gripper Temp - Temperature (C) of gripper. See "Admin" section for Chill Bypass and Warm Bypass features.

USER command panel

(Most frequently used controls in blue)

• Selection Puck - Left-click a numbered pin to select that pin for the next command. Pins are color-coded: Orange=selected, Black=blocked, Cyan=already mounted, Gray = eligible but not yet mounted
• Puck Select ComboBox - Click the down arrow for a popup offering of pucks to select (A-I).
• Pin Select Spinner - Left-click the up or down arrows to change the selected pin (1-16). Alternate to picking from the selection puck at left.
  Auto-Increment Checkbox - If checked, when a sample is mounted, the next sample is selected. I.e. if you mount sample D3, the selection will advance to D4. On by default.
  MOUNT - Pick the selected sample from the dewar and mount it on the goniometer. Action is affected by the AutoUnload and Prerinse features.
  PreRinse Checkbox - If checked, a Mount command will include a rinse of the sample, which is quicker than doing a separate Rinse command after mounting. For users with lots of surface frost.
  
  Rinse - Pull mounted sample from the goniometer, dip it up and down in the liquid nitrogen a few times to dislodge surface ice, replace on goniometer. Works rather well.
  DISMOUNT - Dismount the sample from the goniometer and replace it in its spot in the sample dewar. If initial attempt fails, the BAM-2 will dry the gripper, chill it and try again.
  DRY - Defrost the gripper by running it up and down in the hot air knife until the target temperature (28 C) is reached.
  CHILL - Pre-position the gripper in the nitrogen to start it chilling, which takes roughly a minute. For people who like to plan ahead. If sample is not chilled in advance, Mount, Dismount and Rinse commands will wait until the gripper comes down to temperature before handling a sample.
  Enable (Green) - Transition the interface from Standby mode to Ready. Why was it in Standby mode? Possibly a minor error occurred, such as failure to dismount a sample. Or maybe someone hit the Pause Queue or Reset button (see "Admin"). See BAM-2 State Control below.
  LoadPucks (Red) - Move the gripper to the left rear and transition the robot state to Unpowered mode for safety, which de-energizes the motors. Used when someone needs to load or unload pucks or work in the vicinity of the robot. To recover from the Unpowered state, someone has to manually push the buttons on the robot control button bar in the hutch. See BAM-2 State Control .
  Check - Pick a sample from the dewar, take it to the SampleCheck position for the sensor to read if it is present. If sample is not present, the position will be blocked. Not used much.
  ReportCurrent - Send identity of "Currently mounted" sample to data collection software (e.g. ADX). Useful because the BAM-2 remembers what is mounted over a program restart, while ADX does not. Can also be used to test if the socket communication between the programs is working.
  Set_Mount - Set selected sample as "Currently mounted" without actually moving anything. For recovering from sample handling errors.
  SetG_Vacant - Set "Currently mounted" status to vacant without actually moving anything. For recovering from sample handling errors.
  
  

---

MOUNT/BLOCK status panel

A label and puck icon represents each puck.

Pin buttons are color-coded:

• Gray means the sample has not been mounted, but is eligible.
• Cyan means a sample has been mounted at least once, and is eligible.
• Black means a sample is blocked and therefore not eligible for mounting. Blocking a sample means that it will fail faster if a mount is attempted.

Puck label - One for each puck. Background is orange if this puck is selected.
Right-click* on the label pops up a menu with these choices:

• Select puck - Make this puck the selected puck. Alternative to the Puck select ComboBox.
• Reset puck - Clear mounted status of all pins in this puck.
• Block puck - Block all pins in this puck so they cannot be mounted.
• Unblock puck - Unblock all pins in this puck so they can be mounted.

Puck icon - One for each puck. panel background is orange if this puck is selected. Buttons representing pins are unlabeled, but hovering your mouse should bring up the ToolTipText with the sample label. Some of the pucks in that image look funny. That's because the software supports both ALS/Unipucks and MSC pucks. MSC pucks have only 12 samples in a different pattern. No one seems to be bringing MSC pucks recently.
Right-click* on any pin button pops up a menu with these choices:

• Select pin - Make this sample the selected puck & pin. Alternative to Puck select Combobox and Pin select Spinner.
• Reset pin - Clear mounted status of this sample pin.
• Block pin - Block this sample pin so it may not be mounted.
• Unblock pin - Unblock this sample pin so it may be mounted.

* The popup menus in the Mount/Block status panel are the only use of mouse right-clicking in the BAM-2 interface. All other controls use left-clicks (assuming standard 2 or 3 button right-handed mouse).

Reset All - Reset mounted status of all pins in all pucks
Unblock All - Unblock all pins in all pucks

---

ADMIN command panel

These commands are for staff, and should only be used if you have specific instructions. E.g. if a sensor is broken, you might be told to use a bypass feature to get you through the night.

Alignment features:
Align All - Calibrate position of gripper, then goniometer, then 3 posts on sample plate. This is the normal procedure after a user's pucks are loaded. Goniometer must be empty.
Align Gripper - Calibrate position of gripper vs. master reference post.
Align Plate - Calibrate position of gripper, then 3 posts on sample plate. Positions of individual puck slots are calculated from this info and previous mapping.
Align Slots - Calibrate position of gripper, then 3 posts on sample plate, then all 9 puck slots on sample plate. All slots must be empty.
Align Goniometer - Calibrate position of gripper, then of goniometer. Goniometer must be empty. Should be done after a table alignment or reset of the "Pin zero' position.
Flying Start - Special mode for when the gripper is so far out of alignment it cannot pick up the calibration probe. The gripper will move to the SafeFlip position (above the hole in the dewar lid), click closed and open twice, then wait 5 seconds for someone to manually place the probe snugly in the gripper. The gripper will close, then wait 3 seconds for the assistant to get out of the way before it continues with its next duties, which will always be to calibrate the gripper with probe against the master reference post.
After alignment, the gripper will return to the SafeFlip position, wait 5 seconds, then release the probe. Someone should catch it so it doesn't fall into the nitrogen.
The "FlyingStart" option may be toggled off after the probe is picked up, and in that case the probe will be returned to its cradle in the normal fashion.

Bypass features:
ProbeHome Bypass - Bypass the sensor which detects the calibration probe in its cradle. Useful when sensor is broken.

Chill Bypass - Bypass temperature sensor in gripper while chilling. When gripper is placed in nitrogen, wait a certain period of time for gripper to chill instead. Useful when gripper temperature sensor is broken.

Warm Bypass - Bypass temperature sensor in gripper during defrost. Useful during development.

DTemp Bypass - Bypass temperature sensor in sample dewar, return a cold temperature. In case the dewar temperature sensor breaks.

SensorG Bypass - Bypass the laser sensor which checks for presence of a sample on the goniometer. Useful if the sensor is broken or out of alignment.

SensorD Bypass - Bypass the laser sensor which checks for sample presence in the gripper adjacent to the dewar. Useful if sensor is broken or out of alignment. Has occasionally been useful if user has extremely rusty sample holders (shame on them).

Assorted:

Atom Test - Bring up the AtomTest frame for advanced testing and development. Only for use by Dave Schuller or his successor once he is dead and cold in the ground. Further details below in a separate section.

XRAY_Lockout - The Xray Lockout mode is normally set by a signal from the data collection software (e.g. ADX) while data collection is in progress. When it is set, gripper access to the goniometer is denied. Mount, Dismount, Rinse and Align Goniometer commands will fail. This button allows the mode to be toggled in case the data collection software gets confused and forgets to unset it.

SPECIAL - Advanced command series, may change. Last used to mount each sample in each puck specified by a string in the System.properties file, wait 4 seconds, then dismount it. Puck drying cycle called after each puck. Last used for testing Hampton Research pins.

SPECIAL2 - Similar to SPECIAL, except each sample kept on for 120 seconds before dismount.

Mount Puck - Mount each unblocked sample of a puck, leave it on for 4 seconds, then dismount it. For endurance testing.

Check Puck - Pick up each sample of a puck, take it to SampleCheck position and test if sample is present in gripper, then return it to puck. Undetected samples will be assumed missing and blocked.

Pause Queue - Disable execution of new commands in queue. Current command will be finished, then state will transition to Standby.

Resume Queue - Resume execution of commands in queue. State transitions from Standby to Ready. Equivalent to Enable button on user command panel.

Clear Queue - Clear commands from the queue. The current command will be finished.

Premount - Send signal to data collection software to move goniometer to the standard position for automounter access (Phi=225, MX,MY,MZ=0). This is sent for all commands originating from the BAM-2. For commands originating from the data collection software, it is assumed the goniometer has been properly positioned in advance.

AutoUnload - This toggle feature, on by default, affects behavior of the Mount button. If a sample is already mounted on the goniometer, it will be dismounted first; and then the selected sample will be mounted. Saves a few mouse clicks.

Reset - Transition state to Standby mode with full startup configuration sequence.

---

LOG panel

A text block showing a portion of the log file. This also gets written to ~/src/bam2/MacCam0.log. Perusing the log file can be useful if anything goes wrong, but it takes some study to know what to look for. For example, to see the results of calibrations, try searching the log file for SHIFT.

---

---

Atom Test frame

The Atom Test frame, called from one of the "Admin" buttons, is for serious development and testing. Most users will never see this feature.

AtomTest status panel

Status check boxes provide output from the various sensors and micro-switches:

• Gonio Occupied (laser sensor output)
  
• Gripper Occupied (laser sensor output)
  
• Gripper Open
• Probe@Home (calibration probe is in its cradle)
  
• Lid Open A The two halves of the pneumatic lid have separate sensors.
  
• Lid Open B
• Cryo Retracted cryostream mount has pneumatic lift to retract it while gripper accesses goniometer.
  
• Cryo Extended
• Touch Sensor0 - discrete level, lowest force. Used for calibration.
• Touch Sensor1 - discrete level, intermediate force.
• Touch Sensor2 - discrete level, high force. There is a fourth, even higher, discrete output from the force sensor which triggers an interrupt to unpower the robot motors if excessive force is encountered.
• FliprUp position of pneumatic 90d rotation stage for gripper. Up for acces to goniometer, down for access of dewar.
  
• FliprDwn

Queue Depth - Number of AtomTest commands queued up for execution

Position XYZ - Position of gripper (mm)

Force/Torque sensor 6 axis readout: FX, FY, FZ, TX, TY, TZ

"F" is force, "T" is torque. The 3 readings which are important are FZ, the straight line force up the gripper (when it is vertical. values will be negative), TX, the torque in the North-South direction(positive or negative) and TY, the torque in the upstream-downstream direction(positive or negative).

AtomTest commands

Move to/Approach defined positions. Positions are defined in the properties files in the /res directory.

Move To - move to position selected by radio buttons:

• Safe Flip - where the gripper goes to flip up and down
• SampleCheck - Dewar-adjacent position where samples are held up for sensor check
• Chill - Gripper is down through hole in lid, in nitrogen
• Standby - Gripper is back out of the way to the left, best for loading pucks
• Recover - the special spot in the dewar where samples are dropped when they cannot be put back in the puck.

Approach - approach the radio-button-selected position to within the specified distance (mm):

• Reference Master alignment post
• ProbeHome - Where the alignment probe is kept
• Gonio
• Reference post on sample plate (0-2)
• Dryer
• Puck/Pin (select A-I, 1-16)

Discrete commands

• Flip Up
• Flip Down
• OpenGripper
• CloseGripper
• Open Lid
• Close Lid
• Get Probe
• Retrn Probe
• DryerAir On
• DryerAir Off
• Retract Cryo - Engage pneumatic lift for cryostream
• Extend Cryo - Release pneumatic lift of cryostream
• Set Force Bias - zero out Force/Torque readings
• Get Force - Get immediate reading from the Force/Torque sensor. A reading is also made after each move.

Minor axis translations

(For each axis)

Speed(select with spinner), Distance(mm)(select with spinner), Move-, Move+

+X is to the North. +Y is upstream to the Xrays. +Z is gravitational up.

Assorted

Clear Que - clear AtomTest command queue. This is separate from the general BAM-2 command queue.

Report Position - Write current position to the log file so it can be easily identified.

Exit - Close the AtomTest frame. I recommend moving the gripper back to StandBy position first.

---

Command times

In seconds. Based on 2023-1 run. For sample-handling commands, shorter times will reflect that gripper is pre-chilled. Longer times may include retries. Longer mount times may include pre-rinse. Longer dismount times may include dry-chill cycle time in case of initial failure.

• Operation: Median (range)
• Rinse: 62.5 (55.0 - 79.2)
• Mount: 44.6 (24.5 - 99.1)
• Dismount: 46.6 (35.2 - 216.9)
• Dry: 54.9 (13.95 - 68.7)
• Chill: 52.0 (11.3 - 65.8)
• Align Gripper: 59.4 (56.2 - 85.037)
• Align Goniometer: 106.2 (102.8 - 118.2)
• Align Plate: (176.6 - 196.4)
• Align All (Gripper, Gonio, Plate): 233.4 (221.9 - 250.2)
• Align Slots: (615.5 - 629.7)

---

---

BAM-2 State Control

The BAM-2 interface uses SCXML state control markup language to ensure that the automounter is always in a defined state. Part of state control is managing the power to the robot control motors, which is done for safety reasons. If someone is loading pucks or performing maintenance in the vicinity of the automounter, they need to be sure that they are safe from unexpected robot motion. To accomplish this, the BAM-2 robot can be put into an Unpowered state.

Unpowered state:

When the BAM-2 is in the Unpowered state, the State line in the status panel at the top of the BAM-2 GUI turns red and says "unpowered". When the motors are unpowered, the robot arm may be manually pushed around in horizontal directions. Be sure that the arm position is well within its legal range before transitioning from unpowered mode to standby mode, otherwise the software will hang.

Any of three things will cause the robot to enter the unpowered state:

• Clicking the LoadPucks button on the User command panel
• Stepping on the pneumatic safety mat on the floor near the automounter
• The Force/Torque sensor through which the gripper is mounted to the robot arm registering an excessive force

To exit the Unpowered mode, someone needs to find the robot control bar and hit some buttons. The control bar is mounted to the side of an equipment rack as you enter the ID7B2 hutch.

In the Unpowered state, the white button light will be off.

To transition from Unpowered to Standby state:

• Hit the green button, and the white button light should start blinking.
• Hit the white button. The BAM-2 interface will transition to Standby mode and the white button light should glow steadily.

Standby state:

In the Standby state, the GUI State bar will be yellow and read "Standby."

The robot motors are powered up, but the software interface is still not processing commands. To accomplish this, hit the Enable button on the User command panel to transition to Ready mode.

Ready state:

In the Ready mode, the GUI status panel state bar will be green, the robot motors are powered, and the software will accept and execute commands. The state bar text will be either "Ready" or whatever command it is executing.

To transition back to the Standby mode, hit the Pause Queue or Reset buttons on the Admin command panel of the GUI.