esp-pal 0.1.0

ESP32 development tool with daemon-based serial port sharing

ESPal - ESP32 Development Tool

ESPal is a daemon-based tool for ESP32 development that solves the serial port sharing problem between monitoring and firmware uploads.

The Problem

When developing for ESP32, the serial port is used for both:

• Monitoring - viewing debug output from your device
• Uploading - flashing new firmware

These operations conflict because only one process can hold the port at a time. ESPal solves this with a daemon architecture where:

• A daemon continuously monitors the serial port
• Data is cached in a ring buffer (50MB default)
• Multiple clients can read simultaneously
• Build/upload operations coordinate port access automatically

Features

• Daemon Architecture - Background daemon owns the serial port
• Ring Buffer - Cached output survives uploads, can replay "since last upload"
• Multiple Clients - User and AI assistants can monitor simultaneously
• Auto-spawn - Daemon starts automatically when needed
• VID:PID Detection - Track devices by USB ID, not port number
• Build Integration - PlatformIO, Arduino CLI, and ESP-IDF support
• Idle Shutdown - Daemon auto-exits after 30 minutes idle

Installation

Using pipx (recommended)

pipx install espal

Using pip

pip install espal

From source

git clone https://github.com/appositeit/espal.git
cd espal
pip install -e .

Requirements

• Python 3.10+
• Linux or macOS (uses Unix sockets)

Quick Start

# List available ESP32 devices
espal list

# Start monitoring (daemon starts automatically)
espal monitor

# Build and upload (daemon releases port automatically)
espal run

# Check daemon status
espal status

# Stop daemon
espal daemon stop

Usage

Monitor Commands

# Live monitoring (default)
espal monitor

# Monitor from last upload marker
espal monitor --since-upload

# Start with last N lines from buffer
espal monitor --tail 100

# Replay buffer and exit (no live monitoring)
espal monitor --replay

# Use legacy direct serial mode (no daemon)
espal monitor --legacy

Build Commands

# Build project
espal build

# Upload firmware
espal upload

# Build and upload
espal run

# Clean project
espal clean

Daemon Commands

# Show daemon status
espal status

# Stop the daemon
espal daemon stop

Device Selection

# Specify device manually
espal -d /dev/ttyUSB0 monitor

# Set baudrate
espal -b 115200 monitor

# Specify project directory
espal -p /path/to/project build

# Use USB VID:PID for device detection
espal --vidpid 10c4:ea60 monitor

# Or separate VID and PID
espal --vid 10c4 --pid ea60 monitor

Build System Integration

# PlatformIO
espal platformio esp32dev build
espal platformio esp32dev upload

# Arduino CLI
espal arduino esp32:esp32:esp32doit-devkit-v1 build

# ESP-IDF
espal espidf build
espal espidf flash

Configuration

PlatformIO

Add VID/PID to your platformio.ini:

[env:esp32dev]
platform = espressif32
board = esp32dev
monitor_speed = 115200
upload_vidpid = 10c4:ea60

Common ESP32 VID:PID Values

Chip	VID:PID
Silicon Labs CP2102	10c4:ea60
CH340	1a86:7523
FTDI FT232	0403:6001
Espressif USB JTAG	303a:1001

Finding Your Device's VID:PID

# Interactive discovery (recommended)
espal discover

# List devices with details
espal list

Architecture

ESPal uses a daemon-client architecture:

┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   Daemon    │────▶ Serial Port
│  (espal)    │     │  (espal.d)  │
└─────────────┘     └─────────────┘
                          │
┌─────────────┐           │
│  AI Client  │───────────┘
└─────────────┘

• Daemon - Owns serial port, manages ring buffer, coordinates builds
• Clients - Connect via Unix socket, subscribe to data stream
• Ring Buffer - 50MB default, stores timestamped data with markers

Data Flow

1. Daemon continuously reads from serial port
2. Data stored in ring buffer with timestamps
3. Markers inserted at key events (upload_start, upload_complete)
4. Clients subscribe and receive data in real-time
5. Clients can request replay from any marker

Development

# Run tests
pytest tests/ -v

# Run specific test file
pytest tests/test_buffer.py -v

License

MIT License - see LICENSE for details.