J-Link debugging

Use a SEGGER J-Link to program a debug build, or attach to running firmware, and then inspect it in Debug mode. Your installed SEGGER software decides which targets are supported. A board appearing in Embedder’s catalog doesn’t establish J-Link compatibility, so verify the exact MCU and probe combination.

Prepare the host and board

Install the SEGGER J-Link Software for your host. It includes J-Link GDB Server.
Connect the probe to the board’s debug connector with the correct signal wiring, ground, and target voltage reference. Power the board.
Build an ELF with debug symbols. To attach to an existing run, use the ELF that matches the firmware on the board.
Find the exact SEGGER device name and whether the board uses SWD or JTAG.
Close other applications that hold the probe.

Embedder downloads its own GDB client on Windows x64, macOS, and Linux x64 or Arm64. On Linux it needs glibc 2.28 or later. You only install the SEGGER software. Embedder finds J-Link GDB Server on PATH or in SEGGER’s default folders:

Host	Default folders
macOS	`/Applications/SEGGER/JLink`
Linux	`/opt/SEGGER/JLink`, `/usr/bin`
Windows	`JLink` or a versioned `JLink_…` folder under `C:\Program Files\SEGGER` or `C:\Program Files (x86)\SEGGER`, or the folder recorded by the SEGGER installer

In Debug mode, if a J-Link probe is connected but the software isn’t found, Embedder shows J-Link Software Required. Install the software, then choose I’ve installed it, retry detection. Continue without J-Link carries on without J-Link debugging.

Record the device

The device name must match an entry in your installed SEGGER device list. A board name or a nearby MCU name isn’t a substitute. In VS Code, select an RTT port in the Embedder Monitor: its Device picker lists the names from your installed J-Link software, and you can filter it with Search device…. In EMBEDDER.md, set the debug interface and record the exact device name so every chat uses the same target:

Target MCU = STM32F407VG
Debug Interface = jlink

Ask Embedder to check J-Link readiness and list the detected probes before connecting.

Start a debug run

Switch to Debug mode with /debug, then give Embedder the artifact, device name, and interface:

Use the connected J-Link and the exact SEGGER device name recorded in
EMBEDDER.md. Program build/app.elf over SWD, run to main, then show the
current frame and registers. Report the selected device before starting.

Replace build/app.elf and the interface with your project’s values. Embedder asks you to approve before it connects, unless your approval settings already allow it. A normal connection programs the ELF and tries to stop at main. If main isn’t reached within about 5 seconds, Embedder halts the target where it is, so check the reported stop location. You can then ask for breakpoints, stepping, stack frames, variables, registers, or memory. See GDB debugging.

Attach to existing firmware

The normal connection programs the ELF. Ask for attach-only to load symbols without programming or running to main. Ask for no halt as well if the target should keep running.

Attach through J-Link using build/app.elf for symbols only. Do not program
or run to main. Check whether this target setup permits no-reset, no-halt
attachment before connecting; preserve the current fault state.

Turning off run-to-main alone still programs the target. Asking for no halt on a programming connection makes Embedder reset and halt the target after loading the ELF. Follow the attachment precautions, because probe startup can still affect execution.

Script a J-Link connection

For a repeatable check, save a hardware script under .embedder/hardware/:

gdb.jlink_connect(
    device="STM32F407VG",
    elf="build/app.elf",
    interface="SWD",
    run_to_main=True,
)
print(gdb.stack())
print(gdb.read_registers())

Replace the device and artifact with your own, then ask Embedder to run it. This example programs the target. The debugger connection closes when the script ends.

Option	Default	Effect
`device`	Required	Exact SEGGER device name
`elf`	Required	Firmware ELF with symbols
`interface`	`"SWD"`	`"SWD"` or `"JTAG"`
`run_to_main`	`True`	Run to `main` after programming
`attach`	`False`	Load symbols only, without programming
`no_halt`	`False`	Don’t request a halt when connecting
`enable_rtt`	`True`	Start RTT alongside the debugger

Use RTT for firmware output through J-Link. A J-Link debug connection starts RTT by default, but the firmware must provide RTT channels. Starting a J-Link debug session takes over the probe:

An RTT session that uses the probe is released.
Any J-Link GDB Server already running on this computer is closed, including one started by another tool.

When you’re finished, tell Embedder whether to leave the firmware running or halted, then disconnect. Stop competing sessions before starting another probe operation.

Troubleshoot

J-Link Software Required, or JLinkGDBServer not found: install the full SEGGER package. If you installed it outside the default folders, add its folder to PATH and restart VS Code or the terminal running Embedder.
Unknown device: check the exact SEGGER name and whether your installed package supports it.
Target voltage too low: the board isn’t powered or the voltage reference isn’t connected.
Connection times out: the probe responds but the target doesn’t. Check target power and SWD or JTAG wiring.
Cannot connect: check target power, voltage reference, wiring, the SWD or JTAG choice, and competing probe users.
Wrong source or missing variables: use matching symbols and check optimization settings.
Run-to-main fails: verify the entry path and the main symbol, then inspect the actual stop reason before continuing.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

Prepare the host and board

Record the device

Start a debug run

Attach to existing firmware

Script a J-Link connection

Troubleshoot

​Prepare the host and board

​Record the device

​Start a debug run

​Attach to existing firmware

​Script a J-Link connection

​RTT and probe sharing

​Troubleshoot

Prepare the host and board

Record the device

Start a debug run

Attach to existing firmware

Script a J-Link connection

RTT and probe sharing

Troubleshoot