Scanbot User Guide (Terminal Mode)

This page documents the available commands and how to use them when running Scanbot in a terminal. For a list of available commands on the fly, run help, or for help with a specific command, run help <command_name>

Scanbot Configuration

Command	Inputs	Description	Example
help	Command name	Get help with a specific command	help survey
get_ip		Returns the configured IP address	get_ip
set_ip	IP address	Configures the IP of the machine running Nanonis	set_ip 127.0.0.1
get_portlist		Returns the list of ports being available to Scanbot	get_portlist
set_portlist	TCP ports	List of ports delimited by a space	set_portlist 6501 6502
get_upload_method		Return the current upload method	get_upload_method
set_upload_method	Upload method	Can be one of path, zulip, firebase, no_upload	set_upload_method firebase
get_path		Returns the current save path	get_path
set_path	path	Configures the path to save PNGs	set_path ./scanbot_images/
get_users		Return the list of users on the whitelist	get_users
add_user	User email	Zulip only: Add a user email to the whitelist. Only users on the whitelist can run Scanbot commands. Whitelist is stored in whitelist.txt on the host machine.	add_user example@example.com
stop		Stop Scanbot's current action	stop
quit		Stop Scanbot running	quit

Nanonis Configuration

Command	Inputs	Description	Example
plot_channel	-c: (int) Set default channel for scanbot to look at. -1 means no change. Run without options to see available channels. Default: -1 -a: (int) Add channel to the scan buffer. -1 means no change. Run without options to see available channels. Default: -1 -r: (int) Remove channel from the scan buffer. -1 means no change. Run without options to see available channels. Default: -1	Configure channels in the scan buffer. Run without inputs to see a available channels	plot_channel -c=14

Data Acquisition

Command	Inputs	Description	Example
plot	-c: (int) Channel to plot. -1 plots the default channel which can be set using plot_channel. Default: -1	Return a PNG of the current scan frame	plot
survey	-bias: (float) Scan bias. Default: nanonis settings -n: (int) Size of the nxn grid of scans. Default: 5 -i: (int) Start the grid from this index. Default: 1 -s: (str) Suffix at the end of autosaved sxm files. Default: scanbot -xy: (float) Length and width of the scan frame (m). Default: nanonis settings -dx: (float) Scan grid spacing (m). Default is -xy. Default: nanonis settings -px: (int) Number of pixels. Default: nanonis settings -st: (float) Drift compensation time (s). Default: 10 -stitch: (int) Return the stitched survey after completion. 1: Yes, else No. Default: 1 -hook: (str) Name of a custom python script to call after each image.. -autotip: (int) Automatic tip shaping. 0=off, 1=on. Properties for the auto tip shaper should be set with auto_tip_shaper command. Default: 0	Conduct a survey where images in a grid of size nxn are taken	survey -n=3 -s=test_survey -bias=0.7
survey2	-bias: (float) Scan bias. Default: nanonis settings -n: (int) Size of the nxn grid of scans within each survey. Default: 5 -i: (int) Start the grid from this index. Default: 1 -s: (str) Suffix at the end of autosaved sxm files. Default: scanbot -xy: (float) Length and width of the scan frame (m). Default: nanonis settings -dx: (float) Scan grid spacing (m). Default: nanonis settings -px: (int) Number of pixels. Default: nanonis settings -st: (float) Drift compensation time (s). Default: 10 -stitch: (int) Return the stitched survey after completion. 1: Yes, else No. Default: 1 -hook: (int) Flag to call a custom python script after each image. Script must be ~/scanbot/scanbot/hk_survey.py. 0=Don't call, 1=Call. Default: 0 -autotip: (int) Automatic tip shaping. 0=off, 1=on. Properties for the auto tip shaper should be set with auto_tip_shaper command. Default: 0 -nx: (int) Size of the nx x ny grid of surveys. This sets up nx x ny surveys each taken after moving -x/yStep motor steps. Default: 2 -ny: (int) Size of the nx x ny grid of surveys. This sets up nx x ny surveys each taken after moving -x/yStep motor steps. Default: 2 -xStep: (int) Number of motor steps between surveys in the X direction. Negative value snakes coarse grid in opposite direction. Default: 20 -yStep: (int) Number of motor steps between surveys in the Y+ direction. Negative value reverses to Y- direction. Default: 20 -zStep: (int) Number of motor steps to move in +Z (upwards) before moving the tip in x/y. Default: 500 -xyV: (float) Piezo voltage when moving motor steps in xy direction. Default: 120 -zV: (float) Piezo voltage when moving motor steps in z direction. Default: 180 -xyF: (float) Piezo frequency when moving motor steps in xy direction. Default: 1100 -zF: (float) Piezo frequency when moving motor steps in z direction. Default: 1100	Conduct several surveys as above, moving the coarse motor between each one. nx x ny surveys are acquired	survey2 -bias=1 -n=4 -xy=50e-9 -dx=200e-9 -px=256 -nx=3 -ny=5 -zStep=2000 -yStep=-500
bias_dep	-n: (int) Number of images to take b/w initial and final bias. Default: 5 -bdc: (float) Bias of the drift correction images (V). Default: -1 -tdc: (float) Time per line for drift correction images (s). Default: 0.3 -tbdc: (float) Backward direction speed multiplier for drift correct image. E.g. 1=same speed, 2=twice as fast, 0.5=half speed. Default: 1 -pxdc: (int) Number of pixels in drift correct images. 0=no drift correction. Default: 128 -lxdc: (int) Number of lines in drift correct image. 0=keep same ratio as px:lx. Default: 0 -bi: (float) Initial Bias (V). Default: -1 -bf: (float) Final Bias (V). Default: 1 -px: (int) Number of pixels in images. Default: nanonis settings -lx: (int) Number of lines in images. 0=same as px. Default: 0 -tlf: (float) Time per line (forward direction) (s). Default: nanonis settings -tb: (float) Backward direction speed multiplier. E.g. 1=same speed, 2=twice as fast, 0.5=half speed. Default: 1 -s: (str) Suffix for the set of bias dep sxm files. Default: sb-biasdep	Take a series of bias dependent images with drift correction (optional)	bias_dep -n=4 -bi=2 -bf=0.5 -tlf=0.5 -tb=2 -px=256 -dcpx=128
zdep	-zi: (float) Initial tip lift from setpoint (m). Default: -10e-12 -zf: (float) Final tip lift from setpoint (m). Default: 10e-12 -nz: (int) Number of scans between zi and zf. Default: 5 -iset: (float) Setpoint current (A). Limited to 1 nA. zi and zf are relative to this setpoint. Default: nanonis settings -bset: (float) Setpoint bias (V). Default: nanonis settings -dciset: (float) Setpoint current for drift correction (A). Default: nanonis settings -bias: (float) Scan bias during constant height (V). Default: nanonis settings -dcbias: (float) Scan bias during drift correction. 0 = dc off(V). Default: nanonis settings -ft: (float) Forward scan time per line during constant height (s). Default: nanonis settings -bt: (float) Backward scan time per line during constant height (s). Default: nanonis settings -dct: (float) Forward and backward time per line during drift correction (s). Default: nanonis settings -px: (int) Number of pixels for constant height image. Default: nanonis settings -dcpx: (int) Number of pixels for drift correction image. Default: nanonis settings -lx: (int) Number of lines for constant height image. 0=same as -px. Default: 0 -dclx: (int) Number of lines for drift correction image. 0=same as -dcpx. Default: 0 -s: (str) Suffix at the end of autosaved sxm files. Default: sb-zdep -gif: (int) Turn scans into a gif after completion. 0=No,1=Yes. Default: 1	z-dependant constant height imaging. Useful for constant current imaging or nc-AFM force volumes	zdep -bias=2e-3 -iset=20e-12 -dcbias=20e-3 -dciset=20e-12 -zi=-120e-12 -zf=-100e-12 -nz=5 -ft=120 -bt=1 -dct=0.4 -px=256 -dcpx=256 -s=nc-AFM_z-dep
afm_registration	-zset: (float) Initial tip lift from setpoint (m). Default: 0 -iset: (float) Setpoint current (A). Limited to 1 nA. zi and zf are relative to this setpoint. Default: nanonis settings -bset: (float) Bias at which the setpoint is measured (V). Default: nanonis settings -bias: (float) Scan bias during constant height (V). Default: nanonis settings -ft: (float) Forward scan time per line during constant height (s). Default: nanonis settings -bt: (float) Backward scan time per line during constant height (s). Default: nanonis settings -px: (int) Number of pixels for constant height image. Default: nanonis settings -lx: (int) Number of lines for constant height image. 0=same as -px. Default: 0 -lz: (int) Line number to perform tip lift -dz. lz is measured from the TOP of the scan frame, regardless of whether scan direction is up or down. i.e. lz=0 is at the top of the frame. Default: 0 -dz: (float) Tip lift (m) at line number -lz. Default: 0 -dir: (str) Scan dirction. Can be either 'up' or 'down'. Default: down -s: (str) Suffix at the end of autosaved sxm files. Default: sb-rego	nc_AFM registration. See for example this image

STM Tip Actions

Command	Inputs	Description	Example
move_area	-up: (int) Steps to go up before moving across. min 10. Default: 20 -upV: (float) Controller amplitude during up motor steps. Default: 270 -upF: (float) Controller frequency during up motor steps. Default: 2100 -dir: (str) Direction to go across (either X+, X-, Y+, Y-). Default: Y+ -steps: (int) Steps to move across after moving -up number of steps. Default: 10 -dirV: (float) Controller amplitude during across motor steps. Default: 130 -dirF: (float) Controller frequency during across motor steps. Default: 2100 -zon: (int) Turn the z-controller on after approaching. 1=on, 0=off. Default: 1	Move the tip to a new scan area. If a crash is detected during the move, the tip will be retracted until the current is below some threshold	move_area -dir=X+
tip_shape_props	-sod: (float) Switch off delay: the time (s) during which the Z position is averaged before switching the Z controller off. Default: nanonis settings -cb: (int) Change bias flag (0=Nanonis,1=Change Bias,2=Don't Change. Default: nanonis settings -b1: (float) The value applied to the Bias signal if cb is true. Default: nanonis settings -z1: (float) First tip lift (m) (i.e. -2e-9). Default: nanonis settings -t1: (float) Defines the time to ramp Z from current Z position to z1. Default: nanonis settings -b2: (float) Bias voltage applied just after the first Z ramping. Default: nanonis settings -t2: (float) Time to wait after applying the Bias Lift value b2. Default: nanonis settings -z3: (float) Height the tip is going to ramp for the second time (m) i.e. +5nm. Default: nanonis settings -t3: (float) Time to ramp Z in the second ramping [s].. Default: nanonis settings -wait: (float) Time to wait after restoring the initial Bias voltage. Default: nanonis settings -fb: (int) Restore the initial Z-Controller status. 0: off. 1: on. Default: nanonis settings	Configure the tip shaping properties in nanonis. Run with no options to return the current settings	tip_shape_props -z1=-2e-9
tip_shape		Execute a tip shaping action. Settings can be configures with tip_shape_props command	tip_shape
set_crash_safety	-c: (float) When moving the coarse piezos, a current above this value will be considered a crash and the tip will retract. -1 means no change. Default: -1 -V: (float) Voltage applied to the 'Z' piezo during tip retraction after a crash is detected. -1 means no change. Default: -1 -F: (float) Frequency applied to the 'Z' piezo during tip retraction after a crash is detected. -1 means no change. Default: -1	Settings applied to the Z piezo during a tip retraction after detecting a crash	set_crash_safety -c=3e-9
get_crash_safety		Return the settings for crash safety	get_crash_safety

STM Automation

Command	Inputs	Description	Example
auto_tip_shape	-n: (int) Max number of tip shapes to perform. -1 means keep going until criterea met. Default: 10 -wh: (float) Size of the square scan frame when imaging the clean surface. Default: 10e-9 -sym: (float) Minimum circularity requirement. 0=don't care, 1=perfectly circle. Default: 0.7 -size: (float) Max size of the desired tip imprint in units of nm2. Default: 1.2 -zQA: (float) z-lift when performing a light tip shape to asses quality of tip (m). Default: -0.9e-9 -ztip: (float) z-lift when performing a tip shape to alter the tip (m). Default: -1.5e-9 -st: (int) Drift compensation time (s). Default: 10	Routine that automatically prepares a nice tip. Assumes the substrate is a clean metal.	auto_tip_shape -sym=0.9 -size=2.1
auto_init	-light: (int) Flag to turn the light on/off before/after initialisation. This uses hk_light.turn_on() and hk_light.turn_off() functions. 0=Don't, 1=Do. Default: 0 -cameraPort: (int) cv2 camera port - usually 0 for desktops or 1 for laptops with an inbuilt camera.. Default: 0 -demo: (int) Load in an mp4 recording of the tip moving instead of using live feed. Default: 0	Initialise tip, sample, and clean metal positions using the camera feed	auto_init -cameraPort=0
move_tip_to_sample move_tip_to_clean	-light: (int) Flag to turn the light on before moving and off after moving. This uses hk_light.turn_on() and hk_light.turn_off() functions. 0=Don't, 1=Do. Default: 0 -cameraPort: (int) cv2 camera port - usually 0 for desktops or 1 for laptops with an inbuilt camera. Default: 0 -xStep: (int) Number of motor steps in the X direction before updating tip position. More=Faster but might lose the tip. Default: 100 -zStep: (int) Number of motor steps to move in +Z (upwards) before updating tip position. More=Faster but might lose the tip. Default: 250 -xV: (float) Piezo voltage when moving motor steps in x direction. Default: 130 -zV: (float) Piezo voltage when moving motor steps in z direction. Default: 180 -xF: (float) Piezo frequency when moving motor steps in x direction. Default: 1100 -zF: (float) Piezo frequency when moving motor steps in z direction. Default: 1100 -approach: (int) Approach when tip reaches target. 0=No,1=Yes. Default: 1 -demo: (int) Load in an mp4 recording of the tip moving instead of using live feed. Default: 0	After auto_init has been run, automatically move the tip to sample/clean metal locations using the camera	move_tip_to_sample -light=1

Intended Usage

This section describes how the automation aspect of Scanbot can be used for supervised or unsupervised operation. Note that you can still take advantage of Scanbot's data acquisition commands without automating the entire process.

1. Setup

These steps must be carried out before Scanbot is able to automatically move the tip between the sample and the clean metal.

1. Making sure the STM tip, sample of interest, and clean metal surface are in clear view of the camera.
2. Run the auto_init command. This will initialise the locations of the STM tip, sample, and clean metal.
   • Drive the tip completely outside the view of the camera, then click within the picture to set the background frame.
   • Drive the tip back into view of the camera, in close proximity to the sample.
   • Place a marker near the apex of the tip.
   • Place a marker at a safe distance above the clean metal.
   • Place a marker at a safe distance above the sample.
   • Note: Close any other applications that use the camera as they might prevent Scanbot from accessing it.
   • Note2: If the coarse piezos are moved manually at any point, Scanbot will have incorrect information about the location of the tip and this process must be repeated. Same goes for moving the camera.

2. End-to-End Supervised Test

It is advised to go through these steps, especially steps 1 and 3, each time auto_init is run.

1. Run the move_tip_to_clean command. This will move the tip to the location you set above the clean metal and begin an auto approach.
   • Configure the correct piezo voltages, frequency, and number of steps for your machine (see commands or run help move_tip_to_clean).
   • Observe the camera feed and ensure the tip is tracked correctly. If not, run stop, then rerun auto_init after refocusing the camera.
   • Note: run the stop command at any time to abort.
2. Once the tip has approached, run auto_tip_shape with the appropriate inputs for your system (e.g. metal used, etc.).
   • This function may take some time, for testing purposes run the stop command once you've verified it's working correctly.
3. Next run the move_tip_to_sample command.
   • Observe the camera feed and ensure the tip is tracked correctly.
4. Once the tip has approached, start a survey using the survey or survey2 command.

3. Supervised Operation Example

1. After setup, run the move_tip_to_sample command.
2. Upon approach, start a survey leaving -autotip=0.
3. Periodically monitor the scans stream (for Zulip users, each scan will be sent through the steam the survey was started from).
4. If the tip requires refinement, run stop followed by move_tip_to_clean with the options -tipshape=1, -return=1, and -run=survey
   • Here, Scanbot will automatically move the tip to the clean metal location set in auto_init
   • With -tipshape=1, the auto tip shaping process will begin after approaching
   • With -return=1, Scanbot will move the tip back to the sample location set in auto_init
   • With -run=survey, Scanbot will begin a survey with the same options as the previous survey
   • Note: If the function passed to the -run option has not been run previously, the default parameters will be used - check them to ensure they are compatible with your system in this case.

4. Fully Automated Operation

1. After setup, run the survey or survey2 command with the -autotip=1 option.
   • This will begin a survey and each scan will be analysed.
   • When scanbot detects that the tip is unstable, it will automatically navigate the tip to the clean metal surface and initiate the auto_tip_shape command.
   • Once the tip is refined, it will be moved back to the sample and the survey will continue.

Note: Although Scanbot excels at identifying noisy images resulting from tip-sample interaction, its capacity to evaluate overall image quality remains restricted. While it can detect unstable tips, it cannot identify doubled tips. In the event of a tip alteration resulting in multiple tips, Scanbot will not endeavor to reshape it. However, if the tip becomes unstable, Scanbot will recognise this and refine the tip accordingly.

Note2: Scanbot requires a camera feed to track the tip during automated operation. For this reason, there is a configurable hook that will allow Scanbot to control the STM light when required.

Operation Details

Auto Tip Shaping

The auto_tip_shape command is executed as follows:

1. A small scan (wh=<scan_size>) of the clean surface will be acquired.
   • The scan will be monitored line by line and if the area is contaminated or contains a step edge, the scan will be stopped and the scan frame will be moved.
2. If the small scan completes and the area is clean, a light tip shape (~0.8 nm) will be performed in the centre of the frame.
3. The imprint of the tip will be imaged.
4. The contour of the imprint's enclosed area and circularity will be calculated and compared against the criteria set by the options -size=<area_in_nm2> and -sym=<score_0-1>, respectively.
5. If the criteria are met, a successful tip shape is declared and the process stops here. Otherwise, a more aggressive tip shape is carried out and the process starts over.
6. In the event where the entire scan region is either unsuitable for tip shaping or the area has been destroyed by tip shaping, Scanbot will automatically call the move_area command, before continuing.

Auto Tip Maneuvering

The primary concern when it comes to automating movement of the STM head is accidental tip crashes. The following rules have been applied to any command where the coarse piezos are utilised:

• Scanbot can never move the tip in the Z- direction (down) when using the coarse piezo. Instead, auto approach is used.
• When moving in X or Y directions, the tunnelling current must be monitored after every 10 steps.
• A tunnelling current greater than the threshold set in the config file is considered a crash (see Tip Crash Safety).
• In the event of a crash, the tip will be retracted using the Z+ piezo and operation will cease.

Please make sure to set appropriate piezo voltages and frequencies when using any of the commands that control the coarse piezos. You can configure voltage and frequency limits in the config file.