From b3feb1fe920463279006e3a78d40fba9d2de3729 Mon Sep 17 00:00:00 2001 From: Ricardo Carneiro <71648276+ricarneiro@users.noreply.github.com> Date: Sun, 22 Mar 2026 15:18:33 -0300 Subject: [PATCH] Add detailed README with architecture, setup and protocol docs Co-Authored-By: Claude Sonnet 4.6 --- README.md | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 177 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f28270..839c458 100644 --- a/README.md +++ b/README.md @@ -1 +1,177 @@ - \ No newline at end of file +# KVMote + +> **KVM over Bluetooth** — controle teclado e mouse de um PC remoto usando um Arduino Leonardo como ponte HID, sem instalar nada no PC cliente. + +--- + +## O que é + +KVMote é um software KVM (*Keyboard, Video, Mouse*) que funciona de forma semelhante ao [Barrier](https://github.com/debauchee/barrier) e [InputLeap](https://github.com/input-leap/input-leap), mas com uma diferença fundamental: **o PC cliente não precisa de nenhum software instalado**. + +A comunicação acontece via **Bluetooth Serial (HC-06)** até um **Arduino Leonardo**, que se apresenta ao PC cliente como um teclado e mouse USB padrão (HID). Para o Windows do cliente, é como se um teclado e mouse físicos tivessem sido conectados. + +``` +┌─────────────────┐ Bluetooth SPP ┌────────────┐ USB HID ┌──────────────┐ +│ PC Host │ ──────────────────────► │ HC-06 │ ─────────────► │ PC Cliente │ +│ KVMote.exe │ (virtual COM) │ Arduino │ (teclado + │ (sem sw) │ +│ teclado+mouse │ │ Leonardo │ mouse USB) │ │ +└─────────────────┘ └────────────┘ └──────────────┘ +``` + +--- + +## Por que usar + +- ✅ **Zero instalação no PC cliente** — o Arduino é reconhecido como HID nativo +- ✅ **Funciona em ambientes corporativos** — sem software, sem porta de rede, sem VPN +- ✅ **Sem driver especial** — Windows, Linux e macOS reconhecem HID automaticamente +- ✅ **Clipboard de texto** — Ctrl+C no host, Ctrl+V envia o texto digitado ao cliente +- ✅ **Suporte a layouts** — US Internacional e PT-BR ABNT2 + +--- + +## Hardware necessário + +| Componente | Detalhes | +|---|---| +| Arduino Leonardo | ATmega32U4 com suporte a USB HID nativo | +| Módulo HC-06 | Bluetooth SPP escravo, configurado para 9600 baud | +| LED RGB (ânodo comum ou cátodo comum) | Opcional, mas recomendado para feedback visual | +| PC Host | Windows 10/11, com Bluetooth | +| PC Cliente | Qualquer sistema operacional | + +### Conexão do HC-06 ao Arduino Leonardo + +``` +HC-06 TX → Arduino RX1 (pino 0) +HC-06 RX → Arduino TX1 (pino 1) [use divisor de tensão: 5V→3.3V] +HC-06 VCC → Arduino 5V +HC-06 GND → Arduino GND +``` + +### LED RGB (pinos PWM) + +``` +R → pino 5 +G → pino 6 +B → pino 9 +``` + +**Significado das cores:** +| Cor | Estado | +|---|---| +| Azul | Conectado, aguardando (modo host) | +| Laranja | Modo cliente ativo (mouse no PC remoto) | +| Flash verde | Ação executada / voltou ao host | +| Flash ciano | PONG recebido (heartbeat OK) | + +--- + +## Software necessário (PC Host) + +- Windows 10/11 (x64) +- .NET 8 Desktop Runtime — ou use o executável self-contained +- Arduino IDE com as bibliotecas `Keyboard` e `Mouse` (inclusas no suporte ao Leonardo) + +--- + +## Como configurar + +### 1. Arduino +1. Abra `KVMote.ino` na Arduino IDE +2. Selecione a placa **Arduino Leonardo** +3. Faça o upload + +### 2. HC-06 (se necessário) +O HC-06 já vem configurado para 9600 baud de fábrica. Se você alterou, edite a constante no sketch: +```cpp +#define BAUD_HC06 9600 // ← altere se necessário +``` + +### 3. Par Bluetooth +1. Ligue o Arduino com o HC-06 +2. No PC Host: Configurações → Bluetooth → Adicionar dispositivo → `HC-06` +3. Senha padrão: `1234` +4. Anote a porta COM criada (ex: `COM5`) + +### 4. KVMote.exe +1. Compile o projeto ou use o executável publicado +2. Execute `KVMote.exe` no PC Host +3. A porta COM é **detectada automaticamente** via handshake PONG +4. Selecione a posição do PC cliente (Esquerda, Direita, Acima, Abaixo) +5. Selecione o layout do teclado do cliente +6. Clique em **Conectar** + +--- + +## Como usar + +### Controle de mouse e teclado +- Leve o cursor até a **borda da tela** na direção do PC cliente +- O cursor desaparece e o modo cliente é ativado (LED laranja no Arduino) +- Tudo que você digita e move o mouse vai para o PC cliente +- Para **voltar ao host**: mova o mouse na direção oposta (~15px além da borda virtual) + +### Clipboard de texto +1. Selecione e copie texto no host (**Ctrl+C**) — máximo 300 caracteres +2. Mude para o modo cliente (leve o mouse até a borda) +3. Pressione **Ctrl+V** (ou **Shift+Insert**) — o texto é digitado caractere a caractere no cliente + +> **Nota:** O clipboard é enviado como digitação, não como colagem nativa. Caracteres não-ASCII (acentos) e alguns símbolos dependem do layout configurado. + +--- + +## Protocolo serial (binário) + +| Comando | Bytes | Descrição | +|---|---|---| +| `M` dx dy | 3 | Movimento do mouse (int8 cada) | +| `W` delta | 2 | Roda do mouse (int8) | +| `K` char | 2 | Digitar caractere (Keyboard.write) | +| `P` key | 2 | Pressionar tecla (Keyboard.press) | +| `U` key | 2 | Soltar tecla (Keyboard.release) | +| `A` | 1 | Soltar todas as teclas | +| `C` L\|R | 2 | Clique do mouse | +| `D` L\|R | 2 | Pressionar botão do mouse | +| `E` L\|R | 2 | Soltar botão do mouse | +| `O` | 1 | LED laranja (entrou no cliente) | +| `H` | 1 | LED azul + flash verde (voltou ao host) | +| `~` | 1 | Ping → Arduino responde `[PONG]` | + +--- + +## Gerar executável portable + +```bash +# Self-contained (~70MB) — roda sem .NET instalado +dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true + +# Dependente do runtime (~2MB) — requer .NET 8 Desktop Runtime +dotnet publish -c Release -r win-x64 --self-contained false -p:PublishSingleFile=true +``` + +O `.exe` gerado fica em `bin\Release\net8.0-windows\win-x64\publish\`. + +--- + +## Limitações conhecidas + +- **Canal único (9600 baud):** durante o envio de clipboard, o mouse fica momentaneamente travado +- **Caracteres não-ASCII:** acentos (é, ã, ç) não são suportados no clipboard — são ignorados +- **Monitor único:** suporte a múltiplos monitores não implementado +- **PT-BR:** alguns símbolos (`/`, `?`, `\`, `@`) não podem ser enviados via clipboard no layout PT-BR ABNT2 + +--- + +## Roadmap + +- [ ] Suporte a múltiplos monitores +- [ ] Layout US-International como destino +- [ ] Mapeamento completo PT-BR (símbolos restantes via HID raw) +- [ ] Aplicativo separado de clipboard (OneDrive / TCP) para textos longos e imagens + +--- + +## Licença + +MIT — use, modifique e distribua livremente.