Crate android_usb_serial 

Pure Rust USB serial drivers for Android (and Linux), built on nusb.

Protocol logic is ported from usb-serial-for-android and checked against golden USB control-transfer fixtures under tests/fixtures/.

Overview

This crate does not talk to Android UsbManager. The host app (typically Kotlin) owns USB permission, opens a UsbDeviceConnection, and passes its raw file descriptor into Rust. The crate then:

1. from_raw_fd — dups the fd so Java can keep the connection alive.
2. NusbTransport — claims interfaces via nusb (detach_and_claim).
3. ProbeTable / open_port — selects a vendor driver and returns a SerialPortHandle.

UsbManager (Kotlin) → permission → UsbDeviceConnection → fd (unclaimed)
        ↓
   from_raw_fd / NusbTransport
        ↓
   ProbeTable → Ftdi / Cp21xx / Ch34x / … drivers
        ↓
   SerialPortHandle (write / reader / modem / purge)

Android usage

• Declare android.hardware.usb.host and a device_filter.xml in the app.
• Request runtime USB permission before UsbManager.openDevice().
• Do not call UsbDeviceConnection.claimInterface() in Kotlin — nusb claims after from_raw_fd. Pre-claim causes io interface is busy.
• Keep the UsbDeviceConnection open for the whole session; close it only after Rust SerialPortHandle::close.
• Prefer SerialPortHandle::start_reader after line config and DTR/RTS (important for weak OTG / CH340).
• Multi-port chips: pass port_index to open_port (0, 1, …). App-level enumerate often exposes paths as deviceName / deviceName#N.

Full Kotlin/permission walkthrough: crate README (Using on Android) in the repository.

Quick start (real USB fd)

// fd from UsbDeviceConnection.fileDescriptor (dup'd inside from_raw_fd)
use android_usb_serial::{from_raw_fd, open_port, NusbTransport, Transport};
use std::sync::Arc;

let device = from_raw_fd(fd)?;
let transport = Arc::new(NusbTransport::from_device(device)?) as Arc<dyn Transport>;
let mut port = open_port(transport, 0)?;
port.write(b"AT\r\n")?;

Quick start (fake-transport)

use android_usb_serial::{open_port, FakeTransport, Transport};
use std::sync::Arc;

let fake = FakeTransport::cdc_single_iface();
let transport: Arc<dyn Transport> = Arc::new(fake.clone());
let mut port = open_port(transport, 0).unwrap();
port.write(b"PING").unwrap();
assert_eq!(fake.take_tx(), b"PING");

Features

Feature	Default	Description
serialport-compat	yes	serialport::SerialPort adapter (serialport_compat)
fake-transport	no	FakeTransport + golden_record binary

Platform notes

• Android / Linux: real USB via nusb (from_raw_fd, NusbTransport).
• Other hosts: drivers + fake for tests; supply your own Transport for hardware.

Re-exports

pub use device::describe_device;

pub use device::open_port;

pub use device::DeviceDescriptor;

pub use device::PortDescriptor;

pub use drivers::ModemStatus;

pub use error::ReadOutcome;

pub use error::Result;

pub use error::TransferError;

pub use error::UsbSerialError;

pub use port::SerialPortHandle;

pub use probe::DriverType;

pub use probe::ProbeTable;

pub use transport::BulkIn;

pub use transport::BulkOut;

pub use transport::ControlRequest;

pub use transport::EndpointInfo;

pub use transport::InterfaceInfo;

pub use transport::SharedTransport;

pub use transport::Transport;

pub use fake::FakeTransport;fake-transport

pub use nusb_transport::from_raw_fd;Android or Linux

pub use nusb_transport::NusbTransport;Android or Linux

pub use config::*;

Modules

config

Line / flow / purge configuration types. Line configuration types (no plugin dependency).

device

Device probe and port open helpers. Device discovery and port enumeration.

drivers

Chip-specific USB serial drivers. USB serial driver implementations.

error

Error types. USB serial driver errors.

fakefake-transport

In-memory Transport for golden parity and harnesses. In-memory transport for golden parity and on-device harness.

nusb_transportAndroid or Linux

nusb-backed transport (from_raw_fd / Android UsbDeviceConnection). nusb-backed transport (Linux / Android).

port

High-level serial port handle. High-level serial port handle over a proprietary USB serial driver.

probe

VID/PID probe table (ported from usb-serial-for-android). Driver probing (ported from ProbeTable.java / UsbId.java).

reader

Continuous bulk-IN reader thread. Background bulk-IN reader (2–4 in-flight transfers + RX filter chain).

rx_filter

RX filter chain (FTDI header strip, XON/XOFF). RX filter chain (FTDI header strip, XON/XOFF inline).

serialport_compatserialport-compat

Adapter implementing serialport::SerialPort. serialport crate compatibility layer — full serialport::SerialPort on Android USB.

transport

USB transport trait and request types. USB transport abstraction (nusb or fake).

xonxoff

XON/XOFF inline filter. Software XON/XOFF filter for RX paths.