MXDBG

ESP32-S3 multi-interface debugger host library — control I2C / PWM / SPI / GPIO peripherals and flash firmware over USB CDC, with no local ESP-IDF toolchain required.

中文文档 · English Docs · Changelog · License: Apache-2.0

Features

• One-click firmware flashing — bundled firmware binaries, no ESP-IDF / compilation needed
• Interactive safety — confirm before flashing; choose the target when multiple ESP32s are connected
• Multi-bus support — I2C, SPI, GPIO, PWM over the virtual serial port (USB CDC)
• ExtBoard support — v0.1 / v0.2.1 expansion boards (level-shifted I/O, power control, expand I/O)
• Cross-platform — Windows / macOS / Linux
• Hardware — ESP32-S3-Pico

Installation

pip install mxdbg

Python 3.10+. The package bundles prebuilt firmware, so flashing works out of the box.

Command-Line Interface

mxdbg scan                 # list detected ESP32 devices
mxdbg info                 # show connected device version / ExtBoard
mxdbg flash                # flash firmware (confirm, choose device if multiple)
mxdbg flash -p /dev/ttyACM0 --yes   # specify port, skip confirmation

Quick Start

from mxdbg import MXDBG

dev = MXDBG()                      # auto-detect ESP32 and connect
print(dev.version)

# GPIO
dev.gpio_config(pin=33, mode=dev.gpio_mode["GPIO_MODE_OUTPUT"], pull_up=True, pull_down=False)
dev.gpio_write_read(33, 1)         # set pin 33 high

# I2C
dev.i2c_config(freq=100000, port=0)
ret, data = dev.i2c_write_read(slave_id=0x50, write_list=[0x00], read_length=1, port=0)

# SPI
dev.spi_config(freq=1000000, mode=3)
ret, data = dev.spi_write_read([0x01], 1)

# PWM
dev.pwm_config(pin=16, freq=361, duty=0.5, channel=0)
dev.pwm_run_stop(True, channel=0)

Flash Firmware (no ESP-IDF needed)

from mxdbg import MXDBG

dev = MXDBG()
ret, msg = dev.flash_firmware()    # confirm (y/N), choose device if multiple
print(ret, msg)

• Flashing asks for confirmation first; pass confirm=False for scripts
• When multiple ESP32 devices are detected, you choose which to flash
• The serial port is released before flashing; the device resets afterwards — create a new MXDBG() instance before further use
• USB-UART bridges (CH340/FT232/CP2102) and specific devices: MXDBG(port="/dev/ttyUSB0") / flash_firmware(port="...")
• Linux: add your user to the dialout group (sudo usermod -aG dialout $USER, re-login) for serial access

APIs

Full Documentation

• 中文文档 (README.zh.md)
• English Docs (README.en.md)

License

Apache-2.0