Small serial device harness for embedded boards.

mama owns the real USB serial port in a background daemon, mirrors device output to a PTY for humans, writes a serial log, and exposes a local API for CLI commands.

mama is currently geared toward ESP32 development.

git clone git@github.com:edsammy/mama.git
cd mama
go install ./cmd/mama

This installs mama into Go's bin directory, usually ~/go/bin. Make sure that directory is on your PATH:

export PATH="$HOME/go/bin:$PATH"

mama reads .mama.toml from the current directory. Example for an ESP32-S3 project:

name = "device"
baud = 115200
state_dir = ".mama"
pty_link = "/tmp/mama-device"
port_patterns = ["/dev/cu.usbmodem*", "/dev/tty.usbmodem*"]

ready_pattern = "UART command task started"

[serial_protocol]
enabled = true
line_ending = "\n"
timeout_s = 5
success_patterns = ["OK:"]
error_patterns = ["ERROR:"]
prompt_patterns = []

[tasks]
shell = "zsh"
setup = ". $HOME/esp/esp-idf/export.sh >/dev/null"
build = "idf.py build"
flash = "idf.py -p {port} flash"
flash_verify = "idf.py -p {port} flash --verify"

Prefer explicit success/error markers when the firmware can provide them. prompt_patterns is a fallback for interactive shells that only show a prompt when a command is done.

mama start
mama status
mama status --json
mama send PING
mama reset --wait
mama build
mama flash
mama flash --no-build
mama restart
mama stop

Example:

cd /path/to/firmware
mama start
tio /tmp/mama-device 115200
mama send PING

For human serial viewing, I recommend tio. mama owns the real serial port; tio connects to the PTY link that mama creates.

For name = "device" and state_dir = ".mama":

.mama/
  device.log
  device.daemon.log
  device/
    status.json

device.log is the serial log. status.json is how the CLI finds the daemon API. device.daemon.log captures daemon startup or crash output.