How to Choose the Right Zephyr Board Target for Your BLE Hardware

Developer selecting nRF52 development board for Bluetooth Low Energy project with Zephyr RTOS

You’ve installed Zephyr. You’ve cloned the BLE sample. You’ve typed west build with what you’re pretty sure is the right board name. And the terminal spits back:

ERROR: Board "nrf52840dk_nrf52840" not found

You’re staring at the exact string from the tutorial you followed. You copied it character by character. And it doesn’t work.

This isn’t a you problem. Zephyr changed its board target naming convention, and most tutorials, Stack Overflow answers, and even some official examples haven’t caught up. The result is that thousands of embedded developers, people who are perfectly capable of writing firmware, get stuck before they compile a single line of code. The board target is the first thing Zephyr asks you for, and it’s the worst-explained concept in the entire ecosystem.

Here’s how to fix that, permanently.

Why Zephyr Can’t Just Figure Out Your Board

If you’re coming from Arduino, this feels absurd. Arduino auto-detects your board. ESP-IDF has menuconfig and idf.py set-target. The bare-metal Nordic SDK assumes you know your chip and gets out of the way.

Zephyr supports over 700 boards across ARM, RISC-V, x86, ARC, and more. It can’t guess. The board target is the single string that resolves all ambiguity: which SoC you’re using, what pins are wired where, which peripherals exist, and which drivers need to be compiled.

Think of it as a chain reaction:

Board target → SoC definition → devicetree → pin mappings → driver enablement

The board target doesn’t just pick a chip. It describes an entire hardware platform: the crystal frequency, the UART connected to USB, the buttons and LEDs, the flash layout. Two boards using the same nRF52840 SoC can have completely different board targets because their hardware designs differ.

This is actually powerful. But the first time you encounter it, it just feels like a wall.

The Naming Convention That Broke Everyone’s Tutorials

Here’s the source of most build failures for newcomers. Zephyr 3.7 changed the board target format:

Current format (Zephyr 3.7+):

  <board_name>/<soc_name>
  nrf52840dk/nrf52840              ← nRF52840 DK
  nrf52dk/nrf52832                 ← nRF52 DK
  nrf5340dk/nrf5340/cpuapp         ← nRF5340 DK, application core

Old format (pre-3.7, still in most tutorials):

  nrf52840dk_nrf52840              ← underscore instead of slash
  nrf52dk_nrf52832

That’s it. Slash instead of underscore. A one-character difference that produces an incomprehensible error message and sends developers down a thirty-minute debugging rabbit hole.

If you’re using the nRF Connect SDK (NCS) v2.7+, or a recent Zephyr main branch, you need the slash format. If you’re on an older NCS release, you might still need the underscore format. The error message won’t tell you which version you’re running or which format you need. It just says the board wasn’t found.

For boards with multi-core SoCs like the nRF5340, there’s an additional layer: you specify which CPU core you’re targeting. nrf5340dk/nrf5340/cpuapp for the application core, nrf5340dk/nrf5340/cpunet for the network core. If you’re using an nRF52-series board, you don’t need to worry about this.

The fix is simple: check your Zephyr version, use the matching format. But you shouldn’t have to guess. Here’s how to find the exact string.

Three Ways to Find Your Exact Board Target

Method 1: The Zephyr board catalog. Go to docs.zephyrproject.org/latest/boards and search for your board. Each listing shows the exact target string for the current Zephyr version. This is the most reliable source.

Method 2: Your local Zephyr tree. Every supported board has a directory under zephyr/boards/<vendor>/:

zephyr/boards/nordic/nrf52840dk/
├── nrf52840dk_nrf52840.dts        ← devicetree source
├── nrf52840dk_nrf52840_defconfig  ← default Kconfig values
├── board.cmake                    ← flash/debug runner config
├── board.yml                      ← board metadata (has the target string)
└── Kconfig.board                  ← board Kconfig symbol

Open board.yml. The target string is right there.

Method 3: The command line. Run west boards to list every supported board. Pipe it through grep to narrow it down:

west boards | grep nrf52840

If your specific commercial board isn’t listed, say you’re using a third-party module based on the nRF52840, you’ll need to create a custom board definition. That’s a separate topic, but it starts by copying the closest DK’s board directory and modifying the devicetree to match your hardware.

What .overlay and .conf Files Actually Do

Once you get past the board target error, the next confusion hits: what are all these extra files, and do you need them?

Two files matter. Here’s the mental model:

Board Target ──► "Here is the DEFAULT hardware description"
     │
.overlay ──────► "Here are MY project's hardware tweaks"
     │
prj.conf ──────► "Here are the SOFTWARE features I need"
     │
west build ────► Combines all of the above into firmware

prj.conf controls software features through Kconfig. For BLE, this is where you tell Zephyr to compile the Bluetooth stack. It’s a plain text file with key-value pairs:

CONFIG_BT=y
CONFIG_BT_PERIPHERAL=y
CONFIG_BT_DEVICE_NAME="My BLE Device"

No prj.conf, no BLE stack. It’s that direct.

.overlay files modify the hardware description (devicetree) without touching the board’s source files. You use them to reassign pins, enable an I2C sensor, change a UART baud rate, or add a peripheral that exists on your custom board but not on the reference DK.

Here’s the critical thing most guides bury: you do not always need an overlay file. If you’re running a BLE sample on a standard Nordic DK, the board’s default devicetree already describes the hardware correctly. The sample’s prj.conf already enables the right Kconfig options. You can build and flash with zero modifications.

Overlay files become necessary when your project’s hardware deviates from the DK’s defaults, which it will, eventually, but not on day one.

Building Your First BLE Sample With west build

Enough theory. Here’s a concrete, copy-paste-ready sequence for building a BLE heart rate sample on the nRF52840 DK:

# Navigate to the sample
cd zephyr/samples/bluetooth/peripheral_hr

# Build for the nRF52840 DK (Zephyr 3.7+ format)
west build -b nrf52840dk/nrf52840

# Flash to the board (auto-detects J-Link on Nordic DKs)
west flash

If you’re on an older Zephyr or NCS version:

west build -b nrf52840dk_nrf52840

A successful build ends with something like:

[248/248] Linking C executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:      171.5 KB         1 MB     16.78%
             RAM:       44.2 KB       256 KB     16.87%

After west flash, open the nRF Connect mobile app (available on iOS and Android), scan for BLE devices, and look for “Zephyr HR Sensor.” If it shows up, your board target, devicetree, and Kconfig are all correct.

The sample’s prj.conf is already configured for BLE. Here’s what it enables and why:

CONFIG_BT=y                    # Enable the Bluetooth stack
CONFIG_BT_PERIPHERAL=y         # This device advertises (vs. scanning)
CONFIG_BT_DEVICE_NAME="Zephyr HR Sensor"  # Name visible during scan
CONFIG_BT_DIS=y                # Device Information Service
CONFIG_BT_BAS=y                # Battery Service
CONFIG_BT_HRS=y                # Heart Rate Service

Each line maps to a Kconfig symbol that includes or excludes specific source files from the build. No XML, no GUI, no magic. Just a flat text file.

If you’re using the nRF52 DK (the nRF52832 variant), swap the board target:

west build -b nrf52dk/nrf52832

Everything else stays the same.

When the Build Fails: A Quick Diagnostic Checklist

Before you search Discord or file an issue, run through this:

  1. “Board not found” → Check your Zephyr/NCS version and use the matching format (slash vs. underscore). Run west boards | grep <your_board> to see exactly what’s recognized.

  2. Kconfig warnings about undefined symbols → You’re likely using a prj.conf option that requires a dependency you haven’t enabled. Read the warning; it usually names the missing symbol.

  3. Devicetree errors about missing nodes → Your overlay references a hardware node that doesn’t exist in the board’s base devicetree. Check the board’s .dts file in zephyr/boards/<vendor>/<board>/ to see what nodes are defined.

  4. “Could not find a runner” on west flash → Your board’s board.cmake specifies a debug probe (usually J-Link for Nordic DKs). Make sure the probe is connected and the driver is installed.

  5. Sample builds but BLE doesn’t advertise → Check prj.conf for CONFIG_BT=y and CONFIG_BT_PERIPHERAL=y. If those are set, check that the DK’s SoC has been programmed with the correct SoftDevice or that the Zephyr BLE controller is enabled.

Building This Into Your Workflow

The board target confusion is a one-time cost. Once you understand that it’s a hardware identity string, not a chip name, not a product code, but a complete platform description, the build system starts working for you instead of against you.

Here’s where to go from here:

  • Explore zephyr/samples/bluetooth/ — there are 20+ working BLE samples covering peripherals, centrals, mesh, and more. Each one is a validated reference that confirms your board target and toolchain are working.
  • Bookmark the Zephyr board catalog for target string lookups.
  • Consult Nordic’s nRF Connect SDK docs if you’re using NCS, which layers Nordic-specific features on top of Zephyr.
  • Join the Zephyr Discord for real-time help when you hit the next wall, and there will be one, because that’s how embedded development works.

The build system isn’t the enemy. It’s just a terrible first impression.

Hubble Network connects your BLE devices directly to satellites—no gateways, no extra infrastructure. See how it works →