Metadata-Version: 2.4
Name: esp-pal
Version: 0.1.0
Summary: ESP32 development tool with daemon-based serial port sharing
Home-page: https://github.com/yourusername/espal
Author: ESPal Developers
Author-email: Jenna Nelson <jem@apposite.com.au>
License-Expression: MIT
Project-URL: Homepage, https://github.com/appositeit/espal
Project-URL: Repository, https://github.com/appositeit/espal
Project-URL: Issues, https://github.com/appositeit/espal/issues
Keywords: esp32,embedded,serial,platformio,arduino,esp-idf,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Requires-Dist: pyyaml>=5.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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)

```bash
pipx install espal
```

### Using pip

```bash
pip install espal
```

### From source

```bash
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

```bash
# 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

```bash
# 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

```bash
# Build project
espal build

# Upload firmware
espal upload

# Build and upload
espal run

# Clean project
espal clean
```

### Daemon Commands

```bash
# Show daemon status
espal status

# Stop the daemon
espal daemon stop
```

### Device Selection

```bash
# 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

```bash
# 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`:

```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

```bash
# 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

```bash
# Run tests
pytest tests/ -v

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

## License

MIT License - see [LICENSE](LICENSE) for details.
