stickup 0.2.9

A modular input device abstraction layer with HID and virtual device support.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! src/devices/backends/hid.rs

use crate::device::Device;
use crate::event::InputKind;
use hidapi::{DeviceInfo, HidApi, HidDevice};

/// HID device implementation of the [`Device`] trait.
pub struct HidInputDevice {
    /// Structured device identity.
    #[allow(dead_code)]
    fingerprint: DeviceFingerprint,
    /// Cached ID string (vendor:product[:serial]).
    fingerprint_str: String,
    /// Human-readable name (from USB metadata).
    name: String,
    /// Raw HID device handle.
    raw: HidDevice,
}

impl HidInputDevice {
    /// Opens a HID device and constructs a `HidInputDevice`, if available.
    pub fn new(info: &DeviceInfo, api: &HidApi) -> Option<Self> {
        if let Ok(device) = info.open_device(api) {
            let fingerprint = DeviceFingerprint::from_info(info);
            let fingerprint_str = fingerprint.to_string();

            Some(Self {
                fingerprint,
                fingerprint_str,
                name: info.product_string().unwrap_or("Unknown").to_string(),
                raw: device,
            })
        } else {
            None
        }
    }
}

impl Device for HidInputDevice {
    /// Reads raw data from the device (currently debug only).
    fn poll(&mut self) -> Vec<InputKind> {
        let mut buf = [0u8; 64];
        let mut events = Vec::new();

        match self.raw.read_timeout(&mut buf, 1) {
            Ok(size) if size > 0 => {
                println!("{} reported {} bytes: {:?}", self.name, size, &buf[..size]);

                // TODO: Real parsing logic here. Example fake axis value:
                events.push(InputKind::AxisMoved {
                    axis: 0,
                    value: (buf[0] as f32 - 127.0) / 127.0,
                });
            }
            Ok(_) => {}
            Err(e) => {
                eprintln!("{} read error: {:?}", self.name, e);
            }
        }

        events
    }

    fn name(&self) -> &str {
        &self.name
    }

    fn id(&self) -> &str {
        &self.fingerprint_str
    }
}

/// Discovers available HID devices and wraps them as `Device`s.
pub fn probe_devices(api: &HidApi) -> Vec<Box<dyn Device>> {
    let mut found = Vec::new();
    for info in api.device_list() {
        if let Some(dev) = HidInputDevice::new(info, api) {
            found.push(Box::new(dev) as Box<dyn Device>);
        }
    }
    found
}

/// Unique identifier for a physical device.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct DeviceFingerprint {
    pub vendor_id: u16,
    pub product_id: u16,
    pub serial_number: Option<String>,
}

impl DeviceFingerprint {
    /// Builds a fingerprint from HID device metadata.
    pub fn from_info(info: &hidapi::DeviceInfo) -> Self {
        Self {
            vendor_id: info.vendor_id(),
            product_id: info.product_id(),
            serial_number: info.serial_number().map(|s| s.to_owned()),
        }
    }

    /// Formats the fingerprint as a persistent ID string.
    pub fn to_string(&self) -> String {
        match &self.serial_number {
            Some(serial) => format!("{:04x}:{:04x}:{}", self.vendor_id, self.product_id, serial),
            None => format!("{:04x}:{:04x}", self.vendor_id, self.product_id),
        }
    }
}