Teclado e mouse com Arduino Leonardo: monte um teclado de macros (HID)
Guia de teclado com Arduino Leonardo: ATmega32U4, Keyboard.h e Mouse.h, teclado de macros, mouse com joystick, carregamento com reset duplo e por que o Uno não pode ser um USB HID.
O Arduino Leonardo pode funcionar como teclado e mouse: conecte-o a um computador com um cabo USB e ele será reconhecido como um teclado de verdade. Não é necessário instalar um driver; Windows, macOS, Linux e até tablets o reconhecem como um teclado ou mouse USB comum. Isso permite montar um teclado de macros que envia seus atalhos favoritos, trechos de texto ou comandos de jogos com uma única tecla, um mouse controlado por joystick ou um dispositivo de entrada personalizado para usuários com deficiência. O pequeno Pro Micro, que usa o mesmo chip do Leonardo, pode fazer exatamente o mesmo.
Neste guia, você vai conhecer o chip ATmega32U4, que diferencia o Leonardo do Uno, e os comandos das bibliotecas Keyboard.h e Mouse.h, além de montar passo a passo um teclado de atalhos com quatro teclas e um mouse com joystick. Depois, vamos resolver o problema mais temido, o desaparecimento da porta após um carregamento, com o método de reset duplo, explicar por que o Uno não pode ser um teclado e mostrar como fazer o mesmo com um Raspberry Pi Pico. Para relembrar a ligação de botões, veja Como ligar um botão.

O diferencial do ATmega32U4: por que o Leonardo pode ser um teclado?
Todo dispositivo USB se apresenta com uma classe: porta serial (CDC), armazenamento, áudio ou HID (dispositivo de interface humana). Teclados e mouses são dispositivos HID. O ATmega32U4 do Leonardo tem hardware USB integrado, o que significa que seu programa decide como a porta USB se apresenta. O core do Arduino apresenta o chip como porta serial, teclado e mouse ao mesmo tempo; quando você chama Keyboard.begin(), o computador encontra um novo teclado. O ATmega328P do Uno não tem hardware USB, e as diferenças vão além do USB:
| Característica | Leonardo / Pro Micro (ATmega32U4) | Uno R3 / Nano (ATmega328P) |
|---|---|---|
| USB integrado | Sim, pode ser HID | Não, usa um chip USB-serial separado |
| Memória flash | 32 KB (4 KB de bootloader, 28 KB utilizáveis) | 32 KB (0,5 KB de bootloader) |
| SRAM | 2,5 KB | 2 KB |
| Entradas analógicas | 12 (A0-A5 + 6 nos pinos digitais) | 6 (8 no Nano) |
| Pinos I2C | D2 (SDA), D3 (SCL) | A4 (SDA), A5 (SCL) |
| Portas seriais | Serial = USB, Serial1 = D0/D1 | Uma Serial, compartilhada entre USB e D0/D1 |
| Pinos de interrupção externa | D0, D1, D2, D3, D7 | D2, D3 |
A linha de I2C na tabela esconde uma armadilha pequena, mas importante: um exemplo de OLED ou LCD escrito para o Uno não funciona no Leonardo, porque SDA e SCL ficam em D2/D3 em vez de A4/A5 (o conector SDA/SCL no canto superior chega ao lugar certo nas duas placas). Outra diferença está na porta serial: no Leonardo, Serial é a própria conexão USB, enquanto a porta serial de hardware nos pinos D0/D1 se chama Serial1. Você pode ver a disposição completa dos pinos na ferramenta Pinagem.
Por que um Arduino Uno não pode ser um teclado (HID)?
No Uno R3, o cabo USB não se conecta ao processador principal, mas ao pequeno chip ATmega16U2 ao lado do conector USB. De fábrica, esse chip executa apenas um firmware USB-serial; o computador sempre o reconhece como uma porta serial, e seu sketch não pode mudar isso. Por isso, escrever #include <Keyboard.h> em um Uno gera o erro de compilação “'Keyboard' was not declared in this scope”. Em teoria, você pode transformar um Uno em teclado regravando o firmware do 16U2 no modo DFU, mas a placa deixa de poder ser programada da maneira normal; isso não é recomendado para iniciantes. Nano, Mega e Pro Mini também não podem ser HID pelo mesmo motivo, e os clones de Nano com chip CH340 ou FT232 nem sequer têm essa opção.
| Placa | Teclado/mouse USB (HID) | Observação |
|---|---|---|
| Leonardo, Micro, Pro Micro | Sim | ATmega32U4, com Keyboard.h e Mouse.h |
| Uno R4 Minima / WiFi | Sim | USB integrado do chip Renesas RA4M1 |
| Raspberry Pi Pico | Sim | Core Arduino-Pico ou pacote usb-device do MicroPython |
| ESP32-S2 / ESP32-S3 | Sim | USBHIDKeyboard pelo USB integrado |
| ESP32 clássico | Somente Bluetooth | Pode funcionar como teclado BLE, mas não por USB |
| Uno R3, Nano, Mega, Pro Mini | Não | USB fornecido por um chip separado, somente porta serial |
Comandos de Keyboard.h e Mouse.h
| Comando | O que faz |
|---|---|
| Keyboard.begin() | Inicia o teclado; aceita opcionalmente um layout como KeyboardLayout_de_DE |
| Keyboard.print("text") / println() (envia o texto como digitação de teclado) | Digita o texto letra por letra; println acrescenta Enter ao final |
| Keyboard.write(c) | Pressiona e solta uma única tecla |
| Keyboard.press(k) / release(k) | Mantém uma tecla pressionada ou a solta; usado para atalhos |
| Keyboard.releaseAll() | Solta todas as teclas que estão pressionadas |
| KEY_LEFT_CTRL, KEY_LEFT_SHIFT, KEY_LEFT_ALT, KEY_LEFT_GUI | Ctrl, Shift, Alt e a tecla Windows/Cmd |
| KEY_RETURN, KEY_TAB, KEY_ESC, KEY_F1... | Enter, Tab, Esc, teclas de função e setas (KEY_UP_ARROW e assim por diante) |
| Mouse.move(x, y, wheel) | Move o cursor de forma relativa em passos de -128 a 127 |
| Mouse.click() / press() / release() (clique, pressionar e soltar o botão do mouse) | Botão MOUSE_LEFT, MOUSE_RIGHT ou MOUSE_MIDDLE |
Primeiro teste: digitar texto ao pressionar um botão
Conecte um terminal de um botão a D4 e o outro ao GND; o resistor de pull-up interno é usado, então nenhum outro componente é necessário. Ao escolher a placa, selecione Arduino Leonardo em Ferramentas > Placa (isso também funciona para um Pro Micro de 5 V e 16 MHz). Depois de carregar o código, abra um editor de texto, posicione o cursor nele e pressione o botão.
1// Leonardo: butona basınca yazı yaz / type text when the button is pressed
2#include <Keyboard.h>
3
4const int BUTTON_PIN = 4; // buton diğer ucu GND / other leg of the button to GND
5
6void setup() {
7 pinMode(BUTTON_PIN, INPUT_PULLUP);
8 Keyboard.begin(); // ya da Keyboard.begin(KeyboardLayout_de_DE) / or pick a layout
9}
10
11void loop() {
12 if (digitalRead(BUTTON_PIN) == LOW) {
13 Keyboard.println("Hello BlueGrays"); // yaz ve Enter'a bas / type and press Enter
14 delay(50);
15 while (digitalRead(BUTTON_PIN) == LOW) {} // bırakılmasını bekle / wait for release
16 delay(50);
17 }
18}Teclado de macros: monte seu próprio teclado de atalhos
Agora vamos montar um teclado de atalhos de verdade com quatro botões. Cada botão envia uma combinação de teclas; o código reage apenas no instante em que o botão é pressionado e filtra o repique com um tempo de debounce de 30 ms. Troque os botões por interruptores de teclado mecânico e imprima uma caixa em uma impressora 3D para ter um verdadeiro “stream deck” na sua mesa. Se quiser mais teclas, conecte um teclado matricial 4x4 no lugar dos quatro botões e defina 16 macros.
| Pino | Conexão | Windows / Linux | macOS (MAC = true) |
|---|---|---|---|
| D4 | Botão 1, outro terminal no GND | Ctrl+C (copiar) | Cmd+C |
| D5 | Botão 2, outro terminal no GND | Ctrl+V (colar) | Cmd+V |
| D6 | Botão 3, outro terminal no GND | Ctrl+Shift+T (reabrir aba) | Cmd+Shift+T |
| D7 | Botão 4, outro terminal no GND | Win+L (bloquear tela) | Ctrl+Cmd+Q |
| D9 | Chave ou jumper para GND | Segurança: funciona somente quando conectado | Igual |
1// Leonardo / Pro Micro makro tuş takımı / macro keypad
2#include <Keyboard.h>
3
4const bool MAC = false; // macOS için true / true for macOS
5const int ENABLE_PIN = 9; // GND'ye bağlıyken çalışır / works only when tied to GND
6const int KEY_PINS[4] = {4, 5, 6, 7}; // butonlar, diğer uç GND / buttons, other leg to GND
7const unsigned long DEBOUNCE_MS = 30;
8
9int lastState[4] = {HIGH, HIGH, HIGH, HIGH};
10unsigned long lastChange[4] = {0, 0, 0, 0};
11
12void sendCombo(uint8_t k1, uint8_t k2 = 0, uint8_t k3 = 0) {
13 Keyboard.press(k1); // tuşlara sırayla bas / press the keys in order
14 if (k2) Keyboard.press(k2);
15 if (k3) Keyboard.press(k3);
16 delay(30);
17 Keyboard.releaseAll(); // hepsini bırak / release them all
18}
19
20void runMacro(int i) {
21 const uint8_t MOD = MAC ? KEY_LEFT_GUI : KEY_LEFT_CTRL; // Cmd ya da Ctrl / Cmd or Ctrl
22 switch (i) {
23 case 0: sendCombo(MOD, 'c'); break; // kopyala / copy
24 case 1: sendCombo(MOD, 'v'); break; // yapıştır / paste
25 case 2: sendCombo(MOD, KEY_LEFT_SHIFT, 't'); break; // kapanan sekmeyi aç / reopen closed tab
26 case 3: // ekranı kilitle / lock the screen
27 if (MAC) sendCombo(KEY_LEFT_CTRL, KEY_LEFT_GUI, 'q');
28 else sendCombo(KEY_LEFT_GUI, 'l');
29 break;
30 }
31}
32
33void setup() {
34 pinMode(ENABLE_PIN, INPUT_PULLUP);
35 for (int i = 0; i < 4; i++) pinMode(KEY_PINS[i], INPUT_PULLUP);
36 Keyboard.begin();
37}
38
39void loop() {
40 bool enabled = digitalRead(ENABLE_PIN) == LOW; // güvenlik anahtarı / safety switch
41 for (int i = 0; i < 4; i++) {
42 int s = digitalRead(KEY_PINS[i]);
43 if (s != lastState[i] && millis() - lastChange[i] > DEBOUNCE_MS) {
44 lastChange[i] = millis();
45 lastState[i] = s;
46 if (s == LOW && enabled) runMacro(i); // yalnız basış anında / only on press
47 }
48 }
49}- Use letras minúsculas para as teclas de letras ('c', 'v'); com uma letra maiúscula, a biblioteca também pressiona Shift e envia um atalho diferente, como Ctrl+Shift+C.
- sendCombo() pressiona as teclas em ordem, espera 30 ms e solta todas com releaseAll(); essa pausa é necessária para que alguns programas detectem o atalho.
- Cada botão mantém seu próprio tempo de debounce, então pressionar dois botões quase ao mesmo tempo não causa problemas. Veja por que a temporização usa millis() em vez de delay() em millis() versus delay().
- As teclas de volume e de mídia não fazem parte de Keyboard.h; elas precisam de uma biblioteca com suporte a Consumer Control, como HID-Project.
Montando um mouse USB com joystick

Conecte o VCC do módulo de joystick a 5V, GND a GND, VRx a A0, VRy a A1 e SW a D8. Na inicialização, o código armazena o valor em repouso como centro, ignora uma faixa de ±40 ao redor dele (a zona morta) e transforma o deslocamento em um movimento de no máximo 10 pixels por passo. Não toque no joystick ao conectar a placa, ou o centro errado será armazenado. Para conhecer o funcionamento interno do joystick e suas faixas de valores, veja o artigo sobre o módulo de joystick.
1// Leonardo: joystick ile fare / joystick mouse
2#include <Mouse.h>
3
4const int X_PIN = A0; // joystick VRx
5const int Y_PIN = A1; // joystick VRy
6const int SW_PIN = 8; // joystick SW (basınca GND / pulls to GND when pressed)
7const int DEADZONE = 40; // merkezdeki titreşimi yok say / ignore jitter around the centre
8const int MAX_SPEED = 10; // adım başına en fazla piksel / max pixels per step
9
10int centerX, centerY;
11
12int axis(int raw, int center) {
13 int d = raw - center;
14 if (abs(d) < DEADZONE) return 0;
15 return map(d, -512, 512, -MAX_SPEED, MAX_SPEED);
16}
17
18void setup() {
19 pinMode(SW_PIN, INPUT_PULLUP);
20 centerX = analogRead(X_PIN); // açılışta merkez ölçümü, joystick'e dokunma / centre calibration, don't touch
21 centerY = analogRead(Y_PIN);
22 Mouse.begin();
23}
24
25void loop() {
26 int dx = axis(analogRead(X_PIN), centerX);
27 int dy = axis(analogRead(Y_PIN), centerY); // ters ise -axis(...) yaz / use -axis(...) if inverted
28 if (dx != 0 || dy != 0) Mouse.move(dx, dy, 0);
29
30 if (digitalRead(SW_PIN) == LOW) {
31 if (!Mouse.isPressed(MOUSE_LEFT)) Mouse.press(MOUSE_LEFT); // sol tık basılı / left button down
32 } else if (Mouse.isPressed(MOUSE_LEFT)) {
33 Mouse.release(MOUSE_LEFT); // bırak / release
34 }
35 delay(10); // saniyede yaklaşık 100 güncelleme / about 100 updates per second
36}A porta desapareceu: carregando com reset duplo
Como seu sketch controla o USB no Leonardo, o computador não consegue enxergar a porta se o sketch falhar, travar em um loop infinito ou nunca iniciar o USB. Normalmente, o Arduino IDE abre e fecha brevemente a porta a 1.200 baud quando um carregamento começa; esse “toque” coloca a placa no bootloader, e o código é carregado em segundos. Quando a porta desaparece, esse toque não pode acontecer, mas você pode iniciar o bootloader manualmente: após um reset, ele espera cerca de 8 segundos por um novo código. Isso também explica por que o número da porta muda por um instante durante o carregamento.
- Abra um sketch que você sabe que funciona (por exemplo, Arquivo > Exemplos > Basics > Blink) com Leonardo selecionado como placa.
- Clique em Carregar e aguarde o fim da compilação na saída abaixo.
- Assim que aparecer “Carregando...”, pressione uma vez o botão de reset do Leonardo; em um Pro Micro sem botão, encoste o pino RST no GND duas vezes rapidamente.
- Se o LED da placa estiver “respirando” lentamente, ela está no bootloader; o IDE encontra a nova porta e carrega o código.
- Se não funcionar, tente novamente mudando o momento do reset; em algumas tentativas você acertará o instante certo.
Uma alternativa de teclado USB com o Raspberry Pi Pico
O chip RP2040 do Raspberry Pi Pico também tem USB integrado e custa menos que um Leonardo. Se você usar o pacote Raspberry Pi Pico/RP2040 de Earle Philhower no Arduino IDE, os mesmos comandos de Keyboard.h e Mouse.h funcionarão quase sem alterações; basta ajustar os números dos pinos para os pinos GP. Se preferir MicroPython, a partir da versão 1.23 o pacote oficial usb-device-keyboard transforma o Pico em um teclado. Instale-o na placa pelo computador com mpremote mip install usb-device-keyboard. Quando o código é executado, o Pico reenumera seu USB com um teclado, então a conexão do Thonny cai; isso é normal. Se você está começando com o Pico, leia primeiro O que é Raspberry Pi Pico?.
1# Raspberry Pi Pico: MicroPython USB makro klavye / USB macro keyboard
2# Önce / first: mpremote mip install usb-device-keyboard (MicroPython 1.23+)
3import time
4import usb.device
5from usb.device.keyboard import KeyboardInterface, KeyCode
6from machine import Pin
7
8MACROS = (
9 (Pin(2, Pin.IN, Pin.PULL_UP), (KeyCode.LEFT_CTRL, KeyCode.C)), # kopyala / copy
10 (Pin(3, Pin.IN, Pin.PULL_UP), (KeyCode.LEFT_CTRL, KeyCode.V)), # yapıştır / paste
11 (Pin(4, Pin.IN, Pin.PULL_UP), (KeyCode.LEFT_UI, KeyCode.L)), # Windows: ekranı kilitle / lock screen
12)
13
14kb = KeyboardInterface()
15usb.device.get().init(kb, builtin_driver=True) # USB'yi klavyeyle yeniden tanıt / re-enumerate with a keyboard
16
17
18def tap(keys):
19 kb.send_keys(keys) # tuşlara bas / press the keys
20 time.sleep_ms(20)
21 kb.send_keys(()) # hepsini bırak / release all
22
23
24last = [1] * len(MACROS)
25while True:
26 if kb.is_open():
27 for i, (pin, keys) in enumerate(MACROS):
28 v = pin.value()
29 if v == 0 and last[i] == 1: # basış anı / moment of press
30 tap(keys)
31 last[i] = v
32 time.sleep_ms(10) # basit debounce / simple debounceIdeias de projetos de teclado com Arduino Leonardo
- Teclado para desenvolvedores: associe atalhos do editor, como compilar, executar, comentar linha e abrir terminal, a teclas individuais.
- Painel para reuniões: associe os atalhos de silenciar o microfone e desligar a câmera a botões grandes e iluminados.
- Botão giratório de rolagem: role páginas com um encoder rotativo, enviando Mouse.move(0, 0, step) como a roda de um mouse.
- Mouse acessível: clique com botões grandes ou um pedal e mova o cursor com um joystick.
- Controle remoto para apresentações: um pequeno controle com dois botões que envia as teclas de seta para a esquerda e para a direita.
- Painel de controle para jogos: um cockpit cheio de chaves e botões para jogos de voo ou de corrida.
Erros comuns e como corrigir
| Sintoma | Causa | Solução |
|---|---|---|
| 'Keyboard' was not declared in this scope (Keyboard não foi declarado neste escopo) | Uno, Nano ou Mega selecionado | Use um Leonardo, Micro ou Pro Micro |
| A porta desapareceu após o carregamento | O sketch travou ou causou uma falha no USB | Carregue um sketch que você sabe que funciona usando reset duplo |
| A placa continua enviando teclas | Keyboard.print() incondicional ou pino de botão flutuante | Use INPUT_PULLUP e uma chave de segurança |
| Aparecem caracteres errados | Layout de teclado incompatível | Keyboard.begin(KeyboardLayout_xx_XX) ou mude para o layout americano |
| O código só inicia quando o Monitor Serial é aberto | while (!Serial); em setup() | Remova essa linha ou adicione um tempo limite |
| O OLED de um exemplo para Uno não funciona | Pinos I2C diferentes | Conecte SDA a D2 e SCL a D3 |
| O Pro Micro nunca aparece | Código de 16 MHz carregado em uma placa de 8 MHz | Escolha a placa correta com o pacote da SparkFun e faça um reset duplo |
Leonardo e Pro Micro são a maneira mais fácil de montar seu primeiro dispositivo eletrônico que se comunica com um computador: alguns botões, um pouco de código e você já tem seu próprio teclado de atalhos. No app BlueGrays, você encontra os projetos Teclado para desenvolvedores Arduino e Teclado para desenvolvedores Python, além de projetos com botões, teclados matriciais e joysticks, todos com esquemas do circuito e código passo a passo, prontos para combinar com as técnicas de HID deste artigo.
Perguntas frequentes
Como usar um Arduino Leonardo como teclado?
Adicione #include <Keyboard.h> ao seu sketch e chame Keyboard.begin() em setup(). Depois, você pode digitar texto com Keyboard.print() e enviar atalhos como Ctrl+C com Keyboard.press() e releaseAll(). Sempre vincule o código a um botão, caso contrário a placa enviará teclas sem parar.
Um Arduino Uno pode ser usado como teclado?
Não diretamente, porque o Uno R3 usa um chip ATmega16U2 separado que apresenta o USB apenas como porta serial. É possível regravar esse chip via DFU, mas o procedimento é trabalhoso. Para projetos de teclado e mouse, é muito mais fácil usar Leonardo, Pro Micro, Uno R4 ou Raspberry Pi Pico.
Qual é a diferença entre o Leonardo e o Pro Micro?
Os dois usam o mesmo chip ATmega32U4 e executam o mesmo código. O Pro Micro é muito menor, normalmente não tem botão de reset e tem duas versões, 5 V/16 MHz e 3,3 V/8 MHz. Para o Pro Micro de 5 V, você pode selecionar Arduino Leonardo no Arduino IDE.
A porta do meu Arduino Leonardo não aparece. O que fazer?
Seu sketch pode ter travado ou causado uma falha no USB. Comece a carregar um sketch que você sabe que funciona e pressione reset assim que o IDE mostrar “Carregando”; em um Pro Micro, encoste RST no GND duas vezes rapidamente. A placa permanece no bootloader por alguns segundos, e o código é carregado.
Por que meu Leonardo digita caracteres errados?
A biblioteca Keyboard envia teclas pela posição delas em um layout americano. Em um computador configurado com outro layout, como QWERTZ alemão ou AZERTY francês, algumas letras e símbolos saem errados. Chame Keyboard.begin(KeyboardLayout_de_DE) ou outro layout compatível, ou mude o computador para o layout americano.
Um Raspberry Pi Pico pode ser um teclado USB?
Sim. Graças ao USB integrado do RP2040, o Pico funciona como teclado com Keyboard.h e Mouse.h no core Arduino-Pico, ou com o pacote usb-device-keyboard no MicroPython 1.23 e versões posteriores. Ele é barato e potente, o que o torna uma boa escolha para teclados de macros.
Projetos para montar depois desta leitura
Ver todos os projetos
Teclado para programar em Arduino
Se você se cansou de digitar as mesmas linhas várias vezes ao programar, este pequeno teclado matricial vira seu teclado de atalhos.

Teclado para programar em Python
Se você se cansou de digitar os mesmos padrões várias vezes ao programar, este pequeno teclado é para você.

Controle de LED com botão (momentâneo)
É como uma campainha: a luz fica acesa enquanto você pressiona o botão e apaga quando você solta.

Ligar e desligar um LED com botão
Pressione o botão uma vez para acender a luz e outra vez para apagar, como o interruptor do seu quarto.

Uso do teclado matricial 3x4
O Arduino identifica na hora qual tecla você pressiona em um teclado de 12 teclas parecido com o de um telefone e a mostra na tela do computador.

Uso do teclado matricial 4x4
No teclado matricial 4x4, parecido com as teclas de um telefone, o Arduino identifica na hora qual tecla você pressionou e a mostra na tela do computador.

Controle de LEDs com joystick
Empurre a alavanca do joystick até o fim em qualquer direção e o LED correspondente acende: são quatro cores diferentes para direita, esquerda, cima e baixo.

Controle de servos com joystick
Controle dois motores com um joystick, como ao girar uma câmera de segurança. Empurre a alavanca para os lados e o servo motor inferior gira lentamente; mova para cima ou para baixo e o servo…
Mais artigos
App BlueGrays
Monte este circuito passo a passo pelo celular
Esquema do circuito, código e lista de componentes em uma só tela. Mais de 500 projetos com Arduino, ESP32 e Pico prontos para montar.
Escaneie com seu celular
Aponte a câmera para o código para abrir a loja de aplicativos do seu celular.
ou abrir a loja

