Debugger · OMEN

Omen debugs firmware on real hardware. It connects to your target through a debug probe, halts the core, and inspects it live.

The GDB binary

Omen needs GDB to debug, and the installer provisions it for you. When you install Omen, it downloads a prebuilt arm-none-eabi-gdb into ~/.omen/tools/. You don't install GDB yourself.

This is the debugger. It understands your firmware's symbols, source lines, and stack, but it does not talk to hardware directly. For that, Omen connects it to a GDB server.

GDB servers

A GDB server drives your physical debug probe and exposes it to GDB. Omen supports two. Install the one your probe needs:

OpenOCD works with most probes (ST-Link, CMSIS-DAP, FTDI, and others).
```
# macOS
brew install open-ocd

# Linux
apt install openocd   # or pacman, etc.
```
On Windows, download the xPack OpenOCD release and unzip it, or install via winget or scoop.
J-Link GDB Server is for SEGGER J-Link probes. Install SEGGER's J-Link Software Pack (free) on any platform. This is proprietary SEGGER software, so Omen can't bundle it. You install it once.

Omen finds these automatically after they're installed. See Locating servers if it doesn't.

The debug-target file

The first time you debug in a project, Omen sets up a target. It asks you a few questions to confirm:

the part number of your chip (for example STM32G474RE or nRF9151),
the debug probe you're using,
the GDB server to drive it (OpenOCD or J-Link).

Omen reads your project first and proposes what it finds. If your build files name the chip, it pre-fills that and asks you to confirm. You always confirm before anything connects.

Your answers are saved to .omen/debug-target.yaml in your project, so you're only asked once. Commit it to share the setup with your team.

targets:
  my-board:
    backend: openocd        # or jlink
    config:
      interface: stlink
      target: stm32g4x
      port: 3333

After that, you debug by name. Tell Omen to debug your board and it brings up the server, connects GDB, and hands you a live session.

Locating servers

Omen searches your PATH and the standard install locations for each server. If you've installed one somewhere non-standard and Omen can't find it, point it directly with an environment variable:

export OMEN_OPENOCD_BIN=/path/to/openocd
export OMEN_JLINK_GDBSERVER_BIN=/path/to/JLinkGDBServerCL

These override all automatic discovery, so whatever you set wins. You can set OMEN_GDB_BIN the same way to use a specific GDB.

If a server isn't found, Omen tells you which one, where it looked, and how to install it.