Skip to content

swd-programming.md

Latest commit

 

History

History
125 lines (88 loc) · 6.6 KB

swd-programming.md

File metadata and controls

125 lines (88 loc) · 6.6 KB
description
What SWD is, how it works, what hardware you need, and when to use it.

SWD Programming

What is SWD?

SWD (Serial Wire Debug) is a two-wire debug and programming interface for ARM microcontrollers. It lets you flash firmware, set breakpoints, inspect memory, and access a debug console — all through a physical connection to the chip.

Every ARK product with an STM32 microcontroller exposes SWD through a debug connector. It is the most reliable way to flash firmware and the only way to recover a board with a corrupted bootloader.

How It Works

SWD uses two signals plus ground:

Signal Name Direction Purpose
SWDIO Serial Wire Data I/O Bidirectional Data transfer between debugger and MCU
SWCLK Serial Wire Clock Debugger → MCU Clock signal driven by the debugger
GND Ground — Common reference

The debugger (e.g., ST-LINK) connects to the MCU's internal debug port, giving it direct access to flash memory, registers, and peripherals. This works even if the firmware is completely broken — SWD operates at the hardware level, below any software.

What You Need

  • ST-LINK V3 Mini — programmer/debugger that connects to your computer via USB. The V3 Mini is recommended because it also provides a virtual serial port for UART debug console access through the same USB connection.
  • ARK Pixhawk Debug Adapter — routes the ST-LINK's STDC14 connector to the Pixhawk Standard 6-pin or 10-pin JST-SH debug connector found on ARK boards. Includes debug cables.

The connection chain looks like this:

Computer ↔ USB ↔ ST-LINK V3 Mini ↔ STDC14 Cable ↔ ARK Debug Adapter ↔ JST-SH Cable ↔ Board Debug Port

When to Use SWD

Most firmware updates don't require SWD. The day-to-day methods depend on the type of board:

  • Flight controllers (ARKV6X, ARK FPV, etc.) — firmware is typically loaded via QGroundControl over USB. SWD is not needed for routine updates.
  • DroneCAN nodes (ARK CANnode, ARK Flow, ARK MAG, etc.) — the flight controller pushes firmware from its SD card to the node over the CAN bus, or you can use the DroneCAN GUI Tool directly. This is the normal update path once a bootloader is installed.
  • USB DFU — a fallback used on some boards (like the ARK FPV) to flash a bootloader over USB when the board is placed into DFU mode. Rarely needed.

SWD is for situations where none of the above work:

  • Initial bootloader flash — a brand-new or factory-fresh DroneCAN node has no bootloader. SWD is the only way to install one so the node can accept CAN firmware updates going forward.
  • Recovery — if a bootloader becomes corrupted or a bad firmware flash leaves the board unresponsive, SWD can overwrite flash directly and bring it back.
  • Development and debugging — SWD lets you set breakpoints, step through code, and inspect memory. Not required for firmware development, but useful when you need it.

SWD operates at the hardware level, below any software on the chip. As long as the board is not physically damaged, SWD can recover it — regardless of the state of the bootloader or firmware.

Debug Connector Pinouts

ARK products use one of two Pixhawk Standard Debug Connectors (both JST-SH). The ARK Pixhawk Debug Adapter includes cables for both.

6-Pin Debug Connector

Used on most ARK DroneCAN sensors and smaller boards.

Pin Signal Voltage
1 3.3V 3.3V
2 UART TX 3.3V
3 UART RX 3.3V
4 SWDIO 3.3V
5 SWCLK 3.3V
6 GND GND

10-Pin Debug Connector

Used on flight controllers like the ARKV6X. Adds a second UART and reset line.

Pin Signal Voltage
1 3.3V 3.3V
2 UART5 TX (Debug Console) 3.3V
3 UART5 RX (Debug Console) 3.3V
4 FMU SWDIO 3.3V
5 FMU SWCLK 3.3V
6 SWO 3.3V
7 IO SWDIO 3.3V
8 IO SWCLK 3.3V
9 nRST 3.3V
10 GND GND

Software Setup

Install the stlink tools from source for the most up-to-date version with the best device support:

sudo apt install build-essential cmake libusb-1.0-0-dev
git clone https://github.com/stlink-org/stlink.git
cd stlink
cmake .
make
sudo make install
sudo ldconfig

{% hint style="info" %} Prefer building from source over sudo apt install stlink-tools. The packaged version in most distributions is outdated and may not support newer STM32 chips or ST-LINK firmware versions. See the stlink-org/stlink GitHub page for full build instructions and troubleshooting. {% endhint %}

If you encounter permission errors after installation, add your user to the dialout group:

sudo usermod -aG dialout $USER

Log out and back in for the change to take effect.

Common Pitfalls

  • Skipping the debug adapter — the ST-LINK's STDC14 connector does not directly plug into the JST-SH debug port on ARK boards. You need the ARK Pixhawk Debug Adapter or manual wiring.
  • Wrong bootloader for the firmware stack — PX4 CAN nodes need the PX4 canbootloader, and AP_Periph nodes need the ArduPilot CAN bootloader. Flashing the wrong bootloader means the node won't accept firmware updates over CAN. If a node isn't picking up firmware, check which bootloader is installed.
  • Wrong flash address — STM32 flash typically starts at 0x08000000. Using the wrong address will produce a seemingly successful flash but a non-functional board.
  • Outdated stlink tools — the version from apt install stlink-tools is often too old to recognize newer STM32 chips or ST-LINK firmware. Build from source (see Software Setup above).
  • Powering conflicts — the ST-LINK can supply 3.3V to the target. If the board is already powered externally, this is usually fine, but avoid powering high-current peripherals through the debug connector.

Further Reading