M5Cardputer-SSHClient
Cliente SSH de bolso no M5Cardputer: ESP32, teclado físico e um shell remoto
git clone https://github.com/fernandofatech/tool-m5cardputer-sshclient.gitOuvir guia
gerado ao ouvirGerado apenas no primeiro play
Com tecnologia Amazon Polly + OmniVoice
O M5Cardputer-SSHClient é um experimento em C++ que transforma o M5Cardputer, um computador de bolso baseado em ESP32 com teclado e tela próprios, num cliente SSH capaz de abrir um shell num servidor da sua rede sem notebook nenhum por perto.
O que é e por que existe
A pergunta que me levou a esse repositório não foi "dá para rodar SSH num microcontrolador?". Dá, e isso já foi provado por outras pessoas. A pergunta foi: quanto do que eu tomo como garantido num cliente SSH desaparece quando a máquina tem algumas centenas de KB de RAM, uma tela minúscula e um teclado de 56 teclas?
O M5Cardputer, da M5Stack, é um alvo bom para essa pergunta. É um ESP32 com Wi-Fi, teclado físico, tela e bateria, tudo num formato de cartão. Ele já é usado como brinquedo de hardware e como ferramenta de bancada; um shell remoto nele vira algo prático: checar um serviço no homelab, reiniciar um container, ler um log, sem tirar o notebook da mochila.
O repositório é declaradamente um experimento. Ele está no meu portfólio na trilha de embarcados, IoT e ferramentas de desenvolvedor, ao lado de projetos de arquitetura em nuvem, porque o raciocínio é o mesmo: entender o custo real de cada camada quando o recurso é escasso. Não trate como produto pronto. Trate como ponto de partida bem delimitado para quem quer um terminal remoto no Cardputer e prefere ler o código a começar do zero.
O que você encontra aqui
platform.Como uma sessão acontece
O fluxo é curto de propósito: tudo roda no ESP32, e o único par remoto é o servidor SSH que você escolher.
- Teclado · leitura de teclas
- Cliente SSH · C++ / Arduino
- Tela · terminal em texto
- Wi-Fi · pilha TCP/IP
- Servidor SSH · porta 22
Como funciona
A arquitetura cabe em quatro peças, e nenhuma delas sai do dispositivo.
Entrada: o firmware lê o teclado matricial do Cardputer e converte cada tecla em caractere. Sem teclado completo, combinações como Ctrl+C e setas dependem de mapeamento por tecla de função; é aí que a experiência mais difere de um terminal comum.
Rede: o ESP32 conecta no Wi-Fi e abre uma conexão TCP com o host, normalmente na porta 22. Não há servidor intermediário: se o seu notebook alcança o host, o Cardputer na mesma rede também alcança.
Sessão SSH: o handshake, a troca de chaves e a cifra rodam no próprio ESP32. É a parte mais cara em CPU e memória, e a razão de eu chamar isso de experimento: algoritmos pesados de troca de chave aumentam o tempo de conexão de forma perceptível num microcontrolador.
Saída: o texto devolvido pelo shell é desenhado na tela. Numa tela desse tamanho cabem poucas colunas, então comandos com saída larga, como htop ou docker ps sem formatação, quebram linha ou ficam ilegíveis. Comandos curtos e saída filtrada com tail, grep ou --format funcionam bem.
Confira no código a biblioteca SSH e a versão do pacote de placas usadas; elas definem quais algoritmos de chave e cifra o cliente aceita.
Instalar e usar
- 1
Prepare o ambiente Arduino
Instale o Arduino IDE 2 ou o
arduino-clie adicione o pacote de placas da M5Stack pela URLhttps://static-cdn.m5stack.com/resource/arduino/package_m5stack_index.json. - 2
Clone o repositório
git clone https://github.com/fernandofatech/tool-m5cardputer-sshclient.gite abra o sketch principal. - 3
Instale as bibliotecas
Instale as bibliotecas que os
#includedo sketch pedirem, em especial a do M5Cardputer e a de SSH. Compilar antes de instalar é o jeito mais rápido de descobrir o que falta. - 4
Configure rede e destino
Ajuste SSID, senha do Wi-Fi, host, porta e usuário onde o código define esses valores. Não versione esse arquivo com credencial real.
- 5
Compile e grave
Selecione a placa M5Cardputer, conecte por USB-C e grave. Se a gravação não começar, coloque o dispositivo em modo de download segurando o botão
G0ao conectar. - 6
Conecte e teste
Ligue o Cardputer, espere o Wi-Fi e a sessão abrirem e rode um comando curto como
uptimeantes de qualquer coisa interativa.
git clone https://github.com/fernandofatech/tool-m5cardputer-sshclient.git
cd tool-m5cardputer-sshclient
arduino-cli config add board_manager.additional_urls \
https://static-cdn.m5stack.com/resource/arduino/package_m5stack_index.json
arduino-cli core update-index
arduino-cli core install m5stack:esp32
arduino-cli lib install M5Cardputer
# edite Wi-Fi, host e usuario no sketch antes de compilar
arduino-cli compile --fqbn m5stack:esp32:m5stack_cardputer .
arduino-cli upload --fqbn m5stack:esp32:m5stack_cardputer -p /dev/cu.usbmodem* .
arduino-cli monitor -p /dev/cu.usbmodem* -c baudrate=115200Credencial dentro do firmware
Senha de Wi-Fi e credencial SSH gravadas no firmware podem ser extraídas de quem tiver o dispositivo na mão: a flash do ESP32 sem criptografia habilitada é legível por USB. Use um usuário dedicado com permissão mínima no host, prefira uma rede de laboratório e não aponte isso para máquina com acesso a produção.
Limites que você vai encontrar
Ser honesto sobre o que não funciona é a parte mais útil de um experimento.
Programas de tela cheia: vim, htop e tmux dependem de um emulador de terminal com sequências de escape completas e de uma janela de pelo menos 80 colunas. Numa tela de 240 por 135 pixels isso não cabe, então espere ver caracteres de controle ou layout quebrado.
Tempo de conexão: a troca de chaves num microcontrolador leva segundos, não milissegundos. Para uso pontual é aceitável; para abrir e fechar sessão dezenas de vezes, não.
Algoritmos aceitos: servidores OpenSSH recentes desabilitam algoritmos antigos por padrão. Se o handshake falhar, o primeiro lugar a olhar é o /var/log/auth.log do host, que diz qual algoritmo foi recusado.
Validação de host: num cliente de bolso, conferir a chave do servidor é fácil de esquecer e é exatamente o que separa SSH de telnet cifrado. Verifique no código se o fingerprint é checado antes de usar fora da sua rede.
Contribuindo
O repositório segue as convenções do platform, o mesmo que governa os meus outros projetos.
Branch: <tipo>/<escopo>, com feat/, fix/, chore/ ou docs/.
Commit e título de PR: Conventional Commits. Não é preciosismo: a versão sai dos commits, e ninguém escreve número de versão à mão.
Pipeline: pr-lint, CI, segurança e release vêm dos workflows reutilizáveis do platform. Se a régua estiver errada, a correção é num arquivo lá, não aqui. Manter uma esteira por repositório parece barato no primeiro dia e custa caro no vigésimo repositório, quando cada um diverge um pouco.
Contribuições que mais ajudariam: mapeamento de teclas especiais, rolagem de saída na tela e verificação explícita de fingerprint do host.
Perguntas frequentes
Funciona em outro ESP32 sem ser o Cardputer?
A parte de rede e SSH é portável, mas teclado e tela são específicos do Cardputer. Em outra placa você reescreve entrada e saída.
Consigo acessar um servidor pela internet?
Tecnicamente sim, se o host for alcançável. Eu não recomendo sem validação de fingerprint e sem usuário restrito, pelos motivos do aviso acima.
Suporta autenticação por chave?
Depende do que está implementado no código e da biblioteca SSH usada. Confira o sketch antes de assumir; o README não declara.
Referências
Para quem é
Use quando você já tem um M5Cardputer, quer um shell remoto para tarefas curtas no homelab ou na bancada e aceita ler e ajustar C++ para isso. Não use como cliente SSH principal, nem contra host com acesso a produção, nem se precisa de programas de tela cheia: para isso, um celular com Termux ou um notebook resolve com menos risco. O valor real aqui é o mapa de onde SSH aperta num ESP32, não a substituição do seu terminal.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser