# UsbKVM-Pro

**Repository Path**: darkathena/usbkvm-pro

## Basic Information

- **Project Name**: UsbKVM-Pro
- **Description**: 一个基于WebSerial技术的专业级KVM控制器，无需安装，没有花里胡哨的环境依赖，只需通过网页浏览器就可实时显示远程设备的屏幕并进行键盘和鼠标控制。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-24
- **Last Updated**: 2025-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UsbKVM Pro

**Professional WebKVM USB Controller**

一个基于WebSerial技术的专业级KVM控制器，无需安装，没有花里胡哨的环境依赖，只需通过网页浏览器就可实时显示远程设备的屏幕并进行键盘和鼠标控制。

![preview](pic/preview.png)

## 适用场景
1. 使用笔记本电脑维护无头无手设备（比如无显示器无键鼠的服务器）,支持bios级别操作
2. 在线上会议中，对无网络的设备进行桌面共享

## 外设硬件要求
1. HDMI转USB3.0 采集卡 MS2130 （注意2025年1月之后的win10/win11可能需要更新采集卡固件才能正常连接USB3.0接口）
2. CH9329+CH340UART/TTL 串口转USB HID
>[驱动下载地址 https://www.wch.cn/downloads/CH341SER_EXE.html](https://www.wch.cn/downloads/CH341SER_EXE.html)

## 连接参考图
```
┌──────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   主控端PC       │ USB │   MS2130采集卡  │HDMI│   被控端设备     │
│                  │◄──►│(HDMI虚拟成摄像头)│◄──►│                 │
│  显示被控端屏幕   │    └─────────────────┘    │   输出HDMI信号   │
│                  │    ┌─────────────────┐    │                 │
│键鼠操作转发到被控端│USB │ CH9329+CH340    │USB │  接收USB键鼠输入 │
│                  │◄──►│ (虚拟成USB键鼠)  │◄──►│                 │
└──────────────────┘    └─────────────────┘    └─────────────────┘
```

## ✨ 特性亮点

### 🎯 核心功能
- **WebSerial通信** - 基于现代Web标准的串口通信
- **视频捕获** - 支持HDMI采集卡和USB摄像头
- **完整KVM控制** - 键盘、鼠标、视频全方位控制
- **高性能优化** - 120fps鼠标响应，智能节流算法

### ⌨️ 键盘控制
- **完整USB HID映射** - 支持所有标准键盘按键
- **修饰键精确控制** - 左右Ctrl/Shift/Alt/Win键区分
- **组合键支持** - Ctrl+Alt+Del、Alt+F4等系统快捷键
- **状态管理** - 自动按键状态清理，防止卡键
- **长按重复** - 模拟真实键盘长按行为

### 🖱️ 鼠标控制
- **高精度移动** - 支持亚像素级精确定位
- **多按钮支持** - 左键、右键、中键完整支持
- **滚轮控制** - 平滑滚动体验
- **拖拽操作** - 完整的拖放功能支持
- **灵敏度调节** - 4档灵敏度可选（0.5x-1.5x）
- **性能优化** - 智能节流，最高120fps响应

### 📺 视频处理
- **多设备支持** - 自动识别外部采集设备
- **多种显示模式** - 原始大小、适应屏幕、拉伸填充
- **帧率控制** - 15/30/60fps可选
- **全屏支持** - F11快捷全屏，自动鼠标锁定

### 📝 高级功能
- **智能粘贴** - ASCII文本快速输入
- **CapsLock同步** - 大写锁定状态同步
- **快捷键面板** - 常用组合键一键发送
- **状态指示** - 实时连接和输入状态显示

## 🚀 快速开始

### 系统要求
- **浏览器**: Chrome/Edge 89+ (支持WebSerial API)
- **操作系统**: Windows 10+, macOS 10.15+, Linux
- **硬件**: 串口设备 + 视频采集设备

### 安装使用

1. **下载项目**
   ```bash
   git clone https://gitee.com/darkathena/usbkvm-pro.git
   cd usbkvm-pro
   ```

2. **用浏览器打开网页文件**
   `index.html` -- 推荐使用具有chrome核心的浏览器

3. **连接设备**
   - 点击"🔌 Connect"连接串口设备
   - 点击"📹 Capture Video"选择视频源
   - 点击"🖱️ Lock Mouse"开始控制

## 🎮 使用说明

### 基本操作

1. **连接串口设备**
   - 确保串口设备已连接，驱动已安装
   - 点击Connect按钮选择串口

2. **设置视频源**
   - 连接HDMI采集卡或USB摄像头 
   - 自动识别外部设备，或手动选择

3. **控制远程设备**
   - 点击视频区域获得焦点
   - 锁定鼠标开始精确控制
   - 所有键盘输入自动转发

### 快捷键列表

| 快捷键 | 功能 |
|--------|------|
| `F11` | 全屏 + 自动锁定鼠标 |
| `ESC` | 退出全屏 |
| `Ctrl+L` | 锁定/解锁鼠标 |
| `Ctrl+V` | 快捷粘贴对话框 |

### 高级设置

- **显示模式**: 原始大小/适应屏幕/拉伸填充
- **帧率设置**: 15/30/60fps视频捕获
- **鼠标灵敏度**: 0.5x-1.5x精度调节
- **快捷键**: 预设Ctrl+Alt+Del等系统组合键

## 🔧 技术架构

### 核心技术栈
- **WebSerial API** - 浏览器串口通信
- **MediaDevices API** - 视频设备访问
- **Pointer Lock API** - 鼠标精确控制
- **Fullscreen API** - 全屏体验

### 数据协议
```javascript
// 键盘数据包格式
[0x57, 0xab, 0x00, 0x02, 0x08, modifiers, 0x00, keyCode, 0x00, 0x00, 0x00, 0x00, 0x00, checksum]

// 鼠标数据包格式  
[0x57, 0xab, 0x00, 0x05, 0x05, 0x01, buttons, deltaX, deltaY, wheel, checksum]
```

### 性能优化
- **智能节流**: 避免过频发送，提升响应性
- **状态缓存**: 减少重复计算和数据传输
- **事件合并**: 批量处理鼠标移动事件
- **内存管理**: 自动清理定时器和事件监听

## 🛠️ 开发指南

### 项目结构
```
usbkvm-pro/
├── index.html          # 主应用文件
└── README.md               # 项目文档
```

### 自定义开发

1. **修改键盘映射**
   ```javascript
   const KEY_CODES = {
     // 添加自定义按键映射
     'CustomKey': 0xFF,
   };
   ```

2. **扩展鼠标功能**
   ```javascript
   function handleCustomMouseEvent(e) {
     // 自定义鼠标处理逻辑
   }
   ```

3. **添加新协议**
   ```javascript
   function createCustomPacket(cmd, ...data) {
     // 自定义数据包格式
   }
   ```

## 🐛 故障排除

### 常见问题

**Q: 无法连接串口设备**
- 检查浏览器是否支持WebSerial API
- 确认设备驱动已正确安装
- 尝试更换USB端口或重新拔插主控端USB

**Q: 视频无法显示**
- 检查采集设备是否被其他程序占用
- 确认浏览器摄像头权限已授予
- 尝试手动选择视频设备

**Q: 鼠标控制不准确**
- 调整鼠标灵敏度设置
- 确保已正确锁定鼠标
- 检查目标系统鼠标设置

**Q: 键盘输入异常**
- 点击"Reset Keys"清理状态
- 检查CapsLock等锁定键状态
- 确认目标系统键盘布局

**Q: 第一次Shift+字母不生效**
- 已完全修复修饰键状态同步问题
- 修正了USB HID协议实现：修饰键不再发送键码，只通过修饰符字段传递状态
- 新增"🧪 Test Shift"和"📝 Test Sequence"按钮可测试组合键是否正常
- 自动测试和手动测试现已保持一致的协议实现
- 打开浏览器控制台查看详细数据包信息
- 数据包格式：`0x57 0xab 0x00 0x02 0x08 [modifier] 0x00 [keycode] ...`
- 正确实现：组合键只发送目标键+修饰符，不发送修饰键本身的键码
- 如果仍有问题，可能是CH9329固件兼容性，请检查固件版本

### 调试模式
打开浏览器开发者工具查看详细日志：
```javascript
console.log('UsbKVM Pro Debug Info');
```

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

### 开发流程
1. Fork本项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送分支 (`git push origin feature/amazing-feature`)
5. 提交Pull Request

### 代码规范
- 使用ES6+语法
- 保持代码注释完整
- 遵循现有代码风格
- 添加适当的错误处理

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

- WebSerial API标准制定者
- 开源社区的支持和贡献
- 所有测试用户的反馈

---

**UsbKVM Pro** - 让KVM控制变得简单而强大 🚀

## 📞 联系方式

- 项目主页: [gitee Repository](https://gitee.com/darkathena/usbkvm-pro)
- 问题反馈: [Issues](https://gitee.com/darkathena/usbkvm-pro/issues)
- 功能建议: [Discussions](https://gitee.com/darkathena/usbkvm-pro/discussions)

## 免责声明
>**禁止用于涉密环境，如使用不当造成涉密信息泄露，本人不负任何责任。**

>别问我源码和文档里写的什么意思，因为都是AI生成的 --by DarkAthena