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

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:

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

> set gpio 4

For multiple channels, use comma-separated pin numbers:

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

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

> sniff 1024

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

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

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	Core GPIO setup, hardware timer configuration, and circular buffer management for high-speed sampling
src/commands/SniffCommand.cpp	Command parser for sniff arguments and output formatting
platformio.ini	Build environment and default pin mappings
web-tools/web-serial-terminal/	Browser-based terminal implementation
README.md	High-level documentation of logic analyzer capabilities

These files are located in the 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
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}