From 02c30176792a020b0271ba8f47b3cc045b608060 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dav=C3=AD=C3=B0=20Steinn=20Geirsson?= <david@dsg.is>
Date: Sun, 22 Mar 2026 11:33:07 +0000
Subject: [PATCH] Update README.md

---
 README.md | 99 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 66 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index f7db312..a218b55 100644
--- a/README.md
+++ b/README.md
@@ -1,60 +1,93 @@
-# usbip
+# usbip-rs
 
-[![Coverage Status](https://coveralls.io/repos/github/jiegec/usbip/badge.svg?branch=master)](https://coveralls.io/github/jiegec/usbip?branch=master)
-[![crates.io](https://img.shields.io/crates/v/usbip.svg)](https://crates.io/crates/usbip)
+A USB/IP tool and library for Linux. Share physical USB devices over vsock or TCP, or export simulated devices for testing.
 
-A Rust library to run a USB/IP server to simulate USB devices and share real USB devices over a network.
+## Overview
 
-## What is USB/IP?
+usbip-rs provides:
 
-USB/IP is a network protocol that allows USB devices to be shared between computers over a network. It enables:
+- **CLI tool** (`usbip-rs`) — pass through real USB devices from a host to a client over vsock or TCP, using Linux's vhci_hcd kernel module
+- **Rust library** (`usbip-rs` crate) — implement custom USB/IP device handlers, with built-in HID keyboard and CDC ACM serial examples
 
-- **Device simulation**: Create virtual USB devices that can be accessed remotely
-- **Device sharing**: Share physical USB devices from one machine to another
-- **Cross-platform**: Works across different operating systems (Linux, etc.)
+Supported transfer types: control, bulk and interrupt. Isochronous support is being worked on.
 
-## Installation
+## Building
 
-### Prerequisites
-
-Install Rust from the [official documentation](https://www.rust-lang.org/tools/install).
-
-### Building from source
+### With Nix
+
+```bash
+nix build
+```
+
+### With Cargo
+
+Requires `libusb` and `libudev` (Linux) system dependencies.
 
 ```bash
-git clone https://github.com/jiegec/usbip.git
-cd usbip
 cargo build --release
 ```
 
-## How to use
+The CLI binary is at `target/release/usbip-rs`.
 
-### Examples
+## Usage
 
-The `examples/` directory contains three example programs:
+The CLI has three top-level commands: `client`, `host`, and `test_hid`. Transport addresses use the format `vsock:<port>`, `vsock:<cid>:<port>`, `tcp:<port>`, or `tcp:<host>:<port>`.
 
-1. **hid_keyboard**: Simulate a HID keyboard that types something every second
-2. **cdc_acm_serial**: Simulate a CDC ACM serial device that receives a character every second
-3. **host**: Act as a USB/IP server, sharing physical devices from the host machine to remote clients
+### Pass through a real USB device
 
-#### Running an example
+On the client machine (needs `vhci_hcd` kernel module):
 
 ```bash
-cargo run --example hid_keyboard
+usbip-rs client listen tcp:3240
 ```
 
-#### Connecting from a USB/IP client
-
-On the client machine (e.g. Linux with USB/IP support):
+On the host machine (where the USB device is plugged in):
 
 ```bash
-# List available devices
-usbip list -r $remote_ip
+usbip-rs host connect tcp:<client-ip>:3240 1-2
+```
 
-# Attach to a device
-usbip attach -r $remote_ip -b $bus_id
+The device argument is a bus ID (e.g. `1-2`) or device path (e.g. `/dev/bus/usb/001/002`).
+
+### Test with a simulated HID keyboard
+
+```bash
+# Client side
+usbip-rs client listen vsock:5000
+
+# Host side (simulated keyboard, no real device needed)
+usbip-rs test_hid connect vsock:5000
+```
+
+### Library examples
+
+The `lib/examples/` directory contains standalone USB/IP servers using the library directly:
+
+- **hid_keyboard** — simulated HID keyboard
+- **cdc_acm_serial** — simulated CDC ACM serial device
+- **host** — physical device passthrough (legacy, single-device)
+
+```bash
+cargo run -p usbip-rs --example hid_keyboard
+```
+
+These listen on the standard USB/IP port and work with the Linux `usbip` userspace tools:
+
+```bash
+usbip list -r <host-ip>
+usbip attach -r <host-ip> -b <bus-id>
+```
+
+## Project structure
+
+```
+├── cli/          CLI binary (usbip-rs)
+├── lib/          Library crate (usbip-rs)
+│   ├── src/
+│   └── examples/
+└── flake.nix     Nix build
 ```
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT — see [LICENSE](LICENSE).