Metadata-Version: 2.4
Name: mxdbg
Version: 0.3.2
Summary: ESP32-S3 multi-interface debugger host library (I2C / PWM / SPI / GPIO via USB CDC)
Author-email: isletspace <liewzheng@qq.com>
License-Expression: Apache-2.0
Keywords: esp32,debugger,i2c,spi,gpio,pwm,usb-cdc
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Requires-Dist: toml>=0.10
Requires-Dist: loguru>=0.7
Requires-Dist: esptool>=4.0
Provides-Extra: ui
Requires-Dist: streamlit>=1.30; extra == "ui"
Provides-Extra: paw
Requires-Dist: numpy>=1.24; extra == "paw"
Requires-Dist: PySide6>=6.5; extra == "paw"
Dynamic: license-file

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

[中文文档](https://gitlab.islet.space:8443/isletspace/mxdbg/-/blob/master/README.zh.md) · [English Docs](https://gitlab.islet.space:8443/isletspace/mxdbg/-/blob/master/README.en.md) · [Changelog](https://gitlab.islet.space:8443/isletspace/mxdbg/-/blob/master/CHANGELOG.md) · [License: Apache-2.0](https://gitlab.islet.space:8443/isletspace/mxdbg/-/blob/master/LICENSE)

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

```bash
pip install mxdbg
```

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

## Command-Line Interface

```bash
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
mxdbg flash -p COM5 --yes           # Windows: use the COM port
```

- `flash` asks for **confirmation** first (type `y`); `--yes` skips it for scripts
- When **multiple ESP32 devices** are detected, you choose which to flash
- A hint is printed before flashing; if the connection fails, **hold `BOOT` + press `RST`** to enter download mode, then retry
- The device resets after flashing — run `mxdbg info` to reconnect

## Quick Start

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

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

| API | Description |
|---|---|
| `i2c_config` / `i2c_write_read` / `i2c_find_slave` | I2C configuration, read/write, bus scan |
| `spi_config` / `spi_write_read` / `spi_read_image` | SPI configuration, half/full-duplex transfer |
| `gpio_config` / `gpio_write_read` | GPIO mode / pull-up / level |
| `pwm_config` / `pwm_run_stop` | PWM frequency / duty cycle |
| `usb_config` | USB CDC CRC toggle |
| `power_init` / `power_control` | ExtBoard power control |
| `expand_io_init` / `expand_io_config` / `expand_io_write_read` | ExtBoard expand I/O |
| `restart` / `get_extboard_version` | Device reset / ExtBoard version |

## Full Documentation

- [中文文档 (README.zh.md)](https://gitlab.islet.space:8443/isletspace/mxdbg/-/blob/master/README.zh.md)
- [English Docs (README.en.md)](https://gitlab.islet.space:8443/isletspace/mxdbg/-/blob/master/README.en.md)

## License

[Apache-2.0](https://gitlab.islet.space:8443/isletspace/mxdbg/-/blob/master/LICENSE)
