Struct Z21Station 

pub struct Z21Station { /* private fields */ }

Represents an asynchronous connection to a Z21 station.

The Z21Station manages a UDP socket for communication with a Z21 station. It spawns a background task to continuously listen for incoming packets and proceed these packets over an internal logic.

Implementations

impl Z21Station

pub async fn new(bind_addr: &str) -> Result<Self>

Creates a new connection to a Z21 station at the specified address.

This method establishes a UDP connection to the Z21 station, performs the initial handshake, and starts background tasks for maintaining the connection.

Arguments

• bind_addr - Network address of the Z21 station (typically “192.168.0.111:21105”)

Returns

A new Z21Station instance if the connection is successful.

Errors

Returns an io::Error if:

• The UDP socket cannot be bound or connected
• The initial handshake with the Z21 station fails
• The station does not respond within the timeout period

Example

let station = Z21Station::new("192.168.0.111:21105").await?;

Examples found in repository

examples/loco_control.rs (line 7)

async fn main() -> std::io::Result<()> {
    let station = Arc::new(Z21Station::new("192.168.0.111:21105").await?);

    // Control a locomotive with address 3
    let loco = Loco::control(station.clone(), 4).await?;

    // Subscribe to locomotive state changes
    loco.subscribe_loco_state(Box::new(|state| {
        println!(
            "Locomotive speed: {}%",
            state.speed_percentage.unwrap_or(0.)
        );
    }));

    // Turn on the headlights
    loco.set_headlights(true).await?;

    // Set speed to 50% forward
    loco.drive(50.0).await?;

    // Wait for 5 seconds
    tokio::time::sleep(tokio::time::Duration::from_secs(5)).await;

    // Gradually stop
    loco.stop().await?;

    Ok(())
}

examples/station_listener.rs (line 6)

async fn main() -> std::io::Result<()> {
    // Create a connection to the Z21 station
    let station = Arc::new(Z21Station::new("192.168.0.111:21105").await?);

    // Get the serial number of the station
    let serial = station.get_serial_number().await?;
    println!("Z21 station serial number: {}", serial);

    // Turn on track power
    station.voltage_on().await?;

    // Subscribe to system state updates
    station.subscribe_system_state(
        1.0,
        Box::new(|state| {
            println!("Main track voltage: {:.2}V", state.vcc_voltage);
            println!("Temperature: {}°C", state.temperature);
            println!("Current: {}mA", state.main_current);
        }),
    );

    // Keep the application running
    tokio::signal::ctrl_c().await?;

    // Turn off track power before exiting
    station.voltage_off().await?;
    station.logout().await?;

    Ok(())

    //Ok(())
}

pub async fn voltage_off(&self) -> Result<()>

Turns off the track voltage.

This is equivalent to pressing the STOP button on the Z21 station or the MultiMaus controller. It cuts power to all tracks, stopping all locomotives immediately.

Returns

Ok(()) if the command was successfully sent and acknowledged.

Errors

Returns an io::Error if the command fails to send or no acknowledgment is received.

Example

// Emergency stop all locomotives by cutting track power
station.voltage_off().await?;

Examples found in repository

examples/station_listener.rs (line 29)

async fn main() -> std::io::Result<()> {
    // Create a connection to the Z21 station
    let station = Arc::new(Z21Station::new("192.168.0.111:21105").await?);

    // Get the serial number of the station
    let serial = station.get_serial_number().await?;
    println!("Z21 station serial number: {}", serial);

    // Turn on track power
    station.voltage_on().await?;

    // Subscribe to system state updates
    station.subscribe_system_state(
        1.0,
        Box::new(|state| {
            println!("Main track voltage: {:.2}V", state.vcc_voltage);
            println!("Temperature: {}°C", state.temperature);
            println!("Current: {}mA", state.main_current);
        }),
    );

    // Keep the application running
    tokio::signal::ctrl_c().await?;

    // Turn off track power before exiting
    station.voltage_off().await?;
    station.logout().await?;

    Ok(())

    //Ok(())
}

pub async fn voltage_on(&self) -> Result<()>

Turns on the track voltage.

This restores power to the tracks after an emergency stop or when the system is first started. It also disables programming mode if it was active.

Returns

Ok(()) if the command was successfully sent and acknowledged.

Errors

Returns an io::Error if the command fails to send or no acknowledgment is received.

Example

// Restore power to the tracks
station.voltage_on().await?;

Examples found in repository

examples/station_listener.rs (line 13)

async fn main() -> std::io::Result<()> {
    // Create a connection to the Z21 station
    let station = Arc::new(Z21Station::new("192.168.0.111:21105").await?);

    // Get the serial number of the station
    let serial = station.get_serial_number().await?;
    println!("Z21 station serial number: {}", serial);

    // Turn on track power
    station.voltage_on().await?;

    // Subscribe to system state updates
    station.subscribe_system_state(
        1.0,
        Box::new(|state| {
            println!("Main track voltage: {:.2}V", state.vcc_voltage);
            println!("Temperature: {}°C", state.temperature);
            println!("Current: {}mA", state.main_current);
        }),
    );

    // Keep the application running
    tokio::signal::ctrl_c().await?;

    // Turn off track power before exiting
    station.voltage_off().await?;
    station.logout().await?;

    Ok(())

    //Ok(())
}

pub async fn get_serial_number(&self) -> Result<u32>

Retrieves the serial number from the Z21 station.

Returns

The Z21 station’s serial number as a 32-bit unsigned integer.

Errors

Returns an io::Error if:

• Sending the request fails
• The response times out
• The response data is invalid (e.g., too short)

Example

let serial = station.get_serial_number().await?;
println!("Z21 station serial number: {}", serial);

Examples found in repository

examples/station_listener.rs (line 9)

async fn main() -> std::io::Result<()> {
    // Create a connection to the Z21 station
    let station = Arc::new(Z21Station::new("192.168.0.111:21105").await?);

    // Get the serial number of the station
    let serial = station.get_serial_number().await?;
    println!("Z21 station serial number: {}", serial);

    // Turn on track power
    station.voltage_on().await?;

    // Subscribe to system state updates
    station.subscribe_system_state(
        1.0,
        Box::new(|state| {
            println!("Main track voltage: {:.2}V", state.vcc_voltage);
            println!("Temperature: {}°C", state.temperature);
            println!("Current: {}mA", state.main_current);
        }),
    );

    // Keep the application running
    tokio::signal::ctrl_c().await?;

    // Turn off track power before exiting
    station.voltage_off().await?;
    station.logout().await?;

    Ok(())

    //Ok(())
}

pub fn subscribe_system_state( &self, freq_in_sec: f64, subscriber: Box<dyn Fn(SystemState) + Send + Sync>, )

Subscribes to system state updates from the Z21 station.

This method sets up a polling mechanism to regularly request system state updates and calls the provided callback function whenever new state information is received.

Arguments

• freq_in_sec - Polling frequency in Hz (updates per second)
• subscriber - Callback function that receives SystemState updates

Example

station.subscribe_system_state(1.0, Box::new(|state| {
    println!("Main track voltage: {:.2}V", state.main_track_voltage);
    println!("Temperature: {}°C", state.temperature);
    println!("Current: {}mA", state.current);
}));

Examples found in repository

examples/station_listener.rs (lines 16-23)

async fn main() -> std::io::Result<()> {
    // Create a connection to the Z21 station
    let station = Arc::new(Z21Station::new("192.168.0.111:21105").await?);

    // Get the serial number of the station
    let serial = station.get_serial_number().await?;
    println!("Z21 station serial number: {}", serial);

    // Turn on track power
    station.voltage_on().await?;

    // Subscribe to system state updates
    station.subscribe_system_state(
        1.0,
        Box::new(|state| {
            println!("Main track voltage: {:.2}V", state.vcc_voltage);
            println!("Temperature: {}°C", state.temperature);
            println!("Current: {}mA", state.main_current);
        }),
    );

    // Keep the application running
    tokio::signal::ctrl_c().await?;

    // Turn off track power before exiting
    station.voltage_off().await?;
    station.logout().await?;

    Ok(())

    //Ok(())
}

pub async fn logout(&self) -> Result<()>

Logs out from the Z21 station.

This method should be called at the end of a session to gracefully terminate the connection with the Z21 station.

Returns

Ok(()) if the logout command was successfully sent.

Errors

Returns an io::Error if the logout command fails to send.

Example

// Clean up and disconnect from the Z21 station
station.logout().await?;

Examples found in repository

examples/station_listener.rs (line 30)

async fn main() -> std::io::Result<()> {
    // Create a connection to the Z21 station
    let station = Arc::new(Z21Station::new("192.168.0.111:21105").await?);

    // Get the serial number of the station
    let serial = station.get_serial_number().await?;
    println!("Z21 station serial number: {}", serial);

    // Turn on track power
    station.voltage_on().await?;

    // Subscribe to system state updates
    station.subscribe_system_state(
        1.0,
        Box::new(|state| {
            println!("Main track voltage: {:.2}V", state.vcc_voltage);
            println!("Temperature: {}°C", state.temperature);
            println!("Current: {}mA", state.main_current);
        }),
    );

    // Keep the application running
    tokio::signal::ctrl_c().await?;

    // Turn off track power before exiting
    station.voltage_off().await?;
    station.logout().await?;

    Ok(())

    //Ok(())
}

Trait Implementations

impl Drop for Z21Station

fn drop(&mut self)

Executes the destructor for this type.