# M5Cardputer-SSHClient Terminal SSH no bolso: cliente embarcado para M5Stack Cardputer com teclado físico. - URL: https://fernando.moretes.com/open-source/M5Cardputer-SSHClient - Markdown: https://fernando.moretes.com/open-source/M5Cardputer-SSHClient/guide.md?lang=pt - GitHub: https://github.com/fernandofatech/M5Cardputer-SSHClient - Homepage: https://fernando.moretes.com - Language: C++ - Topics: arduino, cardputer, cpp, embedded, esp32, iot, m5stack, moretes, portfolio, ssh - Stars: 64 - Forks: 11 - Updated: 2026-05-16T01:15:22Z --- M5Cardputer-SSHClient é um cliente SSH embarcado escrito em C++ para o M5Stack Cardputer — um dispositivo ESP32 com teclado físico do tamanho de um cartão — permitindo abrir sessões SSH em servidores remotos sem nenhum laptop. ## O que é e por que existe O M5Stack Cardputer é um microcontrolador ESP32-S3 com display colorido, teclado QWERTY integrado e fator de forma de cartão de crédito espesso. É um hardware incomum: poderoso o suficiente para rodar TLS e TCP/IP via Wi-Fi, pequeno o suficiente para caber no bolso de uma jaqueta. Este repositório nasceu de uma pergunta prática: *dá para gerenciar um servidor Linux diretamente desse dispositivo, sem depender de celular ou notebook?* A resposta é sim, com algumas concessões de UX que vêm com qualquer terminal de 240×135 pixels. Do ponto de vista de portfólio, o projeto demonstra capacidade de trabalhar em toda a pilha — desde alocação de memória em C++ embarcado até protocolos de rede seguros — algo que complementa o trabalho de arquitetura cloud que faço no dia a dia. Não é um produto comercial; é um experimento deliberado que mantive público porque as perguntas que ele responde (SSH em ESP32, teclado físico, hosts salvos) aparecem com frequência em fóruns de IoT e maker. ## Funcionalidades principais - **Sessão SSH via Wi-Fi** — conecta a servidores remotos usando o stack TCP/IP nativo do ESP32. - **Teclado físico integrado** — entrada de texto real sem teclado virtual na tela, fundamental para um terminal utilizável. - **Hosts salvos** — configuração de destinos frequentes para evitar redigitar endereços e usuários a cada sessão. - **C++ puro com Arduino/ESP-IDF** — sem frameworks pesados; código direto ao ponto para um dispositivo com poucos megabytes de RAM. - **Layout modular** — estrutura de projeto orientada a produção, facilitando extensões como suporte a chaves ou múltiplas sessões. ## Como o sistema funciona Fluxo de uma sessão SSH a partir do Cardputer até o servidor remoto. ### 🖐️ Usuário - Engenheiro (teclado físico) (user) ### 📟 Dispositivo - Keyboard Input Handler (frontend) - Display Terminal UI (frontend) - Saved Hosts (Flash/NVS) (storage) - SSH Client Library (C++) (compute) - Wi-Fi Stack ESP32-S3 (network) ### ☁️ Remoto - SSH Server (Linux host) (external) ### Fluxos - user -> keyboard: digita - keyboard -> ui: renderiza entrada - keyboard -> sshclient: envia comando - ui -> hoststore: lê hosts salvos - sshclient -> wifi: TCP/TLS - wifi -> server: SSH :22 - server -> wifi: resposta shell - wifi -> ui: saída do terminal ## Decisões técnicas e limitações honestas O ESP32-S3 no Cardputer tem Wi-Fi 802.11 b/g/n e suporte a TLS via mbedTLS, que já vem integrado ao ESP-IDF e ao core Arduino para ESP32. Isso torna o SSH tecnicamente viável sem bibliotecas externas de criptografia pesadas — o handshake TLS roda no próprio chip. A maior restrição é a tela: 240×135 pixels limitam severamente quantas linhas de terminal cabem visíveis ao mesmo tempo. Comandos com saída longa (como `docker ps` ou `journalctl`) exigem scroll, e a implementação atual é adequada para tarefas de depuração rápida, não para edição de arquivos ou sessões longas de compilação. A autenticação por senha é o caminho mais direto dado o hardware; autenticação por chave pública exigiria armazenar a chave privada na flash do dispositivo, o que levanta questões de segurança que merecem atenção antes de qualquer uso em produção. Trate este projeto como uma prova de conceito funcional, não como um cliente SSH endurecido para ambientes críticos. A estrutura modular do código sugere que extensões — múltiplos perfis de host, autenticação por chave, histórico de comandos — são caminhos naturais de evolução, e o roadmap no README confirma essa intenção. > **Segurança em dispositivos embarcados:** Credenciais armazenadas na flash do ESP32 não têm o mesmo nível de proteção que um cofre de chaves em um sistema operacional convencional. Se você usar este cliente em redes não confiáveis ou armazenar senhas de servidores críticos, avalie as implicações. Para uso pessoal e redes domésticas/lab, o risco é gerenciável; para ambientes corporativos, considere autenticação por chave com armazenamento seguro. ## Instalação e uso 1. **Pré-requisitos de hardware e software** — Você precisa de um M5Stack Cardputer (ESP32-S3), um cabo USB-C, e uma das duas toolchains: **Arduino IDE 2.x** com o board package `esp32` da Espressif, ou **PlatformIO** (VS Code ou CLI). Instale também a biblioteca M5Cardputer via Library Manager ou `lib_deps` no PlatformIO. 2. **Clonar o repositório** — Execute `git clone https://github.com/fernandofatech/M5Cardputer-SSHClient.git` e entre no diretório com `cd M5Cardputer-SSHClient`. 3. **Configurar credenciais Wi-Fi e hosts** — Localize o arquivo de configuração no código-fonte (tipicamente um header ou `config.h`) e preencha o SSID, senha Wi-Fi e os hosts SSH que deseja salvar. Não commite credenciais reais; use um arquivo de exemplo versionado e o arquivo real no `.gitignore`. 4. **Compilar e gravar (Arduino IDE)** — Abra o arquivo `.ino` principal no Arduino IDE. Selecione a placa **M5Stack-Cardputer** (ou ESP32S3 Dev Module com as configurações corretas de flash/PSRAM). Clique em **Upload**. O IDE compila e grava via USB-C automaticamente. 5. **Compilar e gravar (PlatformIO)** — Com o Cardputer conectado via USB-C, execute `pio run --target upload` na raiz do projeto. O PlatformIO resolve dependências, compila e grava. Use `pio device monitor` para ver logs seriais durante o desenvolvimento. 6. **Usar o cliente no dispositivo** — Após o boot, o dispositivo conecta ao Wi-Fi configurado. Navegue pelos hosts salvos com o teclado, selecione um destino, insira a senha quando solicitado e a sessão SSH abre no display. Digite comandos normalmente; a saída aparece na tela em tempo real. _Fluxo completo: clonar, configurar e gravar via PlatformIO_ ```bash # 1. Clone git clone https://github.com/fernandofatech/M5Cardputer-SSHClient.git cd M5Cardputer-SSHClient # 2. Copy and edit config (keep real credentials out of git) cp config.example.h config.h # edit config.h with your SSID, password, and SSH hosts # 3. Build and flash (PlatformIO) pio run --target upload # 4. Monitor serial output (optional, useful during dev) pio device monitor --baud 115200 # --- Arduino IDE alternative --- # Open the .ino file, select board: M5Stack-Cardputer # Tools > Upload Speed: 921600 # Sketch > Upload ``` ## Perguntas frequentes ### Funciona com qualquer servidor SSH ou só com configurações específicas? Deve funcionar com qualquer servidor OpenSSH padrão que aceite autenticação por senha. Configurações que forçam apenas chave pública ou que exigem autenticação multifator vão bloquear a conexão na versão atual. ### Preciso do M5Stack Cardputer exatamente, ou outro ESP32 funciona? O código usa a biblioteca M5Cardputer para o display e o teclado. Portar para outro hardware ESP32 exigiria substituir essas camadas de I/O — é viável, mas não é um drop-in replacement. ### O projeto suporta autenticação por chave SSH? Não na versão atual. O roadmap indica melhorias contínuas, mas autenticação por chave em dispositivos embarcados exige cuidado com armazenamento seguro da chave privada na flash. ### Qual é o tamanho do binário compilado? Não documentado no README, mas projetos similares com mbedTLS e M5Stack ficam tipicamente entre 800 KB e 1.2 MB de flash. O Cardputer tem 8 MB de flash, então não é uma restrição prática. ## Para quem é este projeto Este repositório é útil para três perfis: **makers e entusiastas de IoT** que querem explorar o que o Cardputer consegue fazer além de demos; **engenheiros embarcados** que precisam de um ponto de partida para SSH em ESP32 com teclado físico; e **recrutadores técnicos** que querem ver como eu trabalho em camadas baixas da pilha, fora do contexto cloud. Não é um substituto para um cliente SSH de produção em um laptop — a tela pequena e a ausência de autenticação por chave deixam isso claro. Mas como ferramenta de depuração de campo para acessar um Raspberry Pi ou um servidor de borda sem carregar um notebook, ele cumpre exatamente o que promete. ## Referências e links - [fernandofatech/M5Cardputer-SSHClient — GitHub](https://github.com/fernandofatech/M5Cardputer-SSHClient) - [Fernando Azevedo — Portfolio (fernando.moretes.com)](https://fernando.moretes.com) - [M5Stack Cardputer — Hardware documentation](https://docs.m5stack.com/en/core/Cardputer) - [Espressif ESP32-S3 — Technical Reference](https://www.espressif.com/en/products/socs/esp32-s3) - [PlatformIO — Embedded development platform](https://platformio.org) - [Arduino core for ESP32 — Espressif GitHub](https://github.com/espressif/arduino-esp32) ## Links - [GitHub repository](https://github.com/fernandofatech/M5Cardputer-SSHClient) - [Homepage](https://fernando.moretes.com)