esp-pal 0.1.1

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 esp-pal

Using pip

pip install esp-pal

From source

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

Requirements

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

Quick Start

# List available ESP32 devices
esppal list

# Start monitoring (daemon starts automatically)
esppal monitor

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

# Check daemon status
esppal status

# Stop daemon
esppal daemon stop

Usage

Monitor Commands

# Live monitoring (default)
esppal monitor

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

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

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

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

Build Commands

# Build project
esppal build

# Upload firmware
esppal upload

# Build and upload
esppal run

# Clean project
esppal clean

Daemon Commands

# Show daemon status
esppal status

# Stop the daemon
esppal daemon stop

Device Selection

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

# Set baudrate
esppal -b 115200 monitor

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

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

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

Build System Integration

# PlatformIO
esppal platformio esp32dev build
esppal platformio esp32dev upload

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

# ESP-IDF
esppal espidf build
esppal 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)
esppal discover

# List devices with details
esppal list

Architecture

ESPal uses a daemon-client architecture:

┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   Daemon    │────▶ Serial Port
│  (esppal)    │     │  (esppal.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.