# HID Gadget Emulation in Rust

[![github](https://img.shields.io/badge/github-katyo/hidg--rs-8da0cb.svg?style=for-the-badge&logo=github)](https://github.com/katyo/hidg-rs)
[![crate](https://img.shields.io/crates/v/tokio-hidg.svg?style=for-the-badge&color=fc8d62&logo=rust)](https://crates.io/crates/tokio-hidg)
[![docs](https://img.shields.io/badge/docs.rs-tokio--hidg-66c2a5?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K)](https://docs.rs/tokio-hidg)
[![MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![CI](https://img.shields.io/github/actions/workflow/status/katyo/hidg-rs/ci.yml?branch=master&style=for-the-badge&logo=github-actions&logoColor=white)](https://github.com/katyo/hidg-rs/actions?query=workflow%3ARust)

Rust crate for interfacing with Linux HID Gadget devices (/dev/hidgX).
This crate supports [tokio](https://tokio.rs/) async runtime.

Since all functionality is dependent on Linux function calls, this crate only compiles for Linux systems.

## Crates

- [hidg-core](https://crates.io/crates/hidg-core) - core abstractions and low level interface (not for end users)
- [hidg](https://crates.io/crates/hidg) - std interface which supports synchronous operation only
- **[tokio-hidg](https://crates.io/crates/tokio-hidg)** - async interface for [tokio](https://tokio.rs/) runtime
- [async-hidg](https://crates.io/crates/async-hidg) - async interface for other runtimes

## Features

- *fromstr* - implements [core::str::FromStr] implementation for some types
- *display* - implements [std::fmt::Display] implementation for some types
- *phf* - use [phf](https://crates.io/crates/phf) in [core::str::FromStr] trait implementations
- *serde* - enables [serde](https://crates.io/crates/serde) support for some types
- *keyboard* - enables keyboard class support
- *mouse* - enables mouse class support

## Usage examples

Keyboard input simulation:

```rust,no_run
use tokio_hidg::{Class, Device, Keyboard, Key, Led, StateChange};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut device = Device::<Keyboard>::open(0).await?; // open device

    // Create input report
    let mut input = Keyboard.input();

    // Press left ctrl modifier
    input.press_key(Key::LeftCtrl);

    // Press key 'A'
    input.press_key(Key::A);

    // Print pressed keys
    println!("Keys: {:?}", input.pressed().collect::<Vec<Key>>());

    // Send input report
    device.input(&input).await?;

    // Release left ctrl modifier
    input.release_key(Key::LeftCtrl);

    // Release key 'A'
    input.release_key(Key::A);

    // Send input report
    device.input(&input).await?;

    // Create output report
    let mut output = Keyboard.output();

    // Receive output report
    device.output(&mut output).await?;

    // Print lit LEDs
    println!("LEDs: {:?}", output.lit().collect::<Vec<Led>>());

    Ok(())
}
```

Mouse input simulation:

```rust,no_run
use tokio_hidg::{Button, Class, Device, Mouse, StateChange, ValueChange};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut device = Device::<Mouse>::open("hidg0").await?; // open device

    // Create input report
    let mut input = Mouse.input();

    // Press primary button
    input.press_button(Button::Primary);

    // Set pointer coordinates
    input.change_pointer((150, 50), false);

    // Send input report
    device.input(&input).await?;

    // Move pointer relatively
    input.change_pointer((70, -30), true);

    // Print pressed buttons
    println!("Buttons: {:?}", input.pressed().collect::<Vec<Button>>());

    // Release primary button
    input.release_button(Button::Primary);

    // Send input report
    device.input(&input).await?;

    Ok(())
}
```