129 lines
4.0 KiB
Markdown
129 lines
4.0 KiB
Markdown
# CLAUDE.md — KVMote (Go/Wails)
|
|
|
|
Reescrita em Go do KVMote (original em C#/WinForms em `C:\vscode\KVMote`).
|
|
|
|
---
|
|
|
|
## O que é
|
|
|
|
KVM over Bluetooth/BLE. Controla PC remoto (cliente) a partir do host usando microcontrolador como HID USB. **Sem software no PC cliente.**
|
|
|
|
```
|
|
Host PC ──BLE NUS──► ESP32-S3 ──USB HID──► Cliente PC (sem sw)
|
|
```
|
|
|
|
Hardware suportado: ESP32-S3 (BLE NUS) e Arduino Leonardo + HC-06 (Serial SPP). Ver CLAUDE.md do projeto C# para detalhes de hardware e firmware.
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
- **Go 1.23** + **Wails v2** (webview desktop)
|
|
- **tinygo.org/x/bluetooth** — BLE via WinRT
|
|
- **golang.org/x/sys/windows** — hooks globais (WH_MOUSE_LL, WH_KEYBOARD_LL)
|
|
- **github.com/atotto/clipboard** — leitura de clipboard
|
|
- Frontend: HTML estático em `frontend/dist/` (sem framework JS)
|
|
|
|
---
|
|
|
|
## Estrutura
|
|
|
|
```
|
|
main.go — entry point Wails, bind App
|
|
app.go — App struct, métodos expostos ao frontend
|
|
internal/
|
|
transport/
|
|
transport.go — interface Transport (Detect/Connect/Send/SendLossy...)
|
|
ble_windows.go — BLE NUS via tinygo/bluetooth
|
|
kvm/
|
|
engine.go — lógica KVM: mouse, teclado, clipboard, modo cliente
|
|
input/
|
|
input.go — interface InputHandler + tipos (Point, MouseEvent, KeyboardEvent)
|
|
input_windows.go — hooks Win32, SetCursorPos, ShowCursor, GetSystemMetrics
|
|
frontend/
|
|
dist/index.html — UI
|
|
wails.json — config Wails
|
|
```
|
|
|
|
---
|
|
|
|
## Protocolo binário (Host → Dispositivo)
|
|
|
|
Idêntico ao projeto C#:
|
|
|
|
| Cmd | Bytes | Ação |
|
|
|-----|-------|------|
|
|
| `M` dx dy | 3 | Mouse move (int8) |
|
|
| `W` delta | 2 | Scroll (int8) |
|
|
| `K` char | 2 | Keyboard.write |
|
|
| `P` key | 2 | Keyboard.press |
|
|
| `U` key | 2 | Keyboard.release |
|
|
| `A` | 1 | releaseAll |
|
|
| `C` L\|R | 2 | Click |
|
|
| `D` L\|R | 2 | Mouse press |
|
|
| `E` L\|R | 2 | Mouse release |
|
|
| `T` lenH lenL data | 3+N | Clipboard batch (Go-specific) |
|
|
| `O` | 1 | LED magenta (modo cliente) |
|
|
| `H` | 1 | LED azul (host conectado) |
|
|
| `G` | 1 | LED verde (desconectado) |
|
|
| `~` | 1 | Ping → `[PONG]` |
|
|
|
|
---
|
|
|
|
## Lógica KVM (engine.go)
|
|
|
|
- **Entrada modo cliente:** cursor atinge borda configurada → esconde cursor, warp centro, acumula deltas (técnica FPS)
|
|
- **Retorno ao host:** coordenadas virtuais cruzam `-ReturnThreshold` (120px) na direção de entrada
|
|
- **Debounce:** 800ms anti-bounce após troca de modo
|
|
- **Mouse throttle:** 40ms (~25 pacotes/s)
|
|
- **Scroll:** `scrollActive` suprime warp por 200ms durante scroll (evita cancelar gesto touchpad)
|
|
- **Clipboard:** Ctrl+C no host seta `clipboardReady`, Ctrl+V em modo cliente envia via comando `T` (batch)
|
|
- **Ctrl+Alt+Del:** sequência P/U com delay 50ms
|
|
|
|
---
|
|
|
|
## Hooks Win32 (input_windows.go)
|
|
|
|
- `runtime.LockOSThread()` obrigatório — hooks Win32 exigem message pump na mesma thread
|
|
- Loop `GetMessageW` mantém thread viva
|
|
- `Uninstall()` via `PostThreadMessageW(WM_QUIT)`
|
|
- `SetProcessDPIAware` chamado no init()
|
|
|
|
---
|
|
|
|
## Build
|
|
|
|
```bash
|
|
# Dev
|
|
wails dev
|
|
|
|
# Produção
|
|
wails build
|
|
```
|
|
|
|
Saída: `build/bin/kvmote.exe`
|
|
|
|
---
|
|
|
|
## Diferenças do projeto C#
|
|
|
|
| Aspecto | C# (WinForms) | Go (Wails) |
|
|
|---------|---------------|------------|
|
|
| UI | WinForms nativo | Webview (HTML) |
|
|
| Transporte | Serial + BLE (dual) | Só BLE (por enquanto) |
|
|
| Clipboard | char-a-char com delay | Batch via comando `T` |
|
|
| ClipboardMax | 500/1000 chars | 65536 chars |
|
|
| Scroll | acumulador _wheelAccum + _scrollActive | scrollActive only |
|
|
| ReturnThreshold | 15px | 120px |
|
|
| Reconexão | auto-reconnect loop | manual |
|
|
| Heartbeat/Watchdog | sim | não implementado |
|
|
|
|
---
|
|
|
|
## ⚠️ Cuidados
|
|
|
|
- **Scroll touchpad:** `scrollActive` e `scrollTimer` não devem ser resetados em enter/exitClientMode
|
|
- **runtime.LockOSThread:** nunca remover da goroutine de hooks
|
|
- **isWarping flag:** previne loop infinito SetCursorPos → WM_MOUSEMOVE → SetCursorPos
|
|
- **Mutex ordering:** engine.mu protege todo estado KVM; transport.mu protege conexão BLE
|