# usb display protocol

**Repository Path**: fangml/usb-display-protocol

## Basic Information

- **Project Name**: usb display protocol
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# USB Display Driver（这是AI做的文档）

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](https://github.com/yourname/TaitanScreenUSB)

An open-source, reverse-engineered driver for the low-cost USB HID secondary display (**VID `0x1A2C` / PID `0x151D`**).

This project breaks the vendor software lock and lets you directly control the 480×480 color screen from your PC. It streams JPEG images over USB HID interrupt endpoints — no proprietary software required.

---

## Features

- **Zero re-compression for JPEGs**: If your image is already a 480×480 JPEG, it is sent to the device as-is. No quality loss, no CPU waste.
- **Automatic conversion for other formats**: PNG, BMP, GIF, and non-standard JPEGs are automatically resized and re-encoded with hardware-safe parameters.
- **Built-in performance monitoring**: Real-time FPS, frame latency, CPU, and memory stats.
- **Heartbeat handling**: Non-blocking device status monitoring via a background thread.
- **Cross-platform**: Works on Windows, Linux, and macOS (with appropriate permissions).

---

## Hardware Requirements

| Item | Spec |
|------|------|
| Device | USB secondary display with VID `0x1A2C` / PID `0x151D` |
| Resolution | **480 × 480** (strictly enforced) |
| Interface | USB 2.0 Full-Speed, HID Vendor Defined |
| OS | Windows 10/11, Linux, macOS |

> **Note**: The device has **no frame buffer, no scaling, and no retransmission**. The host must send complete, correctly-sized JPEG frames in real time.

---

## Quick Start

### 1. Install Dependencies

```bash
pip install -r requirements.txt
```

On **Windows**, you may also need the [libusb driver](https://github.com/libusb/libusb/wiki/Windows) or use the built-in `HidUsb.sys`. Most systems work out of the box.

On **Linux**, add a udev rule:

```bash
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1a2c", ATTR{idProduct}=="151d", MODE="0666"' | sudo tee /etc/udev/rules.d/99-taitan-display.rules
sudo udevadm control --reload-rules
```

### 2. Run the Driver

```bash
python hid_display_driver.py
```

1. Select an image from the list.
2. Choose **passthrough** (`N`) if the image is already a 480×480 JPEG.
3. The driver will handshake with the device and start streaming.
4. Press `Ctrl+C` to stop.

### 3. Prepare Test Images

Place your `480×480` images in the project root or in `assets/test_images/`.

Example test images are included in `assets/test_images/`.

---

## Project Structure

```
.
├── hid_display_driver.py      # Main driver script
├── requirements.txt           # Python dependencies
├── LICENSE                    # MIT License
├── README.md                  # This file
├── assets/
│   └── test_images/           # Sample 480×480 test images
├── docs/
│   └── protocol.md            # Reverse-engineered protocol spec
└── tools/
    ├── JPEGAnalyser.py        # JPEG parameter analyzer from captures
    └── WireSharkPackAnalyser.py  # Extract JPEG frames from pcapng
```

---

## Protocol Summary

The device speaks a simple vendor-defined HID protocol:

1. **Handshake** (`EP 0x01` → `EP 0x82`): Send a 467-byte wakeup command. Device replies with status `0x01`.
2. **Image Stream** (`EP 0x03`): Send the JPEG file in 1024-byte HID reports (4-byte header + 1020-byte payload).
3. **Heartbeat** (`EP 0x84`): Device sends intermittent 43-byte status packets. Host reads them but does not need to respond.

> **Critical detail**: Each HID report must be exactly **1024 bytes**. The Wireshark `frame.len = 1051` includes USB protocol overhead — the actual HID payload is 1024 bytes.

For the full specification, see [`docs/protocol.md`](docs/protocol.md).

---

## Performance

Measured on Windows 11 + Python 3.11 with a 6.3 KB static JPEG:

| Metric | Value |
|--------|-------|
| Handshake time | < 50 ms |
| Frame transmit time | 120 ~ 150 ms |
| Stable FPS | 3 ~ 5 FPS (static images) |
| CPU usage | < 2% (passthrough mode) |
| Memory usage | < 30 MB |

The bottleneck is USB 2.0 Full-Speed bandwidth, not CPU. For best stability, keep individual JPEG frames under **15 KB**.

---

## Roadmap

- [ ] Qt/PySide6 GUI with drag-and-drop widget layout
- [ ] System monitor plugin (CPU, RAM, GPU temperature)
- [ ] Weather / clock widgets
- [ ] Screen mirroring (live desktop region capture)
- [ ] Multi-device support
- [ ] Standalone Windows `.exe` build

---

## Contributing

Pull requests are welcome. If you have capture files from a similar device or improvements to the protocol documentation, feel free to open an issue or PR.

## License

This project is released under the [MIT License](LICENSE).

The protocol was derived entirely from black-box traffic analysis. No proprietary vendor code was used.