M5Cardputer-SSHClient
SSH in your pocket: embedded terminal client for the M5Stack Cardputer with physical keyboard.
git clone https://github.com/fernandofatech/M5Cardputer-SSHClient.gitM5Cardputer-SSHClient is an embedded SSH client written in C++ for the M5Stack Cardputer — a card-sized ESP32 device with a physical keyboard — letting you open SSH sessions to remote servers with no laptop in hand.
What it is and why it exists
The M5Stack Cardputer is an ESP32-S3 microcontroller with a color display, integrated QWERTY keyboard, and a thick credit-card form factor. It is unusual hardware: powerful enough to run TLS and TCP/IP over Wi-Fi, small enough to fit in a jacket pocket.
This repository started from a practical question: can you manage a Linux server directly from this device, without relying on a phone or laptop? The answer is yes, with the UX concessions that come with any 240×135-pixel terminal.
From a portfolio standpoint, the project demonstrates the ability to work across the full stack — from C++ memory management on bare metal to secure network protocols — which complements the cloud architecture work I do day-to-day. It is not a commercial product; it is a deliberate experiment I kept public because the questions it answers (SSH on ESP32, physical keyboard, saved hosts) come up frequently in IoT and maker forums.
Key features
How the system works
Flow of an SSH session from the Cardputer to the remote server.
- Engenheiro · (teclado físico)
- Keyboard · Input Handler
- Display · Terminal UI
- Saved Hosts · (Flash/NVS)
- SSH Client · Library (C++)
- Wi-Fi Stack · ESP32-S3
- SSH Server · (Linux host)
Technical decisions and honest limitations
The ESP32-S3 in the Cardputer has 802.11 b/g/n Wi-Fi and TLS support via mbedTLS, which ships integrated with ESP-IDF and the Arduino core for ESP32. That makes SSH technically feasible without heavy external crypto libraries — the TLS handshake runs on the chip itself.
The biggest constraint is the screen: 240×135 pixels severely limits how many terminal lines are visible at once. Commands with long output (like docker ps or journalctl) require scrolling, and the current implementation is well-suited for quick debugging tasks, not for file editing or long build sessions.
Password authentication is the most direct path given the hardware; public-key authentication would require storing a private key in device flash, which raises security questions worth addressing before any production use. Treat this project as a functional proof of concept, not a hardened SSH client for critical environments.
The modular code structure suggests that extensions — multiple host profiles, key-based auth, command history — are natural evolution paths, and the roadmap in the README confirms that intent.
Security on embedded devices
Credentials stored in ESP32 flash do not have the same protection level as a keychain on a conventional OS. If you use this client on untrusted networks or store passwords for critical servers, assess the implications. For personal use and home/lab networks the risk is manageable; for corporate environments, consider key-based auth with secure storage.
Installation and use
- 1
Hardware and software prerequisites
You need an M5Stack Cardputer (ESP32-S3), a USB-C cable, and one of two toolchains: Arduino IDE 2.x with Espressif's
esp32board package, or PlatformIO (VS Code or CLI). Also install the M5Cardputer library via Library Manager orlib_depsin PlatformIO. - 2
Clone the repository
Run
git clone https://github.com/fernandofatech/M5Cardputer-SSHClient.gitand enter the directory withcd M5Cardputer-SSHClient. - 3
Configure Wi-Fi credentials and hosts
Locate the configuration file in the source tree (typically a header or
config.h) and fill in your SSID, Wi-Fi password, and the SSH hosts you want to save. Do not commit real credentials; use a versioned example file and keep the real one in.gitignore. - 4
Build and flash (Arduino IDE)
Open the main
.inofile in Arduino IDE. Select the M5Stack-Cardputer board (or ESP32S3 Dev Module with correct flash/PSRAM settings). Click Upload. The IDE compiles and flashes over USB-C automatically. - 5
Build and flash (PlatformIO)
With the Cardputer connected via USB-C, run
pio run --target uploadfrom the project root. PlatformIO resolves dependencies, compiles, and flashes. Usepio device monitorto see serial logs during development. - 6
Using the client on the device
After boot, the device connects to the configured Wi-Fi. Navigate saved hosts with the keyboard, select a target, enter the password when prompted, and the SSH session opens on the display. Type commands normally; output appears on screen in real time.
# 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 > UploadFrequently asked questions
Does it work with any SSH server or only specific configurations?
It should work with any standard OpenSSH server that accepts password authentication. Configurations that enforce key-only auth or require multi-factor authentication will block the connection in the current version.
Do I need the M5Stack Cardputer specifically, or will another ESP32 work?
The code uses the M5Cardputer library for the display and keyboard. Porting to other ESP32 hardware would require replacing those I/O layers — feasible, but not a drop-in replacement.
Does the project support SSH key authentication?
Not in the current version. The roadmap indicates continuous improvements, but key-based auth on embedded devices requires careful handling of private key storage in flash.
What is the compiled binary size?
Not documented in the README, but similar projects with mbedTLS and M5Stack typically land between 800 KB and 1.2 MB of flash. The Cardputer has 8 MB of flash, so it is not a practical constraint.
Who this project is for
This repository is useful for three profiles: makers and IoT enthusiasts who want to explore what the Cardputer can do beyond demos; embedded engineers who need a starting point for SSH on ESP32 with a physical keyboard; and technical recruiters who want to see how I work at lower layers of the stack, outside the cloud context. It is not a replacement for a production SSH client on a laptop — the small screen and absence of key-based auth make that clear. But as a field debugging tool for reaching a Raspberry Pi or an edge server without carrying a notebook, it does exactly what it claims.