M5Cardputer-SSHClient

This repository is an experiment, not a product. The question it answers is not "can SSH run on a microcontroller?" — it's "how much of a usable terminal fits in 8 MB of flash, 240×135 pixels, and a keyboard the size of a credit card?".

The M5Cardputer is an M5Stack device built around the StampS3 module: an ESP32-S3 with 2.4 GHz Wi-Fi, a physical keyboard, a colour IPS screen, a microSD slot and a small battery. It's the only off-the-shelf hardware in that price range that combines real text input with a radio and a display in a body that fits in a pocket. That makes it the natural candidate for a tool I always missed in the homelab: something I grab from a drawer, join to the network, and use to run a systemctl restart or watch a journalctl -f without pulling out a laptop.

What the project delivers: C++ firmware for the Arduino/ESP32 ecosystem that joins the Cardputer to Wi-Fi, opens an SSH session to a host, and bridges the physical keyboard to the remote terminal, rendering output on the screen. What it does not deliver: full terminal emulation, multi-session management, or any security guarantee beyond what the SSH library provides. It's embedded/IoT portfolio material, published to show the decisions — and the limits — of bringing a cryptographic protocol to an MCU.

The firmware has four responsibilities, and each one has a cost that shows up in the hardware.

Networking: the ESP32-S3 brings up Wi-Fi via Espressif's Arduino core and opens a TCP socket to the host. Nothing new here — the heavy lifting is done by the lwIP stack shipped with the SDK.

Protocol: SSH is the expensive part. Key exchange, symmetric cipher and MAC run in software, and that's what decides whether the session opens in seconds or in tens of seconds. An SSH client in the ESP32 ecosystem relies on an Arduino port of an SSH library; that library's binary size and RAM footprint are the project's main constraint, and that's why the target board matters: the StampS3 has PSRAM, and without it the session simply doesn't fit.

Input: the Cardputer keyboard is not USB HID — it's a matrix read by M5Stack's library. The firmware has to translate a physical key into a terminal byte, including modifier combinations the keyboard lacks a dedicated key for. The mapping is the most hand-crafted part of the code.

Output: the screen is 240×135 pixels. With a legible font that yields somewhere between 40 and 50 columns by 10 to 15 rows — less than a vt100 at 80×24. The renderer keeps a line buffer and redraws what changed; it does not interpret full escape sequences, so full-screen programs like htop or vim degrade. One-line commands and streaming logs work well.

The practical lesson behind this: the bottleneck of an embedded SSH client isn't the network or the crypto — it's the screen.

Anyone arriving with laptop ssh expectations will be frustrated at three points, and it's better to know beforehand.

Memory: the SSH key exchange allocates tens of KB of heap. On the ESP32-S3 with PSRAM that fits; on variants without PSRAM, or with Bluetooth running at the same time, the connection fails with an allocation error rather than a clear message. If the session drops during the handshake, look at free heap before looking at the network.

Screen: 240×135 pixels. Long output scrolls fast and there is no scrollback. What works is short commands and streaming logs — tail -f, journalctl -f, docker ps. Programs that redraw the whole screen have nowhere to fit.

Keyboard: the keys are small and Ctrl/Alt combinations depend on the map implemented in the firmware. Ctrl+C to interrupt a process is the minimum test worth doing right after flashing.

Battery: with Wi-Fi active and the screen on, runtime is minutes to a few hours, not a day. It's a quick-intervention tool, not a long-session one.

None of these limits is a defect of the project — they are properties of the hardware that the experiment makes visible. The value lies precisely in measuring where the line falls.