Struct HidApi

pub struct HidApi { /* private fields */ }

Object for handling hidapi context and implementing RAII for it. Only one instance can exist at a time.

Implementations

impl HidApi

pub fn new() -> HidResult<Self>

Initializes the hidapi.

Will also initialize the currently available device list.

Examples found in repository

examples/readhid.rs (line 18)

fn main() {
    let api = HidApi::new().expect("Failed to create API instance");

    let joystick = api.open(1103, 45320).expect("Failed to open device");

    loop {
        let mut buf = [0u8; 256];
        let res = joystick.read(&mut buf[..]).unwrap();

        let mut data_string = String::new();

        for u in &buf[..res] {
            data_string.push_str(&(u.to_string() + "\t"));
        }

        println!("{}", data_string);
    }
}

examples/static_lifetime_bound.rs (line 27)

fn test_lt() -> Rc<HidDevice> {
    let api = HidApi::new().expect("Hidapi init failed");

    let mut devices = api.device_list();

    let dev_info = devices
        .nth(0)
        .expect("There is not a single hid device available");

    let dev = Rc::new(
        api.open(dev_info.vendor_id(), dev_info.product_id())
            .expect("Can not open device"),
    );

    let dev_1 = dev.clone();
    requires_static_lt_bound(move || {
        println!("{}", dev_1.check_error().unwrap()); //<! Can be captured by closure with static lt
    });

    dev //<! Can be returned from a function, which exceeds the lifetime of the API context
}

examples/open_first_device.rs (line 19)

    fn run() -> Result<(), HidError> {
        let hidapi = HidApi::new()?;

        let device_info = hidapi
            .device_list()
            .next()
            .expect("No devices are available!")
            .clone();

        println!(
            "Opening device:\n VID: {:04x}, PID: {:04x}\n",
            device_info.vendor_id(),
            device_info.product_id()
        );

        let device = device_info.open_device(&hidapi)?;

        let mut buf = vec![0; 64];

        println!("Reading data from device ...\n");

        loop {
            let len = device.read(&mut buf)?;
            println!("{:?}", &buf[..len]);
        }
    }

examples/lshid.rs (line 19)

fn main() {
    println!("Printing all available hid devices:");

    match HidApi::new() {
        Ok(api) => {
            for device in api.device_list() {
                println!(
                    "VID: {:04x}, PID: {:04x}, Serial: {}, Product name: {}",
                    device.vendor_id(),
                    device.product_id(),
                    match device.serial_number() {
                        Some(s) => s,
                        _ => "<COULD NOT FETCH>",
                    },
                    match device.product_string() {
                        Some(s) => s,
                        _ => "<COULD NOT FETCH>",
                    }
                );
            }
        }
        Err(e) => {
            eprintln!("Error: {}", e);
        }
    }
}

examples/co2mon.rs (line 91)

fn main() {
    let api = HidApi::new().expect("HID API object creation failed");

    let dev = open_device(&api);

    dev.send_feature_report(&[0; PACKET_SIZE])
        .expect("Feature report failed");

    println!(
        "Manufacurer:\t{:?}",
        dev.get_manufacturer_string()
            .expect("Failed to read manufacurer string")
    );
    println!(
        "Product:\t{:?}",
        dev.get_product_string()
            .expect("Failed to read product string")
    );
    println!(
        "Serial number:\t{:?}",
        dev.get_serial_number_string()
            .expect("Failed to read serial number")
    );

    loop {
        let mut buf = [0; PACKET_SIZE];
        match dev.read_timeout(&mut buf[..], HID_TIMEOUT) {
            Ok(PACKET_SIZE) => (),
            Ok(res) => {
                println!("Error: unexpected length of data: {}/{}", res, PACKET_SIZE);
                continue;
            }
            Err(err) => {
                println!("Error: {:}", err);
                sleep(Duration::from_secs(RETRY_SEC));
                continue;
            }
        }
        match decode_buf(buf) {
            CO2Result::Temperature(val) => println!("Temp:\t{:?}", val),
            CO2Result::Concentration(val) => println!("Conc:\t{:?}", val),
            CO2Result::Unknown(..) => (),
            CO2Result::Error(val) => {
                println!("Error:\t{}", val);
                sleep(Duration::from_secs(RETRY_SEC));
            }
        }
    }
}

pub fn refresh_devices(&mut self) -> HidResult<()>

Refresh devices list and information about them (to access them use device_list() method)

pub fn devices(&self) -> &Vec<HidDeviceInfo>

👎Deprecated

Returns vec of objects containing information about connected devices

Deprecated. Use HidApi::device_list() instead.

pub fn device_list(&self) -> impl Iterator<Item = &DeviceInfo>

Returns iterator containing information about attached HID devices.

Examples found in repository

examples/static_lifetime_bound.rs (line 29)

fn test_lt() -> Rc<HidDevice> {
    let api = HidApi::new().expect("Hidapi init failed");

    let mut devices = api.device_list();

    let dev_info = devices
        .nth(0)
        .expect("There is not a single hid device available");

    let dev = Rc::new(
        api.open(dev_info.vendor_id(), dev_info.product_id())
            .expect("Can not open device"),
    );

    let dev_1 = dev.clone();
    requires_static_lt_bound(move || {
        println!("{}", dev_1.check_error().unwrap()); //<! Can be captured by closure with static lt
    });

    dev //<! Can be returned from a function, which exceeds the lifetime of the API context
}

examples/open_first_device.rs (line 22)

    fn run() -> Result<(), HidError> {
        let hidapi = HidApi::new()?;

        let device_info = hidapi
            .device_list()
            .next()
            .expect("No devices are available!")
            .clone();

        println!(
            "Opening device:\n VID: {:04x}, PID: {:04x}\n",
            device_info.vendor_id(),
            device_info.product_id()
        );

        let device = device_info.open_device(&hidapi)?;

        let mut buf = vec![0; 64];

        println!("Reading data from device ...\n");

        loop {
            let len = device.read(&mut buf)?;
            println!("{:?}", &buf[..len]);
        }
    }

examples/lshid.rs (line 21)

fn main() {
    println!("Printing all available hid devices:");

    match HidApi::new() {
        Ok(api) => {
            for device in api.device_list() {
                println!(
                    "VID: {:04x}, PID: {:04x}, Serial: {}, Product name: {}",
                    device.vendor_id(),
                    device.product_id(),
                    match device.serial_number() {
                        Some(s) => s,
                        _ => "<COULD NOT FETCH>",
                    },
                    match device.product_string() {
                        Some(s) => s,
                        _ => "<COULD NOT FETCH>",
                    }
                );
            }
        }
        Err(e) => {
            eprintln!("Error: {}", e);
        }
    }
}

pub fn open(&self, vid: u16, pid: u16) -> HidResult<HidDevice>

Open a HID device using a Vendor ID (VID) and Product ID (PID).

When multiple devices with the same vid and pid are available, then the first one found in the internal device list will be used. There are however no guarantees, which device this will be.

Examples found in repository

examples/co2mon.rs (line 80)

fn open_device(api: &HidApi) -> HidDevice {
    loop {
        match api.open(DEV_VID, DEV_PID) {
            Ok(dev) => return dev,
            Err(err) => {
                println!("{}", err);
                sleep(Duration::from_secs(RETRY_SEC));
            }
        }
    }
}

examples/readhid.rs (line 20)

fn main() {
    let api = HidApi::new().expect("Failed to create API instance");

    let joystick = api.open(1103, 45320).expect("Failed to open device");

    loop {
        let mut buf = [0u8; 256];
        let res = joystick.read(&mut buf[..]).unwrap();

        let mut data_string = String::new();

        for u in &buf[..res] {
            data_string.push_str(&(u.to_string() + "\t"));
        }

        println!("{}", data_string);
    }
}

examples/static_lifetime_bound.rs (line 36)

fn test_lt() -> Rc<HidDevice> {
    let api = HidApi::new().expect("Hidapi init failed");

    let mut devices = api.device_list();

    let dev_info = devices
        .nth(0)
        .expect("There is not a single hid device available");

    let dev = Rc::new(
        api.open(dev_info.vendor_id(), dev_info.product_id())
            .expect("Can not open device"),
    );

    let dev_1 = dev.clone();
    requires_static_lt_bound(move || {
        println!("{}", dev_1.check_error().unwrap()); //<! Can be captured by closure with static lt
    });

    dev //<! Can be returned from a function, which exceeds the lifetime of the API context
}

pub fn open_serial(&self, vid: u16, pid: u16, sn: &str) -> HidResult<HidDevice>

Open a HID device using a Vendor ID (VID), Product ID (PID) and a serial number.

pub fn open_path(&self, device_path: &CStr) -> HidResult<HidDevice>

The path name be determined by inspecting the device list available with HidApi::devices()

Alternatively a platform-specific path name can be used (eg: /dev/hidraw0 on Linux).

pub fn wrap_sys_device( &self, sys_dev: i32, interface_num: i32, ) -> HidResult<HidDevice>

Open a HID device using libusb_wrap_sys_device. Useful for Android.

Arguments

• sys_dev: Platform-specific file descriptor that can be recognised by libusb.
• interface_num: USB interface number of the device to be used as HID interface. Pass -1 to select first HID interface of the device.

pub fn check_error(&self) -> HidResult<HidError>

Get the last non-device specific error, which happened in the underlying hidapi C library. To get the last device specific error, use HidDevice::check_error.

The Ok() variant of the result will contain a HidError::HidApiError.

When Err() is returned, then acquiring the error string from the hidapi C library failed. The contained HidError is the cause, why no error could be fetched.