Embedded Debugging: UART Logs, JTAG, and Logic Analyzers

Quickstart

If you’re stuck on a board right now, do these in order. They’re the highest-impact “fast wins” and they prevent you from wasting hours on the wrong layer.

Overview

“Embedded Debugging: UART Logs, JTAG, and Logic Analyzers” is really about observability. You want to answer four questions quickly:

• Is the CPU running? (or stuck in reset / brown-out / fault)
• Where is it running? (bootloader, reset handler, main loop, interrupt)
• What is it doing? (state transitions, configuration, errors)
• What are the pins doing? (timing, bus transactions, glitches)

The goal of this post isn’t to turn you into a tool collector. It’s to help you build a workflow: reproduce → observe → isolate → fix → prevent. You’ll also get checklists and “common mistakes” so you can skip the classic traps (wrong UART voltage, missing GND reference, breakpoints breaking timing, and more).

Core concepts

Good debugging is less “try random things” and more “reduce uncertainty”. These concepts help you decide which tool to use, what to measure, and how to avoid self-inflicted chaos.

1) Observability layers

Think of debugging as layers, from cheapest to deepest:

• Firmware-level signals: logs, counters, state flags, “event pins” (a GPIO toggle)
• CPU-level control: halt/step, read registers/memory, breakpoints/watchpoints (JTAG/SWD)
• Board-level truth: what the pins and buses actually do (logic analyzer, scope)

Most “mysterious” issues happen when you assume the wrong layer is trustworthy. Example: you trust a UART log, but the UART driver drops bytes under load. Or you trust a breakpoint, but the watchdog resets because you paused too long.

2) Determinism and “Heisenbugs”

Embedded systems are timing-sensitive. When you debug, you often change timing: breakpoints stall the CPU, logging adds latency, and even a debugger connection can alter power/noise slightly. A Heisenbug is a bug that disappears when observed.

3) UART vs JTAG vs SWD (what they really are)

• UART is a serial communication peripheral. For debugging, it’s a “printf pipe” (one-way or two-way). Cheap, simple, and often good enough.
• JTAG is a multi-wire debug/test interface (common in many MCUs and CPUs). It can control the core and access memory.
• SWD (Serial Wire Debug) is an ARM two-wire alternative to JTAG (SWDIO + SWCLK). It’s what many Cortex-M boards expose.

Practically: treat “JTAG/SWD” as “the debugger port.” Your probe might be ST-LINK, J-Link, CMSIS-DAP, etc. The workflow is similar: connect, halt, inspect, step, set breakpoints/watchpoints.

4) Timing correlation: the “event pin” trick

When you’re using a logic analyzer, add one spare GPIO as a timing marker. Toggle it around the code region you care about. Then you can correlate: code section A → bus transaction B → interrupt C.

Step-by-step

Here’s a practical workflow you can reuse across boards and projects. It’s intentionally tool-agnostic: whether you’re on an ESP32, STM32, AVR, RP2040, or a custom SoC, the pattern holds.

Step 1 — Make the bug reproducible (or simulate it)

Step 2 — Add UART logs that don’t make things worse

UART logging is great until it changes behavior: blocking writes can break real-time code, printing in interrupts can deadlock, and high log volume can flood buffers. The key is to log state transitions and fault breadcrumbs, not everything.

If you’re working bare-metal or on a small RTOS, a simple ring buffer avoids blocking and keeps your system responsive. Here’s a minimal pattern: log into a buffer fast, flush from a safe context (main loop or low-priority task).

<!-- Minimal non-blocking UART logger using a ring buffer (conceptual, adapt to your HAL/SDK) -->
#include <stdint.h>
#include <stdarg.h>
#include <stdio.h>

#define LOG_BUF_SIZE 1024

static volatile uint16_t log_head = 0;
static volatile uint16_t log_tail = 0;
static uint8_t log_buf[LOG_BUF_SIZE];

/* TODO in your project: implement uart_tx_start_if_idle() and uart_can_tx() and uart_tx_byte(). */

static inline uint16_t rb_next(uint16_t i) { return (uint16_t)((i + 1u) % LOG_BUF_SIZE); }

static void rb_push(uint8_t b) {
  uint16_t next = rb_next(log_head);
  if (next == log_tail) {
    /* Buffer full: drop byte (or overwrite oldest). Dropping is safer than blocking. */
    return;
  }
  log_buf[log_head] = b;
  log_head = next;
}

void log_printf(const char* fmt, ...) {
  char tmp[128];
  va_list ap;
  va_start(ap, fmt);
  int n = vsnprintf(tmp, sizeof(tmp), fmt, ap);
  va_end(ap);

  if (n <= 0) return;
  if (n > (int)sizeof(tmp)) n = (int)sizeof(tmp);

  for (int i = 0; i < n; i++) rb_push((uint8_t)tmp[i]);
  rb_push((uint8_t)'\n');

  /* Kick TX if needed (implementation depends on your UART driver/interrupt/DMA). */
  uart_tx_start_if_idle();
}

/* Call from main loop or a low-priority task to flush. */
void log_flush_poll(void) {
  while (log_tail != log_head && uart_can_tx()) {
    uint8_t b = log_buf[log_tail];
    log_tail = rb_next(log_tail);
    uart_tx_byte(b);
  }
}

Step 3 — Use JTAG/SWD for control, not for “guessing”

When you can connect a debugger, you get superpowers: halt the CPU, inspect memory, set breakpoints, and read fault registers. Use it to answer targeted questions:

• Did we reach main()?
• Are interrupts firing?
• What is the stack pointer and where is it pointing?
• Did we hard fault? If yes, what was the fault address?
• Is a variable changing when it shouldn’t? (watchpoint)

Below is a “known-good” baseline workflow with OpenOCD and GDB (common for ARM Cortex-M via SWD). Adapt the target config file to your MCU and probe. The important part is the sequence: connect → reset/halt → verify you can read memory → set breakpoints/watchpoints.

# Terminal 1: start OpenOCD (example flow; adjust interface/target files)
openocd -f interface/cmsis-dap.cfg -f target/stm32f4x.cfg

# Terminal 2: connect with arm-none-eabi-gdb
arm-none-eabi-gdb build/firmware.elf <<'GDB'
target extended-remote :3333
monitor reset halt
# Confirm the CPU is halted and symbols are loaded
info registers
# Break at main and run
break main
continue
# If you suspect a crash, inspect the backtrace
bt
# Watch a variable (or a memory address) for unexpected writes
# (Watchpoints are limited; use them surgically.)
watch some_global_state
continue
GDB

Step 4 — Measure the pins with a logic analyzer

Logic analyzers are unbeatable for digital truth: did the chip select assert? did the I2C address get ACKed? are UART bytes framed correctly? They’re especially powerful when you combine them with firmware markers (an “event pin”) and logs.

Here’s an example using sigrok’s CLI to capture and decode I2C. This is handy when you want to commit captures to a bug report, run the same capture repeatedly, or automate “did it ACK?” checks.

# Example: capture I2C on two channels and decode with sigrok-cli
# - Set the driver to your device (run: sigrok-cli --scan)
# - Adjust samplerate and capture time to your bus speed and debug needs
sigrok-cli -d fx2lafw \
  --config samplerate=24MHz \
  --time 2s \
  -C D0=SCL,D1=SDA \
  -P i2c \
  -O ascii

Once you can see the transaction, debugging becomes concrete: you can spot missing pull-ups, wrong address, clock stretching, bus stuck low, or chip select glitches in minutes.

Step 5 — Close the loop: fix, verify, and prevent regression

Common mistakes

These mistakes show up in almost every embedded project—especially during bring-up. The fixes are usually simple, but you have to recognize the pattern.

FAQ

Do I need JTAG/SWD if I already have UART logs?

Not always. UART logs are often enough for application-level bugs and “did we reach this state?” problems. You need JTAG/SWD when the system crashes before logs, hangs with no output, corrupts memory, or when you must inspect registers/stack to understand faults.

What’s the difference between JTAG and SWD?

They’re both debug interfaces. JTAG uses more pins (a traditional scan chain), while SWD is a two-wire ARM alternative (SWDIO + SWCLK). For many Cortex-M boards, SWD is the default. The tooling and workflow (GDB/OpenOCD, breakpoints, memory inspection) are similar.

Why is my UART output garbled?

Most commonly it’s the wrong baud rate or wrong voltage level. Also check that you share ground, you’re using the correct pin pair, and your UART settings match (8N1 is common). If it’s “mostly readable but sometimes corrupted,” suspect noise, long wires, incorrect clock config, or an overloaded log path dropping bytes.

Why does the debugger connect but can’t halt or flash reliably?

Suspect signal integrity and target state. Lower the SWD/JTAG speed, shorten wires, ensure solid ground, and try connect-under-reset. If the firmware rapidly enters low-power modes or remaps debug pins, it can destabilize the session—especially during bring-up.

Can breakpoints change real-time behavior?

Yes—often dramatically. Halting the CPU pauses interrupts, changes DMA timing, and can trigger watchdog resets. If the bug disappears with breakpoints, use event pins + logic analyzer, lightweight logs, counters, and watchpoints instead of stepping.

Logic analyzer vs oscilloscope: which should I buy/use first?

If you mostly debug digital buses (I2C/SPI/UART), start with a logic analyzer. Protocol decode and long captures are huge advantages. If you debug analog issues (power rails, ringing, rise times, brown-outs), you’ll want an oscilloscope. Many teams use both: analyzer for “what bytes and when,” scope for “are the edges/power actually valid.”

How do I find UART pins on an unknown board?

Start with the schematic or silkscreen, then confirm with measurement. Look for labeled headers (TX/RX/GND), debug pads, or test points near the MCU. If documentation is missing, a logic analyzer can help: probe suspect pins during boot and look for a UART-like idle-high waveform, then try decoding at common baud rates.

Cheatsheet

A compact checklist you can keep open while debugging.

Wrap-up

Embedded debugging gets dramatically easier when you stop treating tools as separate “modes” and start treating them as layers of truth: UART logs for cheap state visibility, JTAG/SWD for CPU control and fault inspection, and logic analyzers for timing and bus reality. When you combine them—logs + debugger + waveforms—you turn “it sometimes fails” into a measured sequence you can fix.

If you want to go deeper, the related posts below pair well: wiring/prototyping hygiene, protocol selection (UART/I2C/SPI), and a general debugging checklist that works across software and hardware.

Related posts

• PCB Basics for Software Folks: From Schematic to Board
• Debugging Like a Pro: A Checklist That Actually Works
• ESP32 Starter Guide: GPIO, Wi-Fi, and Real Projects
• Arduino to Prototyping: Sensors, Actuators, and Clean Wiring
• Raspberry Pi as a Home Server: Safe Setup and Use Cases
• UART vs I2C vs SPI: Which Protocol to Use and Why