Skip to content

xiao-ftdi: a USB and BLE serial bridge for the HP T5325

The T5325 port says, in the hardware survey, that “there is no way to attach a serial console.” That was true of the case — the two 16550A ports are on the board but none of them exit it, and video is the only output a human can reach from outside. It is not the whole story. There is a UART header inside the case, and once you open it, a console is very much attachable. This post is about the tool that attaches it: xiao-ftdi.

The code lives at github.com/paigeadelethompson/xiao-ftdi.

What it is

A Seeed XIAO ESP32-C6 running Arduino, flashed with about 200 lines of bridge firmware. It presents itself two ways at once:

  • Over USB, a plain serial adapter: plug it into the board’s USB-C port, and Serial enumerates as a CDC device — 115200 8N1. No USB↔serial bridge chip on this board; the ESP32-C6’s native USB does it.
  • Over Bluetooth LE, a Nordic UART Service (NUS): advertised as BLESerial + the last three bytes of the MAC, e.g. BLESerialfffe21. Service 6e400001-…, write characteristic …0002 (host → board), notify characteristic …0003 (board → host).

Everything received on one side is written to the other two: USB → UART and BLE, UART → USB and BLE, BLE → USB and UART. It does not care about direction because it is a dumb pipe that happens to have two mouths.

Wiring to the T5325 is four wires: TX on the XIAO (GPIO16, D6) to the board RX, RX (GPIO17, D7) to the board TX, ground to ground, 3.3V logic both sides. The bridge side of the header speaks the same 115200 8N1 the ports always spoke.

Why not a plain FTDI cable

Because both work, independently and at the same time. Teethered to a laptop, it is an FTDI cable in every way that matters — cu, minicom, anything serial. Untethered, it is a wireless console: start advertising, walk away, connect from whatever has BLE. For a machine whose whole debugging story is “the only output is the framebuffer and there is no serial port,” having both was the point. The T5325 is not the only headless ARM box on the bench that benefits from that; anything with a 3.3V UART header and no network is fair game.

The honest caveat, because it matters if you copy this: the NUS characteristics are unencrypted and unauthenticated. There is no pairing, no bonding, no PIN — any BLE central in range can connect and write to the console. That is acceptable on a bench with no secrets on the wire and not acceptable anywhere else. It is a debugging tool, not a product.

The firmware, and the parts that bit me

The toolchain is not the stock one. platformio.ini pins the pioarduino fork of platform-espressif32 by GitHub release-zip URL, not the registry platform. The registry release does not ship working Arduino-ESP32 support for the C6; the fork does. Swapping it to “the normal one” because it looks cleaner produces a build that either fails or a board that flashes and goes dark.

USB needs the right flags. ARDUINO_USB_MODE=1 and ARDUINO_USB_CDC_ON_BOOT=1 are what make Serial come up over the built-in USB-C instead of a UART that doesn’t exist on this board. Get them wrong and the flash succeeds and you stare at silence.

The RX buffer size must be set before begin(). Serial1.setRxBufferSize(4096) is a no-op once the driver installs, so the order is load-bearing.

BLE writes are WRITE_NR and notifications chunk at 20 bytes. The write characteristic is WRITE | WRITE_NR — no round trip — and the notify path chunks to 20 bytes because it is safe for the default MTU; BLEDevice::setMTU(512) is requested, but nothing guarantees the central negotiates up. Anything larger needs its own framing. The BLE→UART ring buffer is 512 bytes and drops on full with no error signal — fine for a console that a human is reading, not fine for bulk transfer.

The one LED is active-low, blinks on any bridge traffic, and flashes 3 short + 1 long at boot so you can tell “powered” from “bricked.”

The host side

nus_client.py in the repo is the BLE half of the story: a small asyncio REPL on bleak (pipx install bleak). Scan, pick a device (it defaults to the first BLESerial* match), and you get a raw byte stream — notifications are written to stdout verbatim with no added newlines, because a 20-byte chunk can split a line or a UTF-8 sequence and there is no reassembly layer on the firmware side. Status goes to stderr so stdout stays pipeable. /hex 41 42 0a sends raw bytes; /quit exits; it works piped, and the client tears the connection down cleanly on EOF and Ctrl-C.

Does it work?

Both paths do — the USB side is indistinguishable from a proper FTDI adapter, and the BLE side connects, passes bytes both ways, and re-advertises after a disconnect (a fixed 500 ms later). On the T5325 that closes the gap the port post left open: the machine that could only be debugged through a framebuffer, blind, now has a real console you can reach from a laptop without pulling the side panel every time — and, since it re-advertises on its own, without replugging anything after the inevitable BLE drop.

It is not a polished project. It is the tool that made a port possible, written to be copied rather than browsed — which is why the README and the repo layout say this much and the post doesn’t repeat it.