OSHW-XIAO-Debug-Mate

🔧 XIAO Debug Mate

An Open-Source ESP32-S3 Multi-Tool for Embedded System Debugging

🐞 DAPLink Debugger | 📡 UART Monitor | ⚡ Power Profiler | 🖥️ Visual Feedback

Features • Hardware • Getting Started • Project Structure • License

---

📖 Introduction

Seeed Studio XIAO Debug Mate is an open-source ESP32-S3 multi-tool that simplifies embedded system debugging with visual feedback. This all-in-one device features a standalone 2.01 inch TFT LCD display, LED status matrix, and native Seeed Studio XIAO support, delivering essential debugging functions: DAPLink chip-level debugging, built-in serial monitoring with UART passthrough, and accurate power consumption measurement. Plug-and-play design eliminates complex wiring for streamlined development.

✨ Features

🛠️ 3-in-1 Professional Development Tool

Feature	Description
🐞 DAPLink-Compatible SWD Interface	Powered by ESP32-S3 with full OpenOCD/PyOCD support, delivering professional-grade debugging capabilities. Set breakpoints, step through code, inspect memory, and access low-level hardware operations with precision.
📡 Intelligent Serial Monitor & UART Passthrough	Monitor communications between your XIAO and the Debug Mate, or between the Debug Mate and external UART devices (Arduino, Raspberry Pi, Grove sensors). View real-time serial data on the onboard display or redirect to PC for detailed analysis.
⚡ Precision Power Profiling	Track power consumption down to μA levels. Monitor voltage/current readings, ultra-low-power states, and consumption patterns with peak/valley identification. Factory-calibrated for maximum accuracy (±10% @ 1-10μA).

🖥️ Standalone Visual Feedback System

Monitor key system metrics without connecting to a PC. The integrated 2.01" LCD screen displays real-time serial communications, power consumption readings, and UART data streams, while the programmable 36-LED matrix provides instant baud rate indicators. Perfect for on-site field testing, mobile development, and quick system power consumption checks.

🔌 Open-Source Platform with Universal Compatibility

Purpose-built for the Seeed Studio XIAO ecosystem with direct plug-and-play connection—any pre-soldered XIAO board connects instantly without tedious wiring. The thoughtfully designed pin headers and sockets transform the device into a specialized expansion breadboard for XIAO development. While optimized for XIAO, the open-source design extends compatibility to any ARM Cortex-M microcontroller via standard SWD and UART interfaces.

📋 Specifications

Parameter	Description
Processor	Espressif ESP32-S3
Power Input	USB-C 5V/1A
Display	2.01 inch TFT LCD (240 × 296 resolution)
LED	36-LED Matrix for Status Indication (Default: Baud Rate)
User Input	1 × User Button/Boot Button, 1 × Scroll Wheel, 1 × Recessed Reset Button
I/O Interface	14 × XIAO Standard Pins, 8 × Expansion Pins, 4 × SWD Debugging Pins, 1 × UART Grove Connector
Product Size	100 × 56 × 20 mm
Software	Supports DAPLink for debugging
Enclosure	3D-Printed in Black PLA

🎯 Supported Target Boards

Board	Interface	Status
🟢 XIAO SAMD21	SWD	✅ Supported
🟢 XIAO RA4M1	SWD	✅ Supported
🟢 XIAO nRF52840 (Sense)	SWD	✅ Supported
🟢 XIAO RP2040	SWD	✅ Supported
🟢 XIAO RP2350	SWD	✅ Supported
🟢 XIAO MG24 (Sense)	SWD (OpenOCD)	✅ Supported

⚠️ Note: XIAO nRF54L15 and XIAO ESP32 series (C3/S3/C6) do not currently support debugging feature.

🚀 Getting Started

⚡ Quick Flash (Recommended for Users)

If you just want to use the XIAO Debug Mate, flash the pre-compiled firmware:

1. Install esptool: pip install esptool
2. Connect XIAO Debug Mate via USB-C
3. Enter download mode (hold BOOT, press RESET)
4. Run the flash script:

OS	How to Run
🍎 macOS	Open Terminal, navigate to 5_Release_firmware/, run ./flash.sh
🐧 Linux	Open Terminal, navigate to 5_Release_firmware/, run ./flash.sh
🪟 Windows	Double-click flash.bat

# macOS / Linux
cd 5_Release_firmware
./flash.sh

The script automatically detects and flashes the latest firmware version!

---

🛠️ Build from Source (For Developers)

Prerequisites

• Arduino IDE 2.x or later
• ESP32 Board Support (version 3.1.3, installed via Arduino Board Manager)
• USB-C Cable for programming

Quick Start

1️⃣ Clone the Repository

git clone https://github.com/Seeed-Studio/OSHW-XIAO-Debug-Mate.git
cd OSHW-XIAO-Debug-Mate

2️⃣ Install Libraries

Copy all libraries from 1_Libraries/ and the firmware library to your Arduino libraries folder:

# macOS / Linux
cp -r 1_Libraries/* ~/Documents/Arduino/libraries/
cp -r 0_Firmware ~/Documents/Arduino/libraries/Seeed_Debugger

# Windows
xcopy /E /I 1_Libraries\* "%USERPROFILE%\Documents\Arduino\libraries\"
xcopy /E /I 0_Firmware "%USERPROFILE%\Documents\Arduino\libraries\Seeed_Debugger"

⚠️ Important: The firmware must be installed as an Arduino library to compile correctly.

3️⃣ Modify ESP32 Core Files

⚠️ Important: You must modify the ESP32 Arduino core files to disable default USB initialization, otherwise TinyUSB will conflict with the default USB stack.

Locate the ESP32 core files:

OS	Path
🍎 macOS	~/Library/Arduino15/packages/esp32/hardware/esp32/3.1.3/cores/esp32/
🪟 Windows	%LOCALAPPDATA%\Arduino15\packages\esp32\hardware\esp32\3.1.3\cores\esp32\
🐧 Linux	~/.arduino15/packages/esp32/hardware/esp32/3.1.3/cores/esp32/

Modify the following 3 files:

File 1: USB.cpp (around line 352)

// Before:
ESPUSB USB;

// After:
// ESPUSB USB;

File 2: USB.h (around line 119)

// Before:
extern ESPUSB USB;

// After:
// extern ESPUSB USB;

File 3: main.cpp (around lines 98 and 101)

// Before:
#if ARDUINO_USB_DFU_ON_BOOT && !ARDUINO_USB_MODE
    USB.enableDFU();
#endif
#if ARDUINO_USB_ON_BOOT && !ARDUINO_USB_MODE
    USB.begin();
#endif

// After:
#if ARDUINO_USB_DFU_ON_BOOT && !ARDUINO_USB_MODE
    // USB.enableDFU();
#endif
#if ARDUINO_USB_ON_BOOT && !ARDUINO_USB_MODE
    // USB.begin();
#endif

4️⃣ Configure Arduino IDE

Set the following options in Arduino IDE:

• Board: “XIAO ESP32S3”
• Partition Scheme: “Maximum APP (7.9MB APP No OTA/No FS)”
• PSRAM: “OPI PSRAM”
• USB Mode: “USB-OTG (TinyUSB)”

5️⃣ Upload Firmware

• Go to File → Examples → Seeed All-in-one Debugger → main
• Or open 0_Firmware/examples/main/main.ino directly
• Click Upload

📁 Project Structure

OSHW-XIAO-Debug-Mate/
├── 📂 0_Firmware/           # 🔧 Main firmware source code
│   ├── examples/            # Arduino sketch entry point
│   └── src/                 # Core library source files
│
├── 📂 1_Libraries/          # 📚 Required Arduino libraries
│   ├── Adafruit_BusIO/      # I2C/SPI communication
│   ├── Adafruit_INA228/     # Power monitoring sensor
│   ├── Adafruit_TinyUSB/    # USB device support
│   ├── lvgl_debug_mate/     # LVGL graphics library
│   ├── Seeed_Arduino_DAPLink/  # DAPLink implementation
│   ├── TFT_eSPI_Debug_Mate/ # TFT display driver
│   └── ...                  # Other supporting libraries
│
├── 📂 2_DAPLink_Package/    # 🎯 DAPLink tools and examples
│   ├── examples/            # Pre-compiled test binaries
│   ├── target/              # OpenOCD target configurations
│   └── XIAO_MG24_*/         # OpenOCD for MG24 debugging
│
├── 📂 3_Product_housing/    # 🏠 3D printable enclosure
│   └── *.stp, *.3mf         # CAD files for housing
│
├── 📂 4_Hardware/           # ⚡ Hardware documentation
│   └── *.pdf                # Schematic diagrams
│
└── 📂 5_Release_firmware/   # 📦 Pre-compiled firmware binaries
    ├── firmware-v*.bin      # Ready-to-flash firmware
    ├── flash.sh             # One-click flash (macOS/Linux)
    └── flash.bat            # One-click flash (Windows)

🖥️ User Interface

The XIAO Debug Mate features an intuitive menu system:

┌─────────────────────────────────┐
│         🏠 Main Menu            │
├─────────────────────────────────┤
│  📡  Function UART              │
│  ⚡  Function Power             │
└─────────────────────────────────┘

Navigation

• 🔄 Scroll Wheel - Navigate menu items
• 👆 Press - Select/Confirm
• 👆 Long Press - Back/Exit

⚙️ Configuration

Baud Rate Options

The UART bridge supports multiple baud rates:

• 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600

Power Monitoring

• Accuracy: ±10% @ 1-10μA (factory-calibrated)
• Current Range: μA to mA level precision
• Features: Peak/valley identification, real-time monitoring

🔗 Resources

• 🛒 Buy at Seeed Studio
• 🛒 Buy at AliExpress
• 📖 Wiki Documentation
• 💻 GitHub Repository

🤝 Contributing

We welcome contributions! Please feel free to:

• 🐛 Report bugs
• 💡 Suggest new features
• 🔧 Submit pull requests
• 📖 Improve documentation

📄 License

This project is open-source hardware (OSHW). See individual library directories for their specific licenses.

🙏 Acknowledgments

This product started with a simple GitHub discussion back in July 2024, where one of our XIAO Core users rei-vilo opened Discussion #20 in our XIAO Open Roadmap with an observation that resonated with many developers: “A programmer-debugger probe is a very useful and ‘must have’ tool for embedded system development. Today, there is no affordable offer.” Then we started the journey of creating this device together with many other community members who contributed a lot of input. Thank you to everyone who contributed ideas and feedback throughout this journey. A special big shout-out to rei-vilo, Chris, PJ, Hendra, Ernesto, Benjamin, Pete, NitekryDPaul for insightful feedback during v0.1 testing.

• Seeed Studio - Hardware design and development
• LVGL - Graphics library
• Adafruit - Various Arduino libraries
• ARM - CMSIS-DAP protocol
• 啊猫啊狗晒太阳 - Design inspiration for the LED matrix

---

Made with ❤️ by Seeed Studio

_{🌟 Star us on GitHub — it motivates us a lot!}