nanonis-rs

A Rust client library for communicating with Nanonis SPM (Scanning Probe Microscopy) systems via the Nanonis TCP protocol. This library provides a type-safe, high-level interface for controlling scanning probe microscopes and reading measurement data.

Features

Type-safe API: Strongly-typed Rust interface to Nanonis commands
Comprehensive coverage: Support for motors, scanning, spectroscopy, oscilloscopes, and more
Error handling: Robust error types with detailed context
TCPLogger streaming: Continuous data acquisition support
Safety features: Automatic tip withdrawal and motor positioning on client drop
Protocol abstraction: Low-level protocol details handled internally

Supported Functionality

Bias control: Set and read bias voltage
Signal acquisition: Read signal values and metadata
Motor control: Precise control of XYZ motors and FolMe positioning
Z-controller: Z-feedback loop control and monitoring
Scanning: Scan control and data acquisition
Auto-approach: Automated tip approach functionality
Oscilloscopes: Single-trigger, dual-trigger, and high-resolution modes
Spectroscopy: Z-spectroscopy and bias sweeps
Tip management: Tip shaping and recovery procedures
PLL control: Phase-locked loop operations
TCPLogger: Real-time data streaming

Quick Start

Add this to your Cargo.toml:

[dependencies]
nanonis-rs = "0.0.3"

Basic Example

use nanonis_rs::{NanonisClient, NanonisError};
use std::time::Duration;

fn main() -> Result<(), NanonisError> {
    // Connect to Nanonis system
    let mut client = NanonisClient::builder()
        .address("192.168.1.100:6501")
        .timeout(Duration::from_secs(5))
        .build()?;

    // Get current bias voltage
    let bias = client.bias_get()?;
    println!("Current bias: {} V", bias);

    // Set new bias voltage
    client.bias_set(0.5)?;

    // Read signal values
    let signals = client.signals_vals_get()?;
    println!("Signals: {:?}", signals);

    Ok(())
}

Motor Control Example

use nanonis_rs::{NanonisClient, MotorDirection, MotorGroup};
use std::time::Duration;

fn main() -> Result<(), NanonisError> {
    let mut client = NanonisClient::connect("192.168.1.100:6501")?;

    // Move motor with specified steps
    client.motor_start_move(
        MotorDirection::ZPlus,
        1000,  // steps
        MotorGroup::Group1,
        false  // non-blocking
    )?;

    // Wait for movement to complete
    std::thread::sleep(Duration::from_millis(500));

    Ok(())
}

TCPLogger Streaming Example

use nanonis_rs::TCPLoggerStream;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut stream = TCPLoggerStream::connect("192.168.1.100:6502")?;

    // Read streaming data
    loop {
        let data = stream.read_data()?;
        println!("Timestamp: {}, Channels: {}",
                 data.timestamp, data.channels.len());

        // Process data...
    }
}

Architecture

The library is organized into several layers:

Protocol layer (protocol.rs): Low-level TCP message encoding/decoding
Type system (types.rs): Protocol value types and domain-specific types
Client layer (client/): High-level API organized by functionality
Error handling (error.rs): Comprehensive error types with context

All communication with Nanonis follows a request-response pattern with strongly-typed inputs and outputs.

Connection Configuration

Create clients using the builder pattern for advanced configuration:

use nanonis_rs::NanonisClient;
use std::time::Duration;

let client = NanonisClient::builder()
    .address("192.168.1.100:6501")
    .timeout(Duration::from_secs(10))
    .max_response_size(100_000_000)  // 100 MB
    .build()?;

Or use the simpler connect method:

let client = NanonisClient::connect("192.168.1.100:6501")?;

Safety Features

The client implements automatic safety features:

Auto-withdrawal: Z-controller withdraws tip when client is dropped
Motor positioning: Motors automatically move to safe position on drop
Timeout protection: All operations have configurable timeouts

Error Handling

The library uses typed errors via NanonisError:

match client.bias_get() {
    Ok(bias) => println!("Bias: {} V", bias),
    Err(NanonisError::Timeout(msg)) => eprintln!("Timeout: {}", msg),
    Err(NanonisError::Server { code, message }) => {
        eprintln!("Server error {}: {}", code, message)
    }
    Err(e) => eprintln!("Error: {}", e),
}

Documentation

Full API documentation is available on docs.rs. The documentation includes detailed examples for each command.

Requirements

Rust 2021 edition or later
Nanonis system with TCP interface enabled
Network access to Nanonis controller

Development

This project uses Nix flakes for reproducible development environments:

# Enter development shell
nix develop

# Build the library
cargo build

# Run tests (requires Nanonis connection)
cargo test

# Build documentation
cargo doc --open

License

Licensed under the MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues on GitHub.

Acknowledgments

This library implements the Nanonis TCP protocol as documented by SPECS Zurich GmbH. Nanonis is a registered trademark of SPECS Zurich GmbH.

nanonis-rs 0.0.3