Struct NanonisClient 

pub struct NanonisClient { /* private fields */ }

High-level client for communicating with Nanonis SPM systems via TCP.

NanonisClient provides a type-safe, Rust-friendly interface to the Nanonis TCP protocol. It handles connection management, protocol serialization/deserialization, and provides convenient methods for common operations like reading signals, controlling bias voltage, and managing the scanning probe.

Connection Management

The client maintains a persistent TCP connection to the Nanonis server. Connection timeouts and retry logic are handled automatically.

Protocol Support

Supports the standard Nanonis TCP command set including:

• Signal reading (Signals.ValsGet, Signals.NamesGet)
• Bias control (Bias.Set, Bias.Get)
• Position control (FolMe.XYPosSet, FolMe.XYPosGet)
• Motor control (Motor.* commands)
• Auto-approach (AutoApproach.* commands)

Examples

Basic usage:

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Read signal names
let signals = client.signal_names_get(false)?;

// Set bias voltage
client.set_bias(1.0)?;

// Read signal values
let values = client.signals_vals_get(vec![0, 1, 2], true)?;

With builder pattern:

use std::time::Duration;
use rusty_tip::NanonisClient;

let mut client = NanonisClient::builder()
    .address("192.168.1.100")
    .port(6501)
    .debug(true)
    .connect_timeout(Duration::from_secs(30))
    .build()?;

Implementations

impl NanonisClient

pub fn auto_approach_open(&mut self) -> Result<(), NanonisError>

Open the Auto-Approach module

pub fn auto_approach_on_off_set( &mut self, on_off: bool, ) -> Result<(), NanonisError>

Start or stop the Z auto-approach procedure

pub fn auto_approach_on_off_get(&mut self) -> Result<bool, NanonisError>

Get the on-off status of the Z auto-approach procedure

impl NanonisClient

pub fn set_bias(&mut self, voltage: f32) -> Result<(), NanonisError>

Set the bias voltage applied to the scanning probe tip.

This corresponds to the Nanonis Bias.Set command and is fundamental for tip-sample interaction control.

Arguments

• voltage - The bias voltage to apply (in volts)

Errors

Returns NanonisError if:

• The command fails or communication times out
• The voltage is outside the instrument’s safe operating range

Examples

use rusty_tip::{NanonisClient };

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set bias to 1.5V
client.set_bias(1.5)?;

// Set bias to -0.5V   
client.set_bias(-0.5)?;

pub fn get_bias(&mut self) -> Result<f32, NanonisError>

Get the current bias voltage applied to the scanning probe tip.

This corresponds to the Nanonis Bias.Get command.

Returns

The current bias voltage

Errors

Returns NanonisError if:

• The command fails or communication times out
• The server returns invalid or missing data

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let current_bias = client.get_bias()?;
println!("Current bias voltage: {:.3}V", current_bias);

pub fn bias_range_set( &mut self, bias_range_index: u16, ) -> Result<(), NanonisError>

Set the range of the bias voltage, if different ranges are available.

Sets the bias voltage range by selecting from available ranges. Use bias_range_get() first to retrieve the list of available ranges.

Arguments

• bias_range_index - Index from the list of ranges (0-based)

Errors

Returns NanonisError if:

• Invalid range index is provided
• Communication timeout or protocol error

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// First get available ranges
let (ranges, current_index) = client.bias_range_get()?;
println!("Available ranges: {:?}", ranges);

// Set to range index 1
client.bias_range_set(1)?;

pub fn bias_range_get(&mut self) -> Result<(Vec<String>, u16), NanonisError>

Get the selectable ranges of bias voltage and the index of the selected one.

Returns all available bias voltage ranges and which one is currently selected. This information is needed for bias_range_set() and bias_calibr_set/get().

Returns

A tuple containing:

• Vec<String> - Array of available bias range descriptions
• u16 - Index of currently selected range

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (ranges, current_index) = client.bias_range_get()?;
println!("Current range: {} (index {})", ranges[current_index as usize], current_index);

for (i, range) in ranges.iter().enumerate() {
    println!("Range {}: {}", i, range);
}

pub fn bias_calibr_set( &mut self, calibration: f32, offset: f32, ) -> Result<(), NanonisError>

Set the calibration and offset of bias voltage.

Sets the calibration parameters for the currently selected bias range. If multiple ranges are available, this affects only the selected range.

Arguments

• calibration - Calibration factor (typically in V/V or similar units)
• offset - Offset value in the same units as calibration

Errors

Returns NanonisError if communication fails or invalid parameters provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set calibration factor and offset for current range
client.bias_calibr_set(1.0, 0.0)?;

// Apply a small offset correction
client.bias_calibr_set(0.998, 0.005)?;
Ok::<(), Box<dyn std::error::Error>>(())

pub fn bias_calibr_get(&mut self) -> Result<(f32, f32), NanonisError>

Get the calibration and offset of bias voltage.

Returns the calibration parameters for the currently selected bias range. If multiple ranges are available, this returns values for the selected range.

Returns

A tuple containing:

• f32 - Calibration factor
• f32 - Offset value

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (calibration, offset) = client.bias_calibr_get()?;
println!("Bias calibration: {:.6}, offset: {:.6}", calibration, offset);
Ok::<(), Box<dyn std::error::Error>>(())

pub fn bias_pulse( &mut self, wait_until_done: bool, pulse_width_s: f32, bias_value_v: f32, z_controller_hold: u16, pulse_mode: u16, ) -> Result<(), NanonisError>

Generate one bias pulse.

Applies a bias voltage pulse for a specified duration. This is useful for tunneling spectroscopy, tip conditioning, or sample manipulation experiments.

Arguments

• wait_until_done - If true, function waits until pulse completes
• pulse_width_s - Pulse duration in seconds
• bias_value_v - Bias voltage during pulse (in volts)
• z_controller_hold - Z-controller behavior: 0=no change, 1=hold, 2=don’t hold
• pulse_mode - Pulse mode: 0=no change, 1=relative to current, 2=absolute value

Errors

Returns NanonisError if:

• Invalid pulse parameters (negative duration, etc.)
• Bias voltage exceeds safety limits
• Communication timeout or protocol error

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Apply a 100ms pulse at +2V, holding Z-controller, absolute voltage
client.bias_pulse(true, 0.1, 2.0, 1, 2)?;

// Quick +0.5V pulse relative to current bias, don't wait
client.bias_pulse(false, 0.01, 0.5, 0, 1)?;

// Long conditioning pulse at -3V absolute, hold Z-controller
client.bias_pulse(true, 1.0, -3.0, 1, 2)?;

impl NanonisClient

pub fn bias_sweep_open(&mut self) -> Result<(), NanonisError>

Open the Bias Sweep module.

Opens and initializes the Bias Sweep module for bias voltage sweep measurements. This must be called before performing bias sweep operations.

Errors

Returns NanonisError if communication fails or module cannot be opened.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Open bias sweep module
client.bias_sweep_open()?;
println!("Bias Sweep module opened");

pub fn bias_sweep_start( &mut self, get_data: bool, sweep_direction: bool, z_controller_status: u32, save_base_name: &str, reset_bias: bool, ) -> Result<(Vec<String>, Vec<Vec<f32>>), NanonisError>

Start a bias sweep measurement.

Starts a bias voltage sweep with the configured parameters. The sweep will step through bias voltages between the set limits while recording selected channels.

Arguments

• get_data - If true, returns measurement data; if false, only starts measurement
• sweep_direction - Sweep direction: true starts from lower limit, false from upper
• z_controller_status - Z-controller behavior: 0=no change, 1=turn off, 2=don’t turn off
• save_base_name - Base filename for saving data (empty for no change)
• reset_bias - Whether to reset bias after sweep: true for on, false for off

Returns

If get_data is true, returns a tuple containing:

• Vec<String> - Channel names
• Vec<Vec<f32>> - 2D measurement data [rows][columns]

Errors

Returns NanonisError if communication fails or sweep cannot start.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Start sweep and get data, from lower to upper limit, turn off Z-controller
let (channels, data) = client.bias_sweep_start(
    true,           // get_data
    true,           // sweep from lower limit
    1,              // turn off Z-controller
    "bias_sweep_001", // save basename
    true            // reset bias after sweep
)?;
println!("Recorded {} channels with {} points", channels.len(), data.len());

// Just start sweep without getting data
let (_, _) = client.bias_sweep_start(false, true, 0, "", false)?;

pub fn bias_sweep_props_set( &mut self, number_of_steps: u16, period_ms: u16, autosave: u16, save_dialog_box: u16, ) -> Result<(), NanonisError>

Set the bias sweep configuration parameters.

Configures the bias sweep measurement parameters including number of steps, timing, and save behavior.

Arguments

• number_of_steps - Number of bias steps in the sweep (0 = no change)
• period_ms - Period between steps in milliseconds (0 = no change)
• autosave - Auto-save behavior: 0=no change, 1=on, 2=off
• save_dialog_box - Show save dialog: 0=no change, 1=on, 2=off

Errors

Returns NanonisError if communication fails or invalid parameters provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Configure 100 steps, 50ms per step, auto-save on, no dialog
client.bias_sweep_props_set(100, 50, 1, 2)?;

// High resolution sweep with slower timing
client.bias_sweep_props_set(500, 100, 1, 2)?;

pub fn bias_sweep_limits_set( &mut self, lower_limit: f32, upper_limit: f32, ) -> Result<(), NanonisError>

Set the bias sweep voltage limits.

Configures the voltage range for the bias sweep. The sweep will step between these limits according to the configured number of steps.

Arguments

• lower_limit - Lower voltage limit in volts
• upper_limit - Upper voltage limit in volts

Errors

Returns NanonisError if communication fails or invalid limits provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set sweep range from -2V to +2V
client.bias_sweep_limits_set(-2.0, 2.0)?;

// Positive voltage sweep only
client.bias_sweep_limits_set(0.0, 5.0)?;

// Negative voltage sweep
client.bias_sweep_limits_set(-3.0, 0.0)?;

pub fn bias_sweep_limits_get(&mut self) -> Result<(f32, f32), NanonisError>

Get the current bias sweep voltage limits.

Returns the voltage range configuration for bias sweep measurements.

Returns

A tuple containing:

• f32 - Lower voltage limit in volts
• f32 - Upper voltage limit in volts

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (lower, upper) = client.bias_sweep_limits_get()?;
println!("Bias sweep range: {:.2}V to {:.2}V", lower, upper);
println!("Sweep span: {:.2}V", upper - lower);

// Check if limits are reasonable
if (upper - lower).abs() < 0.1 {
    println!("Warning: Very narrow sweep range");
}

impl NanonisClient

pub fn current_get(&mut self) -> Result<f32, NanonisError>

Get the current tunneling current value.

Returns the instantaneous tunneling current measurement from the current amplifier. This is one of the most fundamental measurements in STM, providing direct information about the tip-sample conductance.

Returns

Current value in Amperes (A).

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let current = client.current_get()?;
println!("Tunneling current: {:.3e} A", current);

// Convert to more convenient units
if current.abs() < 1e-9 {
    println!("Current: {:.1} pA", current * 1e12);
} else {
    println!("Current: {:.1} nA", current * 1e9);
}

pub fn current_100_get(&mut self) -> Result<f32, NanonisError>

Get the current value from the “Current 100” module.

Returns the tunneling current from the specialized Current 100 module, which may have different gain or filtering characteristics than the main current amplifier.

Returns

Current 100 value in Amperes (A).

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let current_100 = client.current_100_get()?;
println!("Current 100 module: {:.3e} A", current_100);

pub fn current_beem_get(&mut self) -> Result<f32, NanonisError>

Get the BEEM current value from the corresponding module.

Returns the Ballistic Electron Emission Microscopy (BEEM) current value in systems equipped with BEEM capabilities. BEEM measures hot electrons transmitted through thin metal films.

Returns

BEEM current value in Amperes (A).

Errors

Returns NanonisError if:

• BEEM module is not available or not configured
• Communication fails or protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let beem_current = client.current_beem_get()?;
println!("BEEM current: {:.3e} A", beem_current);

pub fn current_gain_set( &mut self, gain_index: i32, filter_index: i32, ) -> Result<(), NanonisError>

Set the gain and filter of the current amplifier.

Configures the current amplifier’s gain and filtering characteristics. Use current_gains_get() to retrieve the available gain and filter options before setting specific indices.

Arguments

• gain_index - Index from the list of available gains
• filter_index - Index from the list of available filters

Errors

Returns NanonisError if:

• Invalid gain or filter index provided
• Communication fails or protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Get available options first
let (gains, current_gain_idx, filters, current_filter_idx) = client.current_gains_get()?;
println!("Available gains: {:?}", gains);
println!("Available filters: {:?}", filters);

// Set to high gain (index 3) with medium filtering (index 1)
client.current_gain_set(3, 1)?;

pub fn current_gains_get( &mut self, ) -> Result<(Vec<String>, u16, Vec<String>, i32), NanonisError>

Get the available gains and filters of the current amplifier.

Returns all selectable gains and filters for the current amplifier, along with the currently selected indices. This information is needed for current_gain_set().

Returns

A tuple containing:

• Vec<String> - Array of available gain descriptions
• u16 - Index of currently selected gain
• Vec<String> - Array of available filter descriptions
• i32 - Index of currently selected filter

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (gains, gain_idx, filters, filter_idx) = client.current_gains_get()?;

println!("Current gain: {} (index {})", gains[gain_idx as usize], gain_idx);
println!("Current filter: {} (index {})", filters[filter_idx as usize], filter_idx);

// List all available options
for (i, gain) in gains.iter().enumerate() {
    println!("Gain {}: {}", i, gain);
}

pub fn current_calibr_set( &mut self, gain_index: i32, calibration: f64, offset: f64, ) -> Result<(), NanonisError>

Set the calibration and offset for a specific gain in the Current module.

Configures the calibration parameters for accurate current measurements. Each gain setting can have its own calibration and offset values.

Arguments

• gain_index - Index of the gain to calibrate (-1 for currently selected gain)
• calibration - Calibration factor (typically A/V or similar)
• offset - Offset value in the same units

Errors

Returns NanonisError if communication fails or invalid parameters provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Calibrate currently selected gain
client.current_calibr_set(-1, 1.0e-9, 0.0)?;

// Calibrate specific gain (index 2) with offset correction
client.current_calibr_set(2, 9.87e-10, -1.5e-12)?;

pub fn current_calibr_get( &mut self, gain_index: i32, ) -> Result<(f64, f64), NanonisError>

Get the calibration and offset for a specific gain in the Current module.

Returns the calibration parameters for the specified gain setting.

Arguments

• gain_index - Index of the gain to query (-1 for currently selected gain)

Returns

A tuple containing:

• f64 - Calibration factor
• f64 - Offset value

Errors

Returns NanonisError if communication fails or invalid gain index.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Get calibration for currently selected gain
let (calibration, offset) = client.current_calibr_get(-1)?;
println!("Current calibration: {:.3e}, offset: {:.3e}", calibration, offset);

// Check calibration for specific gain
let (cal, off) = client.current_calibr_get(2)?;

impl NanonisClient

pub fn folme_xy_pos_get( &mut self, wait_for_newest_data: bool, ) -> Result<Position, NanonisError>

Get the current x-y position

pub fn folme_xy_pos_set( &mut self, position: Position, wait_until_finished: bool, ) -> Result<(), NanonisError>

Set the x-y position

pub fn folme_speed_set( &mut self, speed: f32, custom_speed: bool, ) -> Result<(), NanonisError>

impl NanonisClient

pub fn motor_start_move( &mut self, direction: impl Into<MotorDirection>, number_of_steps: impl Into<u16>, group: impl Into<MotorGroup>, wait_until_finished: bool, ) -> Result<(), NanonisError>

Move the coarse positioning device (motor, piezo actuator)

pub fn motor_start_closed_loop( &mut self, movement_mode: MovementMode, target_position: Position3D, wait_until_finished: bool, group: MotorGroup, ) -> Result<(), NanonisError>

Move the coarse positioning device in closed loop

pub fn motor_stop_move(&mut self) -> Result<(), NanonisError>

Stop the motor motion

pub fn motor_pos_get( &mut self, group: MotorGroup, timeout: Duration, ) -> Result<Position3D, NanonisError>

Get the positions of the motor control module

pub fn motor_step_counter_get( &mut self, reset_x: bool, reset_y: bool, reset_z: bool, ) -> Result<(i32, i32, i32), NanonisError>

Get step counter values and optionally reset them Available only on Attocube ANC150 devices

pub fn motor_freq_amp_get( &mut self, axis: MotorAxis, ) -> Result<(Frequency, Amplitude), NanonisError>

Get frequency and amplitude of the motor control module Available only for PD5, PMD4, and Attocube ANC150 devices

pub fn motor_freq_amp_set( &mut self, frequency: impl Into<Frequency>, amplitude: impl Into<Amplitude>, axis: impl Into<MotorAxis>, ) -> Result<(), NanonisError>

Set frequency and amplitude of the motor control module Available only for PD5, PMD4, and Attocube ANC150 devices

impl NanonisClient

pub fn osci1t_ch_set(&mut self, channel_index: i32) -> Result<(), NanonisError>

Set the channel to display in the Oscilloscope 1-Channel channel_index: 0-23, corresponds to signals assigned to the 24 slots in the Signals Manager

pub fn osci1t_ch_get(&mut self) -> Result<i32, NanonisError>

Get the channel displayed in the Oscilloscope 1-Channel Returns: channel index (0-23)

pub fn osci1t_timebase_set( &mut self, timebase_index: i32, ) -> Result<(), NanonisError>

Set the timebase in the Oscilloscope 1-Channel Use osci1t_timebase_get() first to obtain available timebases, then use the index

pub fn osci1t_timebase_get(&mut self) -> Result<(i32, Vec<f32>), NanonisError>

Get the timebase in the Oscilloscope 1-Channel Returns: (timebase_index, timebases_array)

pub fn osci1t_trig_set( &mut self, trigger_mode: u16, trigger_slope: u16, trigger_level: f64, trigger_hysteresis: f64, ) -> Result<(), NanonisError>

Set the trigger configuration in the Oscilloscope 1-Channel trigger_mode: 0 = Immediate, 1 = Level, 2 = Auto trigger_slope: 0 = Falling, 1 = Rising

pub fn osci1t_trig_get(&mut self) -> Result<(u16, u16, f64, f64), NanonisError>

Get the trigger configuration in the Oscilloscope 1-Channel Returns: (trigger_mode, trigger_slope, trigger_level, trigger_hysteresis)

pub fn osci1t_run(&mut self) -> Result<(), NanonisError>

Start the Oscilloscope 1-Channel

pub fn osci1t_data_get( &mut self, data_to_get: u16, ) -> Result<(f64, f64, i32, Vec<f64>), NanonisError>

Get the graph data from the Oscilloscope 1-Channel data_to_get: 0 = Current, 1 = Next trigger, 2 = Wait 2 triggers Returns: (t0, dt, size, data_values)

impl NanonisClient

pub fn osci2t_ch_set( &mut self, channel_a_index: i32, channel_b_index: i32, ) -> Result<(), NanonisError>

Set the channels to display in the Oscilloscope 2-Channels channel_a_index: 0-23, channel A signal index
channel_b_index: 0-23, channel B signal index

pub fn osci2t_ch_get(&mut self) -> Result<(i32, i32), NanonisError>

Get the channels displayed in the Oscilloscope 2-Channels Returns: (channel_a_index, channel_b_index)

pub fn osci2t_timebase_set( &mut self, timebase_index: u16, ) -> Result<(), NanonisError>

Set the timebase in the Oscilloscope 2-Channels Use osci2t_timebase_get() first to obtain available timebases, then use the index

pub fn osci2t_timebase_get(&mut self) -> Result<(u16, Vec<f32>), NanonisError>

Get the timebase in the Oscilloscope 2-Channels Returns: (timebase_index, timebases_array)

pub fn osci2t_oversampl_set( &mut self, oversampling_index: u16, ) -> Result<(), NanonisError>

Set the oversampling in the Oscilloscope 2-Channels oversampling_index: 0=50 samples, 1=20, 2=10, 3=5, 4=2, 5=1 sample (no averaging)

pub fn osci2t_oversampl_get(&mut self) -> Result<u16, NanonisError>

Get the oversampling in the Oscilloscope 2-Channels Returns: oversampling index (0=50 samples, 1=20, 2=10, 3=5, 4=2, 5=1 sample)

pub fn osci2t_trig_set( &mut self, trigger_mode: u16, trig_channel: u16, trigger_slope: u16, trigger_level: f64, trigger_hysteresis: f64, trig_position: f64, ) -> Result<(), NanonisError>

Set the trigger configuration in the Oscilloscope 2-Channels trigger_mode: 0 = Immediate, 1 = Level, 2 = Auto trig_channel: trigger channel trigger_slope: 0 = Falling, 1 = Rising

pub fn osci2t_trig_get( &mut self, ) -> Result<(u16, u16, u16, f64, f64, f64), NanonisError>

Get the trigger configuration in the Oscilloscope 2-Channels Returns: (trigger_mode, trig_channel, trigger_slope, trigger_level, trigger_hysteresis, trig_position)

pub fn osci2t_run(&mut self) -> Result<(), NanonisError>

Start the Oscilloscope 2-Channels

pub fn osci2t_data_get( &mut self, data_to_get: u16, ) -> Result<(f64, f64, Vec<f64>, Vec<f64>), NanonisError>

Get the graph data from the Oscilloscope 2-Channels data_to_get: 0 = Current, 1 = Next trigger, 2 = Wait 2 triggers Returns: (t0, dt, channel_a_data, channel_b_data)

impl NanonisClient

pub fn osci_hr_ch_set( &mut self, osci_index: impl Into<OscilloscopeIndex>, signal_index: impl Into<SignalIndex>, ) -> Result<(), NanonisError>

Set the measured signal index of the selected channel from the Oscilloscope High Resolution

pub fn osci_hr_ch_get( &mut self, osci_index: impl Into<OscilloscopeIndex>, ) -> Result<SignalIndex, NanonisError>

Get the measured signal index of the selected channel from the Oscilloscope High Resolution

pub fn osci_hr_oversampl_set( &mut self, oversampling_index: i32, ) -> Result<(), NanonisError>

Set the oversampling index of the Oscilloscope High Resolution

pub fn osci_hr_oversampl_get(&mut self) -> Result<i32, NanonisError>

Get the oversampling index of the Oscilloscope High Resolution

pub fn osci_hr_calibr_mode_set( &mut self, osci_index: i32, calibration_mode: u16, ) -> Result<(), NanonisError>

Set the calibration mode of the selected channel from the Oscilloscope High Resolution calibration_mode: 0 = Raw values, 1 = Calibrated values

pub fn osci_hr_calibr_mode_get( &mut self, osci_index: i32, ) -> Result<u16, NanonisError>

Get the calibration mode of the selected channel from the Oscilloscope High Resolution Returns: 0 = Raw values, 1 = Calibrated values

pub fn osci_hr_samples_set( &mut self, number_of_samples: impl Into<SampleCount>, ) -> Result<(), NanonisError>

Set the number of samples to acquire in the Oscilloscope High Resolution

pub fn osci_hr_samples_get(&mut self) -> Result<SampleCount, NanonisError>

Get the number of samples to acquire in the Oscilloscope High Resolution

pub fn osci_hr_pre_trig_set( &mut self, pre_trigger_samples: u32, pre_trigger_s: f64, ) -> Result<(), NanonisError>

Set the Pre-Trigger Samples or Seconds in the Oscilloscope High Resolution

pub fn osci_hr_pre_trig_get(&mut self) -> Result<i32, NanonisError>

Get the Pre-Trigger Samples in the Oscilloscope High Resolution

pub fn osci_hr_run(&mut self) -> Result<(), NanonisError>

Start the Oscilloscope High Resolution module

pub fn osci_hr_osci_data_get( &mut self, osci_index: i32, data_to_get: u16, timeout_s: f64, ) -> Result<(String, f64, Vec<f32>, bool), NanonisError>

Get the graph data of the selected channel from the Oscilloscope High Resolution data_to_get: 0 = Current returns the currently displayed data, 1 = Next trigger waits for the next trigger Returns: (timestamp, time_delta, data_values, timeout_occurred)

pub fn osci_hr_trig_mode_set( &mut self, trigger_mode: impl Into<TriggerMode>, ) -> Result<(), NanonisError>

Set the trigger mode in the Oscilloscope High Resolution

pub fn osci_hr_trig_mode_get(&mut self) -> Result<TriggerMode, NanonisError>

Get the trigger mode in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_ch_set( &mut self, level_trigger_channel_index: i32, ) -> Result<(), NanonisError>

Set the Level Trigger Channel index in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_ch_get(&mut self) -> Result<i32, NanonisError>

Get the Level Trigger Channel index in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_val_set( &mut self, level_trigger_value: impl Into<TriggerLevel>, ) -> Result<(), NanonisError>

Set the Level Trigger value in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_val_get(&mut self) -> Result<TriggerLevel, NanonisError>

Get the Level Trigger value in the Oscilloscope High Resolution

pub fn osci_hr_trig_arm_mode_set( &mut self, trigger_arming_mode: u16, ) -> Result<(), NanonisError>

Set the Trigger Arming Mode in the Oscilloscope High Resolution

pub fn osci_hr_trig_arm_mode_get(&mut self) -> Result<u16, NanonisError>

Get the Trigger Arming Mode in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_hyst_set( &mut self, hysteresis: f64, ) -> Result<(), NanonisError>

Set the Level Trigger Hysteresis in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_hyst_get(&mut self) -> Result<f64, NanonisError>

Get the Level Trigger Hysteresis in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_slope_set( &mut self, slope: u16, ) -> Result<(), NanonisError>

Set the Level Trigger Slope in the Oscilloscope High Resolution

pub fn osci_hr_trig_lev_slope_get(&mut self) -> Result<u16, NanonisError>

Get the Level Trigger Slope in the Oscilloscope High Resolution

impl NanonisClient

pub fn pll_amp_ctrl_setpnt_set( &mut self, modulator_index: i32, setpoint_m: f32, ) -> Result<(), NanonisError>

Set the amplitude controller setpoint for a PLL modulator.

Sets the amplitude controller setpoint value for the specified PLL modulator. This controls the target oscillation amplitude for the phase-locked loop.

Arguments

• modulator_index - PLL modulator index (starts from 1)
• setpoint_m - Amplitude setpoint in meters

Errors

Returns NanonisError if communication fails or invalid modulator index.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set amplitude setpoint for first PLL to 1 nanometer
client.pll_amp_ctrl_setpnt_set(1, 1e-9)?;

// Set amplitude setpoint for second PLL to 500 picometers
client.pll_amp_ctrl_setpnt_set(2, 500e-12)?;

pub fn pll_amp_ctrl_setpnt_get( &mut self, modulator_index: i32, ) -> Result<f32, NanonisError>

Get the amplitude controller setpoint for a PLL modulator.

Returns the current amplitude controller setpoint value for the specified PLL modulator.

Arguments

• modulator_index - PLL modulator index (starts from 1)

Returns

• f32 - Current amplitude setpoint in meters

Errors

Returns NanonisError if communication fails or invalid modulator index.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Get current amplitude setpoint for first PLL
let setpoint = client.pll_amp_ctrl_setpnt_get(1)?;
println!("Current amplitude setpoint: {:.2e} m", setpoint);

// Check if setpoint is within expected range
if setpoint > 1e-9 {
    println!("Amplitude setpoint is greater than 1 nm");
}

pub fn pll_amp_ctrl_on_off_set( &mut self, modulator_index: i32, status: bool, ) -> Result<(), NanonisError>

Set the amplitude controller on/off status for a PLL modulator.

Switches the amplitude controller for the specified PLL modulator on or off. When enabled, the amplitude controller actively maintains the oscillation amplitude at the setpoint value.

Arguments

• modulator_index - PLL modulator index (starts from 1)
• status - true to turn on, false to turn off

Errors

Returns NanonisError if communication fails or invalid modulator index.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Turn on amplitude controller for first PLL
client.pll_amp_ctrl_on_off_set(1, true)?;

// Turn off amplitude controller for second PLL
client.pll_amp_ctrl_on_off_set(2, false)?;

pub fn pll_amp_ctrl_on_off_get( &mut self, modulator_index: i32, ) -> Result<bool, NanonisError>

Get the amplitude controller on/off status for a PLL modulator.

Returns the current on/off status of the amplitude controller for the specified PLL modulator.

Arguments

• modulator_index - PLL modulator index (starts from 1)

Returns

• bool - true if controller is on, false if off

Errors

Returns NanonisError if communication fails or invalid modulator index.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Check amplitude controller status for first PLL
let is_on = client.pll_amp_ctrl_on_off_get(1)?;
if is_on {
    println!("Amplitude controller is active");
} else {
    println!("Amplitude controller is inactive");
}

// Enable controller if it's off
if !is_on {
    client.pll_amp_ctrl_on_off_set(1, true)?;
}

pub fn pll_amp_ctrl_gain_set( &mut self, modulator_index: i32, p_gain_v_div_m: f32, time_constant_s: f32, ) -> Result<(), NanonisError>

Set the amplitude controller gain parameters for a PLL modulator.

Sets the proportional gain and time constant for the amplitude controller of the specified PLL modulator. These parameters control the response characteristics of the amplitude control loop.

Arguments

• modulator_index - PLL modulator index (starts from 1)
• p_gain_v_div_m - Proportional gain in V/m
• time_constant_s - Time constant in seconds

Errors

Returns NanonisError if communication fails or invalid modulator index.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set moderate gain and fast response for first PLL
client.pll_amp_ctrl_gain_set(1, 1e6, 0.01)?;

// Set higher gain and slower response for second PLL
client.pll_amp_ctrl_gain_set(2, 5e6, 0.1)?;

pub fn pll_amp_ctrl_gain_get( &mut self, modulator_index: i32, ) -> Result<(f32, f32), NanonisError>

Get the amplitude controller gain parameters for a PLL modulator.

Returns the current proportional gain and time constant settings for the amplitude controller of the specified PLL modulator.

Arguments

• modulator_index - PLL modulator index (starts from 1)

Returns

• (f32, f32) - Tuple of (proportional gain in V/m, time constant in seconds)

Errors

Returns NanonisError if communication fails or invalid modulator index.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Get current gain parameters for first PLL
let (p_gain, time_const) = client.pll_amp_ctrl_gain_get(1)?;
println!("P gain: {:.2e} V/m, Time constant: {:.3} s", p_gain, time_const);

// Check if parameters are within acceptable range
if p_gain < 1e5 {
    println!("Warning: Low proportional gain");
}
if time_const > 1.0 {
    println!("Warning: Slow time constant");
}

impl NanonisClient

pub fn safe_tip_on_off_set( &mut self, safe_tip_on: bool, ) -> Result<(), NanonisError>

Switch the Safe Tip feature on or off.

The Safe Tip feature provides automatic tip protection by monitoring specific signals and triggering safety actions when dangerous conditions are detected. This prevents tip crashes and damage during scanning and approach operations.

Arguments

• safe_tip_on - true to enable Safe Tip, false to disable

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Enable Safe Tip protection
client.safe_tip_on_off_set(true)?;
println!("Safe Tip protection enabled");

// Disable for manual operations
client.safe_tip_on_off_set(false)?;

pub fn safe_tip_on_off_get(&mut self) -> Result<bool, NanonisError>

Get the current on-off status of the Safe Tip feature.

Returns whether the Safe Tip protection is currently active. This is essential for verifying tip safety status before starting potentially dangerous operations.

Returns

true if Safe Tip is enabled, false if disabled.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

if client.safe_tip_on_off_get()? {
    println!("Safe Tip protection is active");
} else {
    println!("Warning: Safe Tip protection is disabled");
}

pub fn safe_tip_signal_get(&mut self) -> Result<f32, NanonisError>

Get the current Safe Tip signal value.

Returns the current value of the signal being monitored by the Safe Tip system. This allows real-time monitoring of the safety-critical parameter.

Returns

Current signal value being monitored by Safe Tip.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let signal_value = client.safe_tip_signal_get()?;
println!("Safe Tip signal: {:.3e}", signal_value);

// Check if approaching threshold
let (_, _, threshold) = client.safe_tip_props_get()?;
if signal_value.abs() > threshold * 0.8 {
    println!("Warning: Approaching Safe Tip threshold!");
}

pub fn safe_tip_props_set( &mut self, auto_recovery: bool, auto_pause_scan: bool, threshold: f32, ) -> Result<(), NanonisError>

Set the Safe Tip configuration parameters.

Configures the behavior of the Safe Tip protection system including automatic recovery and scan pause features. These settings determine how the system responds to safety threshold violations.

Arguments

• auto_recovery - Enable automatic Z-controller recovery after Safe Tip event
• auto_pause_scan - Enable automatic scan pause/hold on Safe Tip events
• threshold - Signal threshold value that triggers Safe Tip protection

Errors

Returns NanonisError if communication fails or invalid parameters provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Configure Safe Tip with automatic recovery and scan pause
client.safe_tip_props_set(true, true, 1e-9)?;  // 1 nA threshold

// Conservative settings for delicate samples
client.safe_tip_props_set(true, true, 500e-12)?;  // 500 pA threshold

pub fn safe_tip_props_get(&mut self) -> Result<(bool, bool, f32), NanonisError>

Get the current Safe Tip configuration.

Returns all Safe Tip protection parameters including automatic recovery settings, scan pause behavior, and the safety threshold value.

Returns

A tuple containing:

• bool - Auto recovery enabled/disabled
• bool - Auto pause scan enabled/disabled
• f32 - Threshold value for triggering Safe Tip protection

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (auto_recovery, auto_pause, threshold) = client.safe_tip_props_get()?;

println!("Safe Tip Configuration:");
println!("  Auto recovery: {}", if auto_recovery { "On" } else { "Off" });
println!("  Auto pause scan: {}", if auto_pause { "On" } else { "Off" });
println!("  Threshold: {:.3e}", threshold);

// Convert threshold to more readable units
if threshold < 1e-9 {
    println!("  Threshold: {:.1} pA", threshold * 1e12);
} else {
    println!("  Threshold: {:.1} nA", threshold * 1e9);
}

pub fn z_ctrl_tip_lift_set( &mut self, tip_lift_m: f32, ) -> Result<(), NanonisError>

Set the tip lift distance for safety operations.

Sets the distance the tip is lifted when safety procedures are triggered. This is part of the Z-controller tip safety system and works in conjunction with Safe Tip to provide comprehensive tip protection.

Note: This function is part of the Z-controller system but included here for safety-related operations.

Arguments

• tip_lift_m - Tip lift distance in meters (positive = away from surface)

Errors

Returns NanonisError if communication fails or invalid lift distance.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set conservative lift distance for safety
client.z_ctrl_tip_lift_set(100e-9)?;  // 100 nm lift

// Set larger lift for problematic areas
client.z_ctrl_tip_lift_set(500e-9)?;  // 500 nm lift

pub fn z_ctrl_tip_lift_get(&mut self) -> Result<f32, NanonisError>

Get the current tip lift distance setting.

Returns the distance the tip will be lifted during safety operations. This helps verify that adequate safety margins are configured.

Returns

Current tip lift distance in meters.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let tip_lift = client.z_ctrl_tip_lift_get()?;
println!("Tip lift distance: {:.1} nm", tip_lift * 1e9);

// Check if lift distance is adequate
if tip_lift < 50e-9 {
    println!("Warning: Tip lift may be too small for safe operation");
}

pub fn safety_status_comprehensive( &mut self, ) -> Result<(bool, f32, f32, f32, bool), NanonisError>

Perform a comprehensive safety check of all tip protection systems.

This convenience method checks the status of all major tip safety systems and returns a summary. Use this before starting critical operations to ensure all safety measures are properly configured.

Returns

A tuple containing safety status information:

• bool - Safe Tip enabled
• f32 - Current Safe Tip signal value
• f32 - Safe Tip threshold
• f32 - Tip lift distance (m)
• bool - Z-controller status

Errors

Returns NanonisError if any safety system check fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (safe_tip_on, signal_val, threshold, tip_lift, z_ctrl_on) =
    client.safety_status_comprehensive()?;

println!("=== Tip Safety Status ===");
println!("Safe Tip: {}", if safe_tip_on { "ENABLED" } else { "DISABLED" });
println!("Signal: {:.2e} / Threshold: {:.2e}", signal_val, threshold);
println!("Tip Lift: {:.1} nm", tip_lift * 1e9);
println!("Z-Controller: {}", if z_ctrl_on { "ON" } else { "OFF" });

if !safe_tip_on {
    println!("WARNING: Safe Tip protection is disabled!");
}

impl NanonisClient

pub fn scan_action( &mut self, scan_action: ScanAction, scan_direction: ScanDirection, ) -> Result<(), NanonisError>

Start, stop, pause or resume a scan

pub fn scan_frame_set(&mut self, frame: ScanFrame) -> Result<(), NanonisError>

Configure the scan frame parameters

pub fn scan_frame_get(&mut self) -> Result<ScanFrame, NanonisError>

Get the scan frame parameters

pub fn scan_buffer_get(&mut self) -> Result<(Vec<i32>, i32, i32), NanonisError>

Get the scan buffer parameters Returns: (channel_indexes, pixels, lines)

pub fn scan_status_get(&mut self) -> Result<bool, NanonisError>

Get the current scan status.

Returns whether a scan is currently running or not.

Returns

true if scan is running, false if scan is not running.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

if client.scan_status_get()? {
    println!("Scan is currently running");
} else {
    println!("Scan is stopped");
}

pub fn scan_buffer_set( &mut self, channel_indexes: Vec<i32>, pixels: i32, lines: i32, ) -> Result<(), NanonisError>

Configure the scan buffer parameters.

Sets which channels to record during scanning and the scan resolution. The channel indexes refer to the 24 signals assigned in the Signals Manager (0-23).

Important: The number of pixels is coerced to the closest multiple of 16 because scan data is sent in packages of 16 pixels.

Arguments

• channel_indexes - Indexes of channels to record (0-23 for signals in Signals Manager)
• pixels - Number of pixels per line (coerced to multiple of 16)
• lines - Number of scan lines

Errors

Returns NanonisError if communication fails or invalid parameters provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Record channels 0, 1, and 2 with 512x512 resolution
client.scan_buffer_set(vec![0, 1, 2], 512, 512)?;

// High resolution scan with multiple channels
client.scan_buffer_set(vec![0, 1, 2, 3, 4], 1024, 1024)?;

pub fn scan_speed_set( &mut self, forward_linear_speed_m_s: f32, backward_linear_speed_m_s: f32, forward_time_per_line_s: f32, backward_time_per_line_s: f32, keep_parameter_constant: u16, speed_ratio: f32, ) -> Result<(), NanonisError>

Configure scan speed parameters.

Sets the tip scanning speeds for both forward and backward scan directions. You can specify either linear speed or time per line, and set speed ratios between forward and backward scanning.

Arguments

• forward_linear_speed_m_s - Forward linear speed in m/s
• backward_linear_speed_m_s - Backward linear speed in m/s
• forward_time_per_line_s - Forward time per line in seconds
• backward_time_per_line_s - Backward time per line in seconds
• keep_parameter_constant - Which parameter to keep constant: 0=no change, 1=linear speed, 2=time per line
• speed_ratio - Backward tip speed relative to forward speed

Errors

Returns NanonisError if communication fails or invalid parameters provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set 1 μm/s forward, 2 μm/s backward, keep linear speed constant
client.scan_speed_set(1e-6, 2e-6, 0.1, 0.05, 1, 2.0)?;

// Set based on time per line, equal forward/backward speed
client.scan_speed_set(1e-6, 1e-6, 0.1, 0.1, 2, 1.0)?;

pub fn scan_speed_get( &mut self, ) -> Result<(f32, f32, f32, f32, u16, f32), NanonisError>

Get the current scan speed parameters.

Returns all scan speed configuration values including linear speeds, time per line, and speed ratio settings.

Returns

A tuple containing:

• f32 - Forward linear speed (m/s)
• f32 - Backward linear speed (m/s)
• f32 - Forward time per line (s)
• f32 - Backward time per line (s)
• u16 - Keep parameter constant (0=linear speed, 1=time per line)
• f32 - Speed ratio (backward relative to forward)

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (fwd_speed, bwd_speed, fwd_time, bwd_time, keep_param, speed_ratio) =
    client.scan_speed_get()?;

println!("Forward speed: {:.2e} m/s", fwd_speed);
println!("Backward speed: {:.2e} m/s", bwd_speed);
println!("Speed ratio: {:.1}", speed_ratio);

pub fn scan_xy_pos_get( &mut self, wait_newest_data: bool, ) -> Result<(f32, f32), NanonisError>

Get the current XY position during scanning.

Returns the current values of the X and Y signals, useful for monitoring tip position during scanning operations.

Arguments

• wait_newest_data - If true, discards first value and waits for fresh data

Returns

A tuple containing (X position in m, Y position in m)

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Get current position immediately
let (x, y) = client.scan_xy_pos_get(false)?;
println!("Current position: ({:.6}, {:.6}) m", x, y);

// Wait for fresh position data
let (x, y) = client.scan_xy_pos_get(true)?;

pub fn scan_save( &mut self, wait_until_saved: bool, timeout_ms: i32, ) -> Result<bool, NanonisError>

Save the current scan data buffer to file.

Saves the current scan data into a file. If wait_until_saved is true, the function waits for the save operation to complete before returning.

Arguments

• wait_until_saved - If true, waits for save completion before returning
• timeout_ms - Timeout in milliseconds (-1 for indefinite wait)

Returns

true if timeout occurred while waiting for save completion, false otherwise

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Save immediately without waiting
let timed_out = client.scan_save(false, 5000)?;

// Save and wait up to 30 seconds for completion
let timed_out = client.scan_save(true, 30000)?;
if timed_out {
    println!("Save operation timed out");
}

pub fn scan_frame_data_grab( &mut self, channel_index: u32, data_direction: bool, ) -> Result<(String, Vec<Vec<f32>>, bool), NanonisError>

Get scan frame data for a specific channel and direction.

Returns the complete 2D scan data array for the selected channel. The channel must be one of the channels configured in the scan buffer.

Arguments

• channel_index - Index of channel to retrieve data from (must be in acquired channels)
• data_direction - Data direction: true for forward, false for backward

Returns

A tuple containing:

• String - Channel name
• Vec<Vec<f32>> - 2D scan data array [rows][columns]
• bool - Scan direction: true for up, false for down

Errors

Returns NanonisError if:

• Invalid channel index (not in acquired channels)
• Communication fails or protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Get forward scan data for channel 0
let (channel_name, data, scan_up) = client.scan_frame_data_grab(0, true)?;
println!("Channel: {}, Direction: {}", channel_name, if scan_up { "up" } else { "down" });
println!("Data size: {}x{}", data.len(), data[0].len());

// Get backward scan data
let (_, back_data, _) = client.scan_frame_data_grab(0, false)?;

pub fn scan_wait_end_of_scan( &mut self, timeout: Duration, ) -> Result<(bool, String), NanonisError>

Wait for the End-of-Scan.

Waits for the current scan to complete or timeout to occur, whichever comes first. This is useful for synchronizing operations with scan completion.

Arguments

• timeout - Timeout duration (-1 for indefinite wait)

Returns

A tuple containing:

• bool - true if timeout occurred, false if scan completed normally
• String - File path where data was auto-saved (empty if no auto-save)

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::{NanonisClient, ScanAction, ScanDirection};
use std::time::Duration;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Start a scan
client.scan_action(ScanAction::Start, ScanDirection::Up)?;

// Wait for scan to complete (up to 5 minutes)
let (timed_out, file_path) = client.scan_wait_end_of_scan(Duration::from_secs(300))?;

if timed_out {
    println!("Scan timed out after 5 minutes");
} else {
    println!("Scan completed");
    if !file_path.is_empty() {
        println!("Data saved to: {}", file_path);
    }
}

impl NanonisClient

pub fn signal_names_get( &mut self, print: bool, ) -> Result<Vec<String>, NanonisError>

Get available signal names

Examples found in repository

examples/get_signals.rs (line 7)

fn main() -> Result<(), Box<dyn Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    client.signal_names_get(true)?;

    let values = client.signals_vals_get((0..=127).collect::<Vec<i32>>(), true)?;

    let names = client.signal_names_get(false)?;

    for (index, (value, name)) in values.iter().zip(names).enumerate() {
        println!("{index:3}: {name:25} - {value:>15?}");
    }

    Ok(())
}

pub fn signals_calibr_get( &mut self, signal_index: SignalIndex, ) -> Result<(f32, f32), NanonisError>

Get calibration and offset of a signal by index

pub fn signals_range_get( &mut self, signal_index: SignalIndex, ) -> Result<(f32, f32), NanonisError>

Get range limits of a signal by index

pub fn signals_vals_get( &mut self, signal_indexes: Vec<i32>, wait_for_newest_data: bool, ) -> Result<Vec<f32>, NanonisError>

Get current values of signals by index(es)

Examples found in repository

examples/get_signals.rs (line 9)

fn main() -> Result<(), Box<dyn Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    client.signal_names_get(true)?;

    let values = client.signals_vals_get((0..=127).collect::<Vec<i32>>(), true)?;

    let names = client.signal_names_get(false)?;

    for (index, (value, name)) in values.iter().zip(names).enumerate() {
        println!("{index:3}: {name:25} - {value:>15?}");
    }

    Ok(())
}

pub fn find_signal_index( &mut self, signal_name: &str, ) -> Result<Option<SignalIndex>, NanonisError>

Find signal index by name (case-insensitive)

pub fn signal_val_get( &mut self, signal_index: impl Into<SignalIndex>, wait_for_newest_data: bool, ) -> Result<f32, NanonisError>

Get the current value of a single selected signal.

Returns the current value of the selected signal, oversampled during the Acquisition Period time (Tap). The signal is continuously oversampled and published every Tap seconds.

Signal Measurement Principle

This function waits for the next oversampled data to be published and returns its value. It does not trigger a measurement but waits for data to be published. The function returns a value 0 to Tap seconds after being called.

Important: If you change a signal and immediately call this function, you might get “old” data measured before the signal change. Set wait_for_newest_data to true to ensure you get only fresh data.

Arguments

• signal_index - Signal index (0-127)
• wait_for_newest_data - If true, discards first value and waits for fresh data. Takes Tap to 2*Tap seconds. If false, returns next available value (0 to Tap seconds).

Returns

The signal value in physical units.

Errors

Returns NanonisError if:

• Invalid signal index provided
• Communication timeout or protocol error

Examples

use rusty_tip::{NanonisClient, SignalIndex};

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Read bias signal immediately
let bias_value = client.signal_val_get(SignalIndex(24), false)?;

// Wait for fresh data after signal change
let fresh_value = client.signal_val_get(SignalIndex(24), true)?;

pub fn signals_meas_names_get(&mut self) -> Result<Vec<String>, NanonisError>

Get the list of measurement channels names available in the software.

Returns the names of measurement channels used in sweepers and other measurement modules.

Important Note: Measurement channels are different from Signals. Measurement channels are used in sweepers, while Signals are used by graphs and other modules. The indexes returned here are used for sweeper channel configuration (e.g., GenSwp.ChannelsGet/Set).

Returns

A vector of measurement channel names where each name corresponds to an index that can be used in sweeper functions.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let meas_channels = client.signals_meas_names_get()?;
println!("Available measurement channels: {}", meas_channels.len());

for (index, name) in meas_channels.iter().enumerate() {
    println!("  {}: {}", index, name);
}

pub fn signals_add_rt_get( &mut self, ) -> Result<(Vec<String>, String, String), NanonisError>

Get the list of additional Real-Time (RT) signals and current assignments.

Returns the list of additional RT signals available for assignment to Internal 23 and 24, plus the names of signals currently assigned to these internal channels.

Note: This assignment in the Signals Manager doesn’t automatically make them available in graphs and modules. Internal 23 and 24 must be assigned to one of the 24 display slots using functions like Signals.InSlotSet to be visible in the software.

Returns

A tuple containing:

• Vec<String> - List of additional RT signals that can be assigned to Internal 23/24
• String - Name of RT signal currently assigned to Internal 23
• String - Name of RT signal currently assigned to Internal 24

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (available_signals, internal_23, internal_24) = client.signals_add_rt_get()?;

println!("Available additional RT signals: {}", available_signals.len());
for (i, signal) in available_signals.iter().enumerate() {
    println!("  {}: {}", i, signal);
}

println!("Internal 23 assigned to: {}", internal_23);
println!("Internal 24 assigned to: {}", internal_24);

pub fn signals_add_rt_set( &mut self, additional_rt_signal_1: i32, additional_rt_signal_2: i32, ) -> Result<(), NanonisError>

Assign additional Real-Time (RT) signals to Internal 23 and 24 signals.

Links advanced RT signals to Internal 23 and Internal 24 in the Signals Manager. This enables routing of specialized real-time signals through the internal channel system.

Important Note: This assignment only links the RT signals to Internal 23/24. To make them visible in graphs and available for acquisition in modules, Internal 23 and 24 must be assigned to one of the 24 display slots using functions like Signals.InSlotSet.

Arguments

• additional_rt_signal_1 - Index of the RT signal to assign to Internal 23 (from signals_add_rt_get())
• additional_rt_signal_2 - Index of the RT signal to assign to Internal 24 (from signals_add_rt_get())

Errors

Returns NanonisError if:

• Invalid RT signal indices provided
• RT signals are not available or accessible
• Communication fails or protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// First, get the available RT signals
let (available_signals, current_23, current_24) = client.signals_add_rt_get()?;

println!("Available RT signals:");
for (i, signal) in available_signals.iter().enumerate() {
    println!("  {}: {}", i, signal);
}

// Assign RT signal index 0 to Internal 23 and index 1 to Internal 24
client.signals_add_rt_set(0, 1)?;

// Verify the assignment
let (_, new_23, new_24) = client.signals_add_rt_get()?;
println!("Internal 23 now assigned to: {}", new_23);
println!("Internal 24 now assigned to: {}", new_24);

pub fn read_signal_by_name( &mut self, signal_name: &str, wait_for_newest: bool, ) -> Result<f32, NanonisError>

Read a signal by name (finds index automatically)

impl NanonisClient

pub fn tcplog_start(&mut self) -> Result<(), NanonisError>

Start the acquisition in the TCP Logger module.

Before using this function, select the channels to record in the TCP Logger using tcplog_chs_set().

Returns

Ok(()) if the command succeeds.

Errors

Returns NanonisError if:

• Communication with the server fails
• Protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Configure channels first (using signal slots, not full indices)
client.tcplog_chs_set(vec![0, 1, 2])?; // First 3 signal slots

// Start logging
client.tcplog_start()?;

Examples found in repository

examples/tcp_logger_demo.rs (line 18)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    let mut stream = TCPLoggerStream::connect("127.0.0.1", 6590, 6504)?;

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_chs_set(vec![0, 8])?;

    sleep(Duration::from_millis(500));

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_start()?;

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    for i in 0..20 {
        let frame = stream.read_frame()?;
        println!(
            "Frame {}: {} : {:?}, counter: {}",
            i, frame.num_channels, frame.data, frame.counter
        )
    }

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    client.tcplog_stop()?;

    println!("{:?}", client.tcplog_status_get());

    Ok(())
}

pub fn tcplog_stop(&mut self) -> Result<(), NanonisError>

Stop the acquisition in the TCP Logger module.

Returns

Ok(()) if the command succeeds.

Errors

Returns NanonisError if:

• Communication with the server fails
• Protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Stop logging
client.tcplog_stop()?;

Examples found in repository

examples/tcp_logger_demo.rs (line 36)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    let mut stream = TCPLoggerStream::connect("127.0.0.1", 6590, 6504)?;

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_chs_set(vec![0, 8])?;

    sleep(Duration::from_millis(500));

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_start()?;

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    for i in 0..20 {
        let frame = stream.read_frame()?;
        println!(
            "Frame {}: {} : {:?}, counter: {}",
            i, frame.num_channels, frame.data, frame.counter
        )
    }

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    client.tcplog_stop()?;

    println!("{:?}", client.tcplog_status_get());

    Ok(())
}

pub fn tcplog_chs_set( &mut self, channel_indexes: Vec<i32>, ) -> Result<(), NanonisError>

Set the list of recorded channels in the TCP Logger module.

The channel indexes are comprised between 0 and 23 for the 24 signals assigned in the Signals Manager. To get the signal name and its corresponding index in the list of the 128 available signals in the Nanonis Controller, use the signal_names_get() function.

Arguments

• channel_indexes - Vector of channel indexes to record (0-23)

Returns

Ok(()) if the command succeeds.

Errors

Returns NanonisError if:

• Invalid channel indexes provided
• Communication with the server fails
• Protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Record first few signal slots (current, height, etc.)
client.tcplog_chs_set(vec![0, 1, 2])?;

// Record only the first slot (typically current)
client.tcplog_chs_set(vec![0])?;

Examples found in repository

examples/tcp_logger_demo.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    let mut stream = TCPLoggerStream::connect("127.0.0.1", 6590, 6504)?;

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_chs_set(vec![0, 8])?;

    sleep(Duration::from_millis(500));

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_start()?;

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    for i in 0..20 {
        let frame = stream.read_frame()?;
        println!(
            "Frame {}: {} : {:?}, counter: {}",
            i, frame.num_channels, frame.data, frame.counter
        )
    }

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    client.tcplog_stop()?;

    println!("{:?}", client.tcplog_status_get());

    Ok(())
}

pub fn tcplog_oversampl_set( &mut self, oversampling_value: i32, ) -> Result<(), NanonisError>

Set the oversampling value in the TCP Logger.

The oversampling value controls the data acquisition rate.

Arguments

• oversampling_value - Oversampling index (0-1000)

Returns

Ok(()) if the command succeeds.

Errors

Returns NanonisError if:

• Invalid oversampling value provided (outside 0-1000 range)
• Communication with the server fails
• Protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set moderate oversampling
client.tcplog_oversampl_set(100)?;

// Set maximum oversampling
client.tcplog_oversampl_set(1000)?;

pub fn tcplog_status_get(&mut self) -> Result<TCPLogStatus, NanonisError>

Return the current status of the TCP Logger.

Returns

The current TCPLogStatus of the TCP Logger module.

Errors

Returns NanonisError if:

• Communication with the server fails
• Protocol error occurs
• Invalid status value returned from server

Examples

use rusty_tip::{NanonisClient, TCPLogStatus};

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let status = client.tcplog_status_get()?;
match status {
    TCPLogStatus::Idle => println!("Logger is idle"),
    TCPLogStatus::Running => println!("Logger is running"),
    TCPLogStatus::BufferOverflow => println!("Warning: Buffer overflow detected!"),
    _ => println!("Logger status: {}", status),
}

Examples found in repository

examples/tcp_logger_demo.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    let mut stream = TCPLoggerStream::connect("127.0.0.1", 6590, 6504)?;

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_chs_set(vec![0, 8])?;

    sleep(Duration::from_millis(500));

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_start()?;

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    for i in 0..20 {
        let frame = stream.read_frame()?;
        println!(
            "Frame {}: {} : {:?}, counter: {}",
            i, frame.num_channels, frame.data, frame.counter
        )
    }

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    client.tcplog_stop()?;

    println!("{:?}", client.tcplog_status_get());

    Ok(())
}

impl NanonisClient

pub fn tip_rec_buffer_size_set( &mut self, buffer_size: i32, ) -> Result<(), NanonisError>

Set the buffer size of the Tip Move Recorder.

Sets the number of data elements that can be stored in the Tip Move Recorder buffer. This recorder tracks signal values while the tip is moving in Follow Me mode. Note: This function clears the existing graph data.

Arguments

• buffer_size - Number of data elements to store in the recorder buffer

Errors

Returns NanonisError if communication fails or invalid buffer size.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set buffer for 10,000 data points
client.tip_rec_buffer_size_set(10000)?;

// Set smaller buffer for quick tests
client.tip_rec_buffer_size_set(1000)?;

pub fn tip_rec_buffer_size_get(&mut self) -> Result<i32, NanonisError>

Get the current buffer size of the Tip Move Recorder.

Returns the number of data elements that can be stored in the recorder buffer.

Returns

Current buffer size (number of data elements).

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let buffer_size = client.tip_rec_buffer_size_get()?;
println!("Tip recorder buffer size: {} points", buffer_size);

pub fn tip_rec_buffer_clear(&mut self) -> Result<(), NanonisError>

Clear the buffer of the Tip Move Recorder.

Removes all recorded data from the Tip Move Recorder buffer, resetting it to an empty state. This is useful before starting a new recording session.

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Clear buffer before starting new measurement
client.tip_rec_buffer_clear()?;
println!("Tip recorder buffer cleared");

pub fn tip_rec_data_get( &mut self, ) -> Result<(Vec<i32>, Vec<Vec<f32>>), NanonisError>

Get the recorded data from the Tip Move Recorder.

Returns all data recorded while the tip was moving in Follow Me mode. This includes channel indexes, names, and the complete 2D data array with measurements taken during tip movement.

Returns

A tuple containing:

• Vec<i32> - Channel indexes (0-23 for Signals Manager slots)
• Vec<Vec<f32>> - 2D data array [rows][columns] with recorded measurements

Errors

Returns NanonisError if communication fails or no data available.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Get recorded tip movement data
let (channel_indexes, data) = client.tip_rec_data_get()?;

println!("Recorded {} channels with {} data points",
         channel_indexes.len(), data.len());

// Analyze data for each channel
for (i, &channel_idx) in channel_indexes.iter().enumerate() {
    if i < data[0].len() {
        println!("Channel {}: {} values", channel_idx, data.len());
    }
}

pub fn tip_rec_data_save( &mut self, clear_buffer: bool, basename: &str, ) -> Result<(), NanonisError>

Save the tip movement data to a file.

Saves all data recorded in Follow Me mode to a file with the specified basename. Optionally clears the buffer after saving to prepare for new recordings.

Arguments

• clear_buffer - If true, clears buffer after saving
• basename - Base filename for saved data (empty to use last basename)

Errors

Returns NanonisError if communication fails or file save error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Save data and clear buffer for next measurement
client.tip_rec_data_save(true, "tip_approach_001")?;

// Save without clearing buffer (keep data for analysis)
client.tip_rec_data_save(false, "tip_movement_log")?;

pub fn tip_shaper_start( &mut self, wait_until_finished: bool, timeout: Duration, ) -> Result<(), NanonisError>

Start the tip shaper procedure for tip conditioning.

Initiates the tip shaper procedure which performs controlled tip conditioning by applying specific voltage sequences and mechanical movements. This is used to improve tip sharpness and stability after crashes or contamination.

Arguments

• wait_until_finished - If true, waits for procedure completion
• timeout_ms - Timeout in milliseconds (-1 for infinite wait)

Errors

Returns NanonisError if communication fails or procedure cannot start.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Start tip shaping and wait for completion (30 second timeout)
client.tip_shaper_start(true, 30000)?;
println!("Tip shaping completed");

// Start tip shaping without waiting
client.tip_shaper_start(false, 0)?;

pub fn tip_shaper_props_set( &mut self, config: TipShaperConfig, ) -> Result<(), NanonisError>

Set the tip shaper procedure configuration.

Configures all parameters for the tip conditioning procedure including timing, voltages, and mechanical movements. This is a complex procedure with multiple stages of tip treatment.

Arguments

• config - Tip shaper configuration parameters

Errors

Returns NanonisError if communication fails or invalid parameters.

Examples

use rusty_tip::{NanonisClient, TipShaperConfig};
use std::time::Duration;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Conservative tip conditioning parameters
let config = TipShaperConfig {
    switch_off_delay: Duration::from_millis(100),
    change_bias: 1,      // true
    bias_v: -2.0,
    tip_lift_m: 50e-9,   // 50 nm
    lift_time_1: Duration::from_secs(1),
    bias_lift_v: 5.0,
    bias_settling_time: Duration::from_millis(500),
    lift_height_m: 100e-9, // 100 nm
    lift_time_2: Duration::from_millis(500),
    end_wait_time: Duration::from_millis(200),
    restore_feedback: 1, // true
};
client.tip_shaper_props_set(config)?;

pub fn tip_shaper_props_get(&mut self) -> Result<TipShaperProps, NanonisError>

Get the current tip shaper procedure configuration.

Returns all parameters currently configured for the tip conditioning procedure. Use this to verify settings before starting the procedure.

Returns

A tuple containing all tip shaper parameters:

• f32 - Switch off delay (s)
• u32 - Change bias flag (0=no change, 1=true, 2=false)
• f32 - Bias voltage (V)
• f32 - Tip lift distance (m)
• f32 - First lift time (s)
• f32 - Bias lift voltage (V)
• f32 - Bias settling time (s)
• f32 - Second lift height (m)
• f32 - Second lift time (s)
• f32 - End wait time (s)
• u32 - Restore feedback flag (0=no change, 1=true, 2=false)

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (switch_delay, change_bias, bias_v, tip_lift, lift_time1,
     bias_lift, settling, lift_height, lift_time2, end_wait, restore) =
     client.tip_shaper_props_get()?;

println!("Tip lift: {:.1} nm, Bias: {:.1} V", tip_lift * 1e9, bias_v);
println!("Total procedure time: ~{:.1} s",
         switch_delay + lift_time1 + settling + lift_time2 + end_wait);

pub fn tip_shaper_config_get(&mut self) -> Result<TipShaperConfig, NanonisError>

Get the Tip Shaper properties as a type-safe TipShaperConfig struct

This method returns the same information as tip_shaper_props_get() but with Duration types for time fields instead of raw f32 seconds.

Returns

Returns a TipShaperConfig struct with type-safe Duration fields for all time parameters.

Errors

Returns NanonisError if communication fails or if the response format is invalid.

Examples

use rusty_tip::NanonisClient;
use std::time::Duration;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;
let config = client.tip_shaper_config_get()?;

println!("Tip lift: {:.1} nm, Bias: {:.1} V",
         config.tip_lift_m * 1e9, config.bias_v);
println!("Total procedure time: {:.1} s",
         (config.switch_off_delay + config.lift_time_1 +
          config.bias_settling_time + config.lift_time_2 +
          config.end_wait_time).as_secs_f32());

impl NanonisClient

pub fn z_ctrl_on_off_set( &mut self, controller_on: bool, ) -> Result<(), NanonisError>

Switch the Z-Controller on or off.

Controls the Z-Controller state. This is fundamental for enabling/disabling tip-sample distance regulation during scanning and positioning operations.

Arguments

• controller_on - true to turn controller on, false to turn off

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Turn Z-controller on for feedback control
client.z_ctrl_on_off_set(true)?;

// Turn Z-controller off for manual positioning
client.z_ctrl_on_off_set(false)?;

pub fn z_ctrl_on_off_get(&mut self) -> Result<bool, NanonisError>

Get the current status of the Z-Controller.

Returns the real-time status from the controller (not from the Z-Controller module). This is useful to ensure the controller is truly off before starting experiments, as there can be communication delays and switch-off delays.

Returns

true if controller is on, false if controller is off.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Check controller status before experiment
if client.z_ctrl_on_off_get()? {
    println!("Z-controller is active");
} else {
    println!("Z-controller is off - safe to move tip manually");
}

pub fn z_ctrl_z_pos_set( &mut self, z_position_m: f32, ) -> Result<(), NanonisError>

Set the Z position of the tip.

Important: The Z-controller must be switched OFF to change the tip position. This function directly sets the tip’s Z coordinate for manual positioning.

Arguments

• z_position_m - Z position in meters

Errors

Returns NanonisError if:

• Z-controller is still active (must be turned off first)
• Position is outside safe limits
• Communication fails or protocol error occurs

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Ensure Z-controller is off
client.z_ctrl_on_off_set(false)?;

// Move tip to specific Z position (10 nm above surface)
client.z_ctrl_z_pos_set(10e-9)?;

// Move tip closer to surface (2 nm)
client.z_ctrl_z_pos_set(2e-9)?;

pub fn z_ctrl_z_pos_get(&mut self) -> Result<f32, NanonisError>

Get the current Z position of the tip.

Returns the current tip Z coordinate in meters. This works whether the Z-controller is on or off.

Returns

Current Z position in meters.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let z_pos = client.z_ctrl_z_pos_get()?;
println!("Current tip height: {:.2} nm", z_pos * 1e9);

// Check if tip is at safe distance
if z_pos > 5e-9 {
    println!("Tip is safely withdrawn");
}

pub fn z_ctrl_setpoint_set(&mut self, setpoint: f32) -> Result<(), NanonisError>

Set the setpoint of the Z-Controller.

The setpoint is the target value for the feedback signal that the Z-controller tries to maintain by adjusting the tip-sample distance.

Arguments

• setpoint - Z-controller setpoint value (units depend on feedback signal)

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set tunneling current setpoint to 100 pA
client.z_ctrl_setpoint_set(100e-12)?;

// Set force setpoint for AFM mode
client.z_ctrl_setpoint_set(1e-9)?;  // 1 nN

pub fn z_ctrl_setpoint_get(&mut self) -> Result<f32, NanonisError>

Get the current setpoint of the Z-Controller.

Returns the target value that the Z-controller is trying to maintain.

Returns

Current Z-controller setpoint value.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let setpoint = client.z_ctrl_setpoint_get()?;
println!("Current setpoint: {:.3e}", setpoint);

pub fn z_ctrl_gain_set( &mut self, p_gain: f32, time_constant_s: f32, i_gain: f32, ) -> Result<(), NanonisError>

Set the Z-Controller gains and time settings.

Configures the PID controller parameters for Z-axis feedback control. The integral gain is calculated as I = P/T where P is proportional gain and T is the time constant.

Arguments

• p_gain - Proportional gain of the regulation loop
• time_constant_s - Time constant T in seconds
• i_gain - Integral gain of the regulation loop (calculated as P/T)

Errors

Returns NanonisError if communication fails or invalid gains provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Set moderate feedback gains for stable operation
client.z_ctrl_gain_set(1.0, 0.1, 10.0)?;

// Set aggressive gains for fast response
client.z_ctrl_gain_set(5.0, 0.05, 100.0)?;

pub fn z_ctrl_gain_get(&mut self) -> Result<(f32, f32, f32), NanonisError>

Get the current Z-Controller gains and time settings.

Returns the PID controller parameters currently in use.

Returns

A tuple containing:

• f32 - Proportional gain
• f32 - Time constant in seconds
• f32 - Integral gain (P/T)

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (p_gain, time_const, i_gain) = client.z_ctrl_gain_get()?;
println!("P: {:.3}, T: {:.3}s, I: {:.3}", p_gain, time_const, i_gain);

// Check if gains are in reasonable range
if p_gain > 10.0 {
    println!("Warning: High proportional gain may cause instability");
}

pub fn z_ctrl_home(&mut self) -> Result<(), NanonisError>

Move the tip to its home position.

Moves the tip to the predefined home position, which can be either absolute (fixed position) or relative to the current position, depending on the controller configuration.

Errors

Returns NanonisError if communication fails or protocol error occurs.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Move tip to home position after experiment
client.z_ctrl_home()?;

// Wait a moment for positioning to complete
std::thread::sleep(std::time::Duration::from_secs(1));

// Check final position
let final_pos = client.z_ctrl_z_pos_get()?;
println!("Tip homed to: {:.2} nm", final_pos * 1e9);

pub fn z_ctrl_withdraw( &mut self, wait_until_finished: bool, timeout_ms: Duration, ) -> Result<(), NanonisError>

Withdraw the tip.

Switches off the Z-Controller and fully withdraws the tip to the upper limit. This is a safety function to prevent tip crashes during approach or when moving to new scan areas.

Arguments

• wait_until_finished - If true, waits for withdrawal to complete
• timeout_ms - Timeout in milliseconds for the withdrawal operation

Errors

Returns NanonisError if communication fails or withdrawal times out.

Examples

use rusty_tip::NanonisClient;
use std::time::Duration;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Emergency withdrawal - don't wait
client.z_ctrl_withdraw(false, Duration::from_secs(5))?;

// Controlled withdrawal with waiting
client.z_ctrl_withdraw(true, Duration::from_secs(10))?;
println!("Tip safely withdrawn");

impl NanonisClient

pub fn z_spectr_open(&mut self) -> Result<(), NanonisError>

Open the Z Spectroscopy module.

Opens and initializes the Z Spectroscopy module for distance-dependent measurements. This must be called before performing spectroscopy operations.

Errors

Returns NanonisError if communication fails or module cannot be opened.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Open Z spectroscopy module
client.z_spectr_open()?;
println!("Z Spectroscopy module opened");

pub fn z_spectr_start( &mut self, get_data: bool, save_base_name: &str, ) -> Result<ZSpectroscopyResult, NanonisError>

Start a Z spectroscopy measurement.

Initiates a Z spectroscopy measurement with the configured parameters. The tip is moved through a range of Z positions while recording selected channels.

Arguments

• get_data - If true, returns measurement data; if false, only starts measurement
• save_base_name - Base filename for saving data (empty for no change)

Returns

If get_data is true, returns a tuple containing:

• Vec<String> - Channel names
• Vec<Vec<f32>> - 2D measurement data [rows][columns]
• Vec<f32> - Fixed parameters and settings

Errors

Returns NanonisError if communication fails or measurement cannot start.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Start measurement and get data
let (channels, data, params) = client.z_spectr_start(true, "approach_001")?;
println!("Recorded {} channels with {} points", channels.len(), data.len());

// Just start measurement without getting data
let (_, _, _) = client.z_spectr_start(false, "")?;

pub fn z_spectr_stop(&mut self) -> Result<(), NanonisError>

Stop the current Z spectroscopy measurement.

Immediately stops any running Z spectroscopy measurement and returns the tip to its original position.

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Start a measurement
let (_, _, _) = client.z_spectr_start(false, "")?;

// Stop it after some condition
client.z_spectr_stop()?;
println!("Z spectroscopy stopped");

pub fn z_spectr_status_get(&mut self) -> Result<bool, NanonisError>

Get the status of Z spectroscopy measurement.

Returns whether a Z spectroscopy measurement is currently running.

Returns

true if measurement is running, false if stopped.

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

if client.z_spectr_status_get()? {
    println!("Z spectroscopy is running");
} else {
    println!("Z spectroscopy is stopped");
}

pub fn z_spectr_chs_set( &mut self, channel_indexes: Vec<i32>, ) -> Result<(), NanonisError>

Set the channels to record during Z spectroscopy.

Configures which signals will be recorded during the Z spectroscopy measurement. Channel indexes correspond to the 24 signals assigned in the Signals Manager (0-23).

Arguments

• channel_indexes - Vector of channel indexes to record (0-23)

Errors

Returns NanonisError if communication fails or invalid channel indexes provided.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Record current (0), Z position (1), and bias voltage (2)
client.z_spectr_chs_set(vec![0, 1, 2])?;

// Record more comprehensive dataset
client.z_spectr_chs_set(vec![0, 1, 2, 3, 4, 5])?;

pub fn z_spectr_chs_get( &mut self, ) -> Result<(Vec<i32>, Vec<String>), NanonisError>

Get the channels configured for Z spectroscopy recording.

Returns the channel indexes and names that will be recorded during measurements.

Returns

A tuple containing:

• Vec<i32> - Channel indexes (0-23 for Signals Manager slots)
• Vec<String> - Channel names corresponding to the indexes

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (indexes, names) = client.z_spectr_chs_get()?;
println!("Recording {} channels:", indexes.len());
for (idx, name) in indexes.iter().zip(names.iter()) {
    println!("  Channel {}: {}", idx, name);
}

pub fn z_spectr_range_set( &mut self, z_offset_m: f32, z_sweep_distance_m: f32, ) -> Result<(), NanonisError>

Set the Z range for spectroscopy measurements.

Configures the Z offset and sweep distance for the spectroscopy measurement. The tip will move from (offset - distance/2) to (offset + distance/2).

Arguments

• z_offset_m - Z offset position in meters (center of sweep)
• z_sweep_distance_m - Total sweep distance in meters

Errors

Returns NanonisError if communication fails or invalid range parameters.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Sweep ±5 nm around current position
client.z_spectr_range_set(0.0, 10e-9)?;

// Sweep from current position up to +20 nm
client.z_spectr_range_set(10e-9, 20e-9)?;

pub fn z_spectr_range_get(&mut self) -> Result<(f32, f32), NanonisError>

Get the current Z range configuration for spectroscopy.

Returns the configured Z offset and sweep distance.

Returns

A tuple containing:

• f32 - Z offset in meters (center position)
• f32 - Z sweep distance in meters (total range)

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (offset, distance) = client.z_spectr_range_get()?;
println!("Z sweep: {:.1} nm ± {:.1} nm", offset * 1e9, distance * 1e9 / 2.0);

pub fn z_spectr_timing_set( &mut self, z_averaging_time_s: f32, initial_settling_time_s: f32, maximum_slew_rate_vdivs: f32, settling_time_s: f32, integration_time_s: f32, end_settling_time_s: f32, ) -> Result<(), NanonisError>

Set the timing parameters for Z spectroscopy.

Configures timing-related parameters that control the speed and quality of the Z spectroscopy measurement.

Arguments

• z_averaging_time_s - Time to average signals at each Z position
• initial_settling_time_s - Initial settling time before measurement
• maximum_slew_rate_vdivs - Maximum slew rate in V/s
• settling_time_s - Settling time between measurement points
• integration_time_s - Integration time for each measurement point
• end_settling_time_s - Settling time at the end of sweep

Errors

Returns NanonisError if communication fails or invalid timing parameters.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Fast spectroscopy settings
client.z_spectr_timing_set(0.01, 0.1, 1000.0, 0.01, 0.01, 0.1)?;

// High-quality slow spectroscopy
client.z_spectr_timing_set(0.1, 0.5, 100.0, 0.05, 0.05, 0.2)?;

pub fn z_spectr_timing_get( &mut self, ) -> Result<(f32, f32, f32, f32, f32, f32), NanonisError>

Get the current timing parameters for Z spectroscopy.

Returns all timing-related configuration parameters.

Returns

A tuple containing:

• f32 - Z averaging time (s)
• f32 - Initial settling time (s)
• f32 - Maximum slew rate (V/s)
• f32 - Settling time (s)
• f32 - Integration time (s)
• f32 - End settling time (s)

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (z_avg, init_settle, slew_rate, settle, integrate, end_settle) =
    client.z_spectr_timing_get()?;
println!("Integration time: {:.3} s, settling: {:.3} s", integrate, settle);

pub fn z_spectr_retract_set( &mut self, enable: bool, threshold: f32, signal_index: i32, comparison: u16, ) -> Result<(), NanonisError>

Set the retraction parameters for tip protection during Z spectroscopy.

Configures automatic tip retraction based on signal thresholds to prevent tip crashes during approach spectroscopy.

Arguments

• enable - Enable/disable automatic retraction
• threshold - Signal threshold value for retraction trigger
• signal_index - Index of signal to monitor (0-23)
• comparison - Comparison type: 0=greater than, 1=less than

Errors

Returns NanonisError if communication fails or invalid parameters.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

// Enable retraction when current exceeds 1 nA (signal 0, greater than)
client.z_spectr_retract_set(true, 1e-9, 0, 0)?;

// Disable retraction
client.z_spectr_retract_set(false, 0.0, 0, 0)?;

pub fn z_spectr_retract_get( &mut self, ) -> Result<(bool, f32, i32, u16), NanonisError>

Get the current retraction configuration for Z spectroscopy.

Returns the tip protection settings that prevent crashes during measurements.

Returns

A tuple containing:

• bool - Retraction enabled/disabled
• f32 - Threshold value for retraction
• i32 - Signal index being monitored
• u16 - Comparison type (0=greater, 1=less than)

Errors

Returns NanonisError if communication fails.

Examples

use rusty_tip::NanonisClient;

let mut client = NanonisClient::new("127.0.0.1", 6501)?;

let (enabled, threshold, signal_idx, comparison) = client.z_spectr_retract_get()?;
if enabled {
    let comp_str = if comparison == 0 { ">" } else { "<" };
    println!("Retraction: signal[{}] {} {:.3e}", signal_idx, comp_str, threshold);
}

impl NanonisClient

pub fn new(addr: &str, port: u16) -> Result<Self, NanonisError>

Create a new client with default configuration.

This is the most convenient way to create a client for basic usage. Uses default timeouts and disables debug logging.

Arguments

• addr - Server address (e.g., “127.0.0.1”)
• port - Server port (e.g., 6501)

Returns

A connected NanonisClient ready for use.

Errors

Returns NanonisError if:

• The address format is invalid
• Connection to the server fails
• Connection times out

Examples

use rusty_tip::NanonisClient;

let client = NanonisClient::new("127.0.0.1", 6501)?;

Examples found in repository

examples/get_signals.rs (line 5)

fn main() -> Result<(), Box<dyn Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    client.signal_names_get(true)?;

    let values = client.signals_vals_get((0..=127).collect::<Vec<i32>>(), true)?;

    let names = client.signal_names_get(false)?;

    for (index, (value, name)) in values.iter().zip(names).enumerate() {
        println!("{index:3}: {name:25} - {value:>15?}");
    }

    Ok(())
}

examples/tcp_logger_demo.rs (line 6)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = NanonisClient::new("127.0.0.1", 6501)?;

    let mut stream = TCPLoggerStream::connect("127.0.0.1", 6590, 6504)?;

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_chs_set(vec![0, 8])?;

    sleep(Duration::from_millis(500));

    println!("{:?}", client.tcplog_status_get());

    client.tcplog_start()?;

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    for i in 0..20 {
        let frame = stream.read_frame()?;
        println!(
            "Frame {}: {} : {:?}, counter: {}",
            i, frame.num_channels, frame.data, frame.counter
        )
    }

    println!("{:?}", client.tcplog_status_get());

    sleep(Duration::from_millis(500));

    client.tcplog_stop()?;

    println!("{:?}", client.tcplog_status_get());

    Ok(())
}

pub fn builder() -> NanonisClientBuilder

Create a builder for flexible configuration.

Use this when you need to customize timeouts, enable debug logging, or other advanced configuration options.

Returns

A NanonisClientBuilder with default settings that can be customized.

Examples

use std::time::Duration;
use rusty_tip::NanonisClient;

let client = NanonisClient::builder()
    .address("192.168.1.100")
    .port(6501)
    .debug(true)
    .connect_timeout(Duration::from_secs(30))
    .build()?;

pub fn with_config( addr: &str, config: ConnectionConfig, ) -> Result<Self, NanonisError>

Create a new client with custom configuration (legacy method).

Deprecated: Use NanonisClient::builder() instead for more flexibility.

Arguments

• addr - Server address in format “host:port”
• config - Connection configuration with custom timeouts

pub fn set_debug(&mut self, debug: bool)

Enable or disable debug output

pub fn config(&self) -> &ConnectionConfig

Get the current connection configuration

pub fn quick_send( &mut self, command: &str, args: Vec<NanonisValue>, argument_types: Vec<&str>, return_types: Vec<&str>, ) -> Result<Vec<NanonisValue>, NanonisError>

Send a quick command with minimal response handling.

This is a low-level method for sending custom commands that don’t fit the standard method patterns. Most users should use the specific command methods instead.