# M5Cardputer-SSHClient

Cliente SSH de bolso no M5Cardputer: ESP32, teclado físico e um shell remoto

- 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/tool-m5cardputer-sshclient

- Homepage: https://fernando.moretes.com

- Language: C++

- Topics: arduino, cardputer, cpp, embedded, esp32, iot, m5stack, moretes, portfolio, ssh

- Stars: 68

- Forks: 13

- Updated: 2026-09-29T16:37:55Z

---

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

- **Alvo único:** firmware em C++ para o M5Cardputer (ESP32, ecossistema Arduino), não uma biblioteca genérica.
- **Entrada e saída locais:** o teclado físico do Cardputer é a entrada do shell e a tela é o terminal.
- **Rede pelo Wi-Fi do próprio ESP32:** a sessão SSH sai do dispositivo direto para o host, sem ponte nem proxy.
- **Escopo de experimento:** o objetivo é entender limites de memória, tela e entrada, não substituir o OpenSSH.
- **Esteira padronizada:** branch, commit e release seguem as convenções do repositório `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.

### 🔧 M5Cardputer: firmware ESP32

- Teclado leitura de teclas (edge)
- Cliente SSH C++ / Arduino (compute)
- Tela terminal em texto (frontend)
- Wi-Fi pilha TCP/IP (network)

### 🌐 Rede local: destino

- Servidor SSH porta 22 (external)

### Fluxos

- user -> kbd: digita comandos
- kbd -> app: caracteres
- app -> wifi: canal SSH cifrado
- wifi -> host: TCP
- host -> app: saída do shell
- app -> screen: renderiza linhas

## 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-cli` e adicione o pacote de placas da M5Stack pela URL `https://static-cdn.m5stack.com/resource/arduino/package_m5stack_index.json`.

2. **Clone o repositório**: `git clone https://github.com/fernandofatech/tool-m5cardputer-sshclient.git` e abra o sketch principal.

3. **Instale as bibliotecas**: Instale as bibliotecas que os `#include` do 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 `G0` ao conectar.

6. **Conecte e teste**: Ligue o Cardputer, espere o Wi-Fi e a sessão abrirem e rode um comando curto como `uptime` antes de qualquer coisa interativa.

_Quickstart com arduino-cli. O FQBN segue o pacote atual da M5Stack; ajuste se o repositório declarar outro._

```bash
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=115200
```

> **Credencial 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`](https://github.com/fernandofatech/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](https://www.conventionalcommits.org). 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

- [GitHub: fernandofatech/tool-m5cardputer-sshclient](https://github.com/fernandofatech/tool-m5cardputer-sshclient)
- [Fernando F. Azevedo: portfólio](https://fernando.moretes.com)
- [fernandofatech/platform: convenções e workflows](https://github.com/fernandofatech/platform)
- [Conventional Commits](https://www.conventionalcommits.org)

## 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.

## Links

- [GitHub repository](https://github.com/fernandofatech/tool-m5cardputer-sshclient)
- [Homepage](https://fernando.moretes.com)