Struct Client 

pub struct Client { /* private fields */ }

The main entry point for interacting with the ViGEm bus driver.

A Client manages the connection to the driver and keeps track of all virtual controllers created by it. When the Client is dropped, it will automatically unplug all of its connected virtual controllers.

Use Client::builder() or Client::connect() to create a new client.

Implementations

impl Client

pub fn builder() -> ClientBuilder

Create a builder to configure and connect a new client.

This allows setting options like the maximum number of targets.

Example

use vigem_rust::client::Client;
let client = Client::builder()
    .max_targets(32) // Allow up to 32 controllers
    .connect()
    .unwrap();

pub fn connect() -> Result<Self, ClientError>

Creates a new client with default options and connects to the ViGEm bus.

This is a convenient shortcut for Client::builder().connect().

Example

use vigem_rust::Client;

let client = Client::connect().unwrap();

Examples found in repository

examples/x360.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let x360 = client.new_x360_target().plugin()?;
    println!("Plugged in virtual Xbox 360 controller");

    // Wait for the controller to be ready
    // The virtual controller needs a moment to be recognized
    // by the system before it can receive updates.
    x360.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = x360.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!("  - LED Number/Player Index: {}", notification.led_number);
        }
    });

    // Here, we'll send reports to the controller to simulate input.
    let mut report = X360Report::default();
    let mut angle: f64 = 0.0;
    let mut step = 0;

    loop {
        // Animate the left thumbstick in a circle
        angle += 0.1;
        let (sin, cos) = angle.sin_cos();
        report.thumb_lx = (sin * 32767.0) as i16;
        report.thumb_ly = (cos * 32767.0) as i16;

        // Alternate pressing A and B buttons
        if step % 2 == 0 {
            report.buttons = X360Button::A;
        } else {
            report.buttons = X360Button::B;
        }

        // Send the updated report to the controller
        x360.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        step += 1;
    }
}

examples/ds4.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Here, we'll send reports to the controller to simulate input.

    let mut report = Ds4Report::default();

    // Hold the right D-pad button
    report.set_dpad(Ds4Dpad::East);
    // Hold the Cross button
    report.buttons |= Ds4Button::CROSS.bits();
    // Fully press the right trigger
    report.trigger_r = 255;

    let mut angle: f64 = 0.0;

    loop {
        // Animate the right thumbstick in a circle
        let (sin, cos) = angle.sin_cos();

        // DS4 thumbsticks are 0-255, with 128 as the center.
        report.thumb_rx = (128.0 + sin * 127.0) as u8;
        report.thumb_ry = (128.0 + cos * 127.0) as u8;

        // Send the updated report to the controller
        ds4.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        angle += 0.05;
    }
}

examples/ds4_ex.rs (line 9)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Main input loop for extended reports
    let mut report_ex = Ds4ReportEx::default();

    // Variables to animate the touch point
    let mut packet_counter: u8 = 0;
    let mut touch_x: i32 = 0;
    let mut direction: i32 = 12;

    loop {
        // Move the touch point back and forth horizontally.
        if touch_x <= 0 {
            direction = 12;
        }
        if touch_x >= 1919 {
            direction = -12;
        }
        touch_x += direction;

        report_ex.touch_packets_n = 1;

        // Get a mut reference to the touch data struct inside the report.
        let touch = &mut report_ex.current_touch;

        // This counter should increment for each new packet of touch data (not sure if necessary for functionality).
        touch.packet_counter = packet_counter;
        packet_counter = packet_counter.wrapping_add(1);

        touch.set_touch_1(true, 1, touch_x as u16, 471); // Finger 1 is down, centered vertically.
        touch.set_touch_2(false, 0, 0, 0); // Finger 2 is up (inactive).

        // Send the updated report to the controller
        ds4.update_ex(&report_ex)?;

        thread::sleep(Duration::from_millis(16));
    }
}

pub fn new_x360_target(&self) -> TargetBuilder<'_, Xbox360>

Creates a builder for a new virtual Xbox 360 controller.

The returned builder can be used to set properties like vendor and product IDs before plugging the controller into the bus.

Example

let x360 = client.new_x360_target()
    .with_vid(0xAAAA)
    .with_pid(0xBBBB)
    .plugin()
    .unwrap();

Examples found in repository

examples/x360.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let x360 = client.new_x360_target().plugin()?;
    println!("Plugged in virtual Xbox 360 controller");

    // Wait for the controller to be ready
    // The virtual controller needs a moment to be recognized
    // by the system before it can receive updates.
    x360.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = x360.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!("  - LED Number/Player Index: {}", notification.led_number);
        }
    });

    // Here, we'll send reports to the controller to simulate input.
    let mut report = X360Report::default();
    let mut angle: f64 = 0.0;
    let mut step = 0;

    loop {
        // Animate the left thumbstick in a circle
        angle += 0.1;
        let (sin, cos) = angle.sin_cos();
        report.thumb_lx = (sin * 32767.0) as i16;
        report.thumb_ly = (cos * 32767.0) as i16;

        // Alternate pressing A and B buttons
        if step % 2 == 0 {
            report.buttons = X360Button::A;
        } else {
            report.buttons = X360Button::B;
        }

        // Send the updated report to the controller
        x360.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        step += 1;
    }
}

pub fn new_ds4_target(&self) -> TargetBuilder<'_, DualShock4>

Creates a builder for a new virtual DualShock 4 controller.

The returned builder can be used to set properties like vendor and product IDs before plugging the controller into the bus.

Example

let ds4 = client.new_ds4_target()
    .with_vid(0xAAAA)
    .with_pid(0xBBBB)
    .plugin()
    .unwrap();

Examples found in repository

examples/ds4.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Here, we'll send reports to the controller to simulate input.

    let mut report = Ds4Report::default();

    // Hold the right D-pad button
    report.set_dpad(Ds4Dpad::East);
    // Hold the Cross button
    report.buttons |= Ds4Button::CROSS.bits();
    // Fully press the right trigger
    report.trigger_r = 255;

    let mut angle: f64 = 0.0;

    loop {
        // Animate the right thumbstick in a circle
        let (sin, cos) = angle.sin_cos();

        // DS4 thumbsticks are 0-255, with 128 as the center.
        report.thumb_rx = (128.0 + sin * 127.0) as u8;
        report.thumb_ry = (128.0 + cos * 127.0) as u8;

        // Send the updated report to the controller
        ds4.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        angle += 0.05;
    }
}

examples/ds4_ex.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Main input loop for extended reports
    let mut report_ex = Ds4ReportEx::default();

    // Variables to animate the touch point
    let mut packet_counter: u8 = 0;
    let mut touch_x: i32 = 0;
    let mut direction: i32 = 12;

    loop {
        // Move the touch point back and forth horizontally.
        if touch_x <= 0 {
            direction = 12;
        }
        if touch_x >= 1919 {
            direction = -12;
        }
        touch_x += direction;

        report_ex.touch_packets_n = 1;

        // Get a mut reference to the touch data struct inside the report.
        let touch = &mut report_ex.current_touch;

        // This counter should increment for each new packet of touch data (not sure if necessary for functionality).
        touch.packet_counter = packet_counter;
        packet_counter = packet_counter.wrapping_add(1);

        touch.set_touch_1(true, 1, touch_x as u16, 471); // Finger 1 is down, centered vertically.
        touch.set_touch_2(false, 0, 0, 0); // Finger 2 is up (inactive).

        // Send the updated report to the controller
        ds4.update_ex(&report_ex)?;

        thread::sleep(Duration::from_millis(16));
    }
}