Mapping Physical Header Pins to Logical GPIO Numbers in Code

Once you set up your development board, one of the first things you may want to do is connect external hardware (e.g. wires, sensors, LEDs) to your board. To do so, you would interact with the physical header pins, which may be labeled on your board as DIO24, P0.3, or Pin 9. However, you probably won’t be able to use those labels directly in your code. Instead, you must use logical GPIO identifiers, such as CONFIG_GPIO_LED or gpio_led, that the firmware maps to the physical header pins behind the scenes.

It is essential to understand how to map between physical pins and logical GPIOs. In this guide, you’ll learn the mapping process on the Texas Instruments CC2340 series and Nordic Semiconductor 54 L series development boards, with testable examples you can verify immediately.

Why GPIO Mapping Matters

Hardware designers route microcontroller pins to headers, LEDs, and buttons. Software frameworks expose those pins through symbols or devicetree aliases. The mapping layer lets firmware remain portable and readable even if hardware changes.

In practice, mapping answers the simple question: Which logical GPIO controls this physical pin or LED?

The answer depends on three layers:

• Microcontroller pin name: The microcontroller’s internal GPIO label (e.g. DIO24, P0.3)
• Board routing: Where the pin is physically connected on the board
• Software alias: The logical identifier used in firmware code (e.g. CONFIG_GPIO_LED)

TI CC2340R5 Example

The TI CC2340R5 LaunchPad uses TI’s DIO numbering. Each microcontroller pad has a logical ID like DIO5. The board routes those pads to LEDs and headers.

Here’s an example of this mapping:

• Microcontroller pin: DIO5
• Board: DIO5 header
• Code symbol: CONFIG_GPIO_LED

Follow the steps below to visualize this mapping on your board with an external LED.

Note: You will need an external LED for this exercise, or some other device that can turn on/off when connected to your board. You can also use a multimeter to manually measure the output from your board’s physical header.

Step 1: Connect an external LED to your board

Connect the anode to the DIO5 pin on your board, and the cathode to ground.

Step 2: Create a GPIO instance in SysConfig

In your project’s SysConfig, create a GPIO instance. Name it CONFIG_GPIO_LED, and select DIO5 in the GPIO Pin field. This generates the file ti_drivers_config.h, which links the symbol to the physical pin.

Step 3: Enable header output in firmware

Add the following code to your main application file to enable GPIO output:

#include <ti/drivers/GPIO.h>
#include "ti_drivers_config.h"

int main(void)
{
	// Initialize board-level drivers
   	 Board_init();

    // Initialize GPIO driver module
    GPIO_init();

	// Configure the header pin as a standard output that can be toggled, with off as the initial state
	GPIO_setConfig(CONFIG_GPIO_LED_CONST, GPIO_CFG_OUT_STD | GPIO_CFG_OUT_LOW);

	// Enable output on the header, turning on the external LED
	GPIO_write(CONFIG_GPIO_LED_CONST, CONFIG_GPIO_LED_ON);

	while (1) {}
}

Step 4: See the LED turn on

Build and flash your firmware onto the board. You should see the LED turn on.

Nordic nRF54L15 Example

The Nordic nRF54L15 uses port-pin notation (e.g. P0.2, P0.3). It defines LEDs and buttons with devicetree aliases. The devicetree defines the physical pin and exposes it to code.

Here’s an example of this mapping:

• Microcontroller pin: P0.3
• Board: Port P0, Pin 03
• Devicetree alias: gpio_led

Follow the steps below to visualize this mapping on your board with an external LED.

Note: You will need an external LED for this exercise, or some other device that can turn on/off when connected to your board. You can also use a multimeter to manually measure the output from your board’s physical header.

Step 1: Connect an external LED to your board

Connect the anode to Pin 03 in Port P0 on your board, and the cathode to ground.

Step 2: Enable and map GPIO

Add the following to your project’s prj.conf to enable GPIO usage in your firmware.

Create a devicetree overlay for your project. Add the following code to create an alias for pin P0.3.

/ {
	// Create the gpio_led alias for GPIO pin node P0.3
	gpio_led: gpio_led {
		// Define the binding definitions for the GPIO pin
    	compatible = "nordic,gpio-pins";
	  	// Specify which pin node to use for this alias
        gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>;
	  	// Enable the pin node when it is set to "okay"
        status = "okay";
    };
};

// Enable the gpio0 instance so the GPIO driver can be used elsewhere in the firmware
&gpio0 {
    status = "okay";
};

Step 3: Enable header output in firmware

Add the following code to your main application file to enable GPIO output:

#include <zephyr/drivers/gpio.h>

// Initialize a variable assigned to the gpio_led alias that can be toggled 
static const struct gpio_dt_spec test_led = GPIO_DT_SPEC_GET(DT_NODELABEL(gpio_led), gpios);

int main(void)
{
	// Enable output on the header pin, turning on the external LED
	gpio_pin_configure_dt(&test_led, GPIO_OUTPUT_ACTIVE);

	while (1) {}
}

Step 4: See the LED turn on

Build and flash your firmware onto the board. You should see the LED turn on.

Key GPIO Mapping Differences Between TI and Nordic Boards

You can map logical GPIOs to physical header pins on both platforms, but they work a little differently. Here is a summary of what you need to know for TI and Nordic boards:

Common Issues

If your external LED does not turn on, check the following:

Wiring

Make sure you have your LED connected to the correct physical header on your board. It’s possible that the GPIO number in your project is correct, but your LED is not connected to the right physical pin. Check your board’s hardware diagram if you’re unsure.

Wrong Alias

Make sure you are using the correct alias in your firmware code. It’s possible that you mapped the correct GPIO pin to an alias, but used a different one in your code.

Board Power

Nordic development boards sometimes only output 1.8 V by default to their GPIO pins. This may not be enough to power an external LED. Use Nordic’s Board Configurator tool to adjust the voltage for the pins to 3.3 V.

Troubleshoot With a Multimeter

If all else fails, use a multimeter to measure the voltage across the physical header you enabled. This is the most foolproof way to determine whether you correctly enabled your GPIO in the firmware.

Wrapping Up

Mapping physical pins to logical GPIOs is a core skill for firmware development. Although the TI CC2340R5 and Nordic nRF54L15 development boards use different naming and configuration tools, both use the same three layers: microcontroller pin -> board routing -> software alias.

By using simple LED tests, you can verify your mapping quickly and avoid hours of debugging. When the physical signal from your board header matches your code, you know your GPIO configuration is correct.

Ready to connect your devices anywhere on Earth? Get started with Hubble Network for free →