# How to Use the ESP32-Bit-Pirate as a Logic Analyzer: Complete Setup and Capture Guide

> Learn to use the ESP32-Bit-Pirate as a logic analyzer. Capture digital signals at 2 MS/s with simple commands. Full setup and capture guide.

- Repository: [Geo/ESP32-Bit-Pirate](https://github.com/geo-tp/ESP32-Bit-Pirate)
- Tags: how-to-guide
- Published: 2026-08-02

---

**You can use the ESP32-Bit-Pirate as a logic analyzer by entering DIO mode with `mode dio`, configuring target GPIO pins with `set gpio`, and running the `sniff` command to capture timestamped digital edges at up to 2 MS/s.**

The ESP32-Bit-Pirate firmware transforms an ESP32-S3 into a capable logic analyzer for debugging digital signals. Built on the **DIO** (digital I/O) subsystem, this mode leverages the ESP32-S3's high-resolution hardware timer to capture and stream edge transitions with microsecond precision. This guide walks through the complete workflow—from firmware flashing to interpreting captured data.

## Entering Logic Analyzer Mode

The ESP32-Bit-Pirate implements logic analyzer functionality through dedicated source files that handle GPIO configuration and capture control.

To activate the mode:

```text
> mode dio

```

This command switches the device into digital I/O operation, enabling the **sniff** functionality that powers the logic analyzer. Internally, [`src/modes/DIO.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/modes/DIO.cpp) configures the selected pins as fast GPIO inputs and initializes the circular buffer that stores samples during capture.

## Configuring Capture Parameters

Before capturing data, specify which pins to monitor and how many samples to collect.

### Select Target GPIOs

```text
> set gpio 4

```

For multiple channels, use comma-separated pin numbers:

```text
> set gpio 4,5,6,7

```

The firmware supports monitoring **up to 8 GPIOs simultaneously**, limited by available RAM on the ESP32-S3.

### Set Sample Count and Rate

Control capture duration and timing precision with the `sniff` command options:

```text
> sniff 1024              # 1024 edge transitions, default rate

> sniff -s 2048 -r 1000000  # 2048 samples at 1 MS/s

```

The `-s` flag sets the sample count; `-r` specifies the sampling rate in Hz. With the 240 MHz ESP32-S3 core, reliable capture reaches approximately **2 MS/s** across all configured channels.

## Running the Capture

Execute the logic analyzer capture and receive timestamped output:

```text
> sniff 1024

```

The firmware streams a CSV-formatted edge list to the terminal:

```text
#time_us,level
0,0
12,1
27,0
40,1
...

```

Each row contains:
- **time_us**: Microsecond timestamp from the hardware timer
- **level**: Digital state (0 or 1) at that edge

The [`src/commands/SniffCommand.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/commands/SniffCommand.cpp) file handles argument parsing, initiates the capture through the DIO subsystem, and formats results for host consumption.

## Accessing the Web-Based CLI

The ESP32-Bit-Pirate provides a browser-based terminal that eliminates the need for separate serial software.

1. Navigate to `https://geo-tp.github.io/ESP32-Bit-Pirate/web-tools/web-serial-terminal/`
2. Click **Connect** and select your ESP32-S3 device
3. Run the same `mode dio`, `set gpio`, and `sniff` commands
4. Use the **Download CSV** button to save capture data directly

This interface, located in `web-tools/web-serial-terminal/`, runs entirely in the browser using the Web Serial API.

## Automating Captures with Python

For programmatic control or integration with analysis pipelines, script the capture process:

```python
import serial, csv

ser = serial.Serial('/dev/ttyUSB0', 115200, timeout=1)

# Enter logic analyzer mode

ser.write(b'mode dio\r')
ser.write(b'set gpio 4\r')

# Start capture

ser.write(b'sniff 1024\r')

# Stream results to CSV

with open('logic.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerow(['time_us', 'level'])
    
    while True:
        line = ser.readline().decode().strip()
        
        if line.startswith('#') or not line:
            continue
        if line.startswith('>'):      # End-of-capture marker

            break
            
        writer.writerow(line.split(','))

```

This script configures single-pin capture, receives the timestamped stream, and terminates when the firmware sends the prompt character (`>`).

## Analyzing Captured Data

The raw CSV output integrates with external tools for visualization and protocol decoding. **PulseView** (part of the Sigrok project) accepts the timestamped format for rendering waveforms and applying protocol analyzers.

To import into PulseView:
1. Save the CSV output with proper headers
2. Use PulseView's import feature to specify time and value columns
3. Apply decoders for SPI, I2C, UART, or custom protocols

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`src/modes/DIO.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/modes/DIO.cpp) | Core GPIO setup, hardware timer configuration, and circular buffer management for high-speed sampling |
| [`src/commands/SniffCommand.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/commands/SniffCommand.cpp) | Command parser for `sniff` arguments and output formatting |
| [`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini) | Build environment and default pin mappings |
| `web-tools/web-serial-terminal/` | Browser-based terminal implementation |
| [`README.md`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/README.md) | High-level documentation of logic analyzer capabilities |

These files are located in the [geo-tp/ESP32-Bit-Pirate](https://github.com/geo-tp/ESP32-Bit-Pirate) repository under the `pioarduino` branch.

## Performance Characteristics

The ESP32-Bit-Pirate logic analyzer achieves practical limits based on hardware constraints:

- **Maximum sampling rate**: ~2 MS/s
- **Channel count**: Up to 8 GPIOs (RAM-dependent)
- **Timer resolution**: Microsecond timestamps via ESP32-S3 hardware timer
- **Buffer**: Circular buffer in RAM, streamed to host during capture

These specifications suit debugging serial protocols, button debouncing, and moderate-speed digital interfaces.

## Summary

- **Use `mode dio`** to activate the logic analyzer subsystem implemented in [`src/modes/DIO.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/modes/DIO.cpp)
- **Configure pins with `set gpio`** before starting capture
- **Run `sniff [count]`** to record timestamped edges; add `-r [hz]` for rate control
- **Access via serial terminal or web CLI** at `geo-tp.github.io/ESP32-Bit-Pirate/web-tools/web-serial-terminal/`
- **Export to CSV** for analysis in PulseView or custom scripts
- **Source code**: Examine [`src/commands/SniffCommand.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/commands/SniffCommand.cpp) for command handling details

## Frequently Asked Questions

### What GPIO pins can I use with the ESP32-Bit-Pirate logic analyzer?

Any available GPIO on your ESP32-S3 board works for capture. The [`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini) file defines default pin mappings, and you specify targets dynamically with `set gpio`. Avoid pins reserved for USB, flash, or other critical functions.

### How fast can the ESP32-Bit-Pirate sample digital signals?

The firmware achieves approximately **2 megasamples per second** across all active channels. This limit stems from the ESP32-S3's 240 MHz CPU and the overhead of timestamping edges with the high-resolution timer. For higher rates, consider dedicated logic analyzers.

### Can I capture more than one signal at a time?

Yes. Configure multiple pins with `set gpio 4,5,6` to monitor up to **8 channels simultaneously**. The sample rate remains constant across all channels, and RAM availability determines the maximum practical channel count.

### How do I visualize the captured waveforms?

The terminal displays raw CSV data. For graphical analysis, import the CSV into **PulseView** or write a Python script using matplotlib. The web-based terminal includes a **Download CSV** button to streamline this workflow.