DEV Community: Pranav Jain

AI Code Assistants for Embedded Engineers: What Works, What Doesn

Pranav Jain — Thu, 20 Aug 2026 10:06:26 +0000

I write C for microcontrollers. My code talks to SPI peripherals, configures DMA channels, and runs in environments where a buffer overflow doesn't crash a browser — it crashes a piece of industrial equipment. AI code assistants were not built for this.

But I use them every day. Here's what actually works, what's dangerous, and where I think this is heading.

What I Tested

I've been using three AI assistants in my embedded workflow for the past year:

GitHub Copilot — inline completions in VS Code
Claude — long-form code generation, architecture discussions, code review
ChatGPT — quick questions, datasheet interpretation

I used them on real firmware projects: STM32F4, nRF52840, ESP32-S3. Bare-metal and Zephyr RTOS. 20-60K LOC codebases. Here's what happened.

Where AI Assistants Actually Help

1. Boilerplate Peripheral Initialization

This is the clearest win. Peripheral init code is formulaic — read the reference manual, fill in the struct fields, enable the clocks, configure the pins. AI assistants are very good at this.

Example: "Write STM32 HAL SPI1 init for PA5/PA6/PA7, Mode 0, 1 MHz, 8-bit"

Claude gives me:

void SPI1_Init(void) {
    __HAL_RCC_SPI1_CLK_ENABLE();
    __HAL_RCC_GPIOA_CLK_ENABLE();

    GPIO_InitTypeDef gpio = {0};
    gpio.Pin = GPIO_PIN_5 | GPIO_PIN_6 | GPIO_PIN_7;
    gpio.Mode = GPIO_MODE_AF_PP;
    gpio.Pull = GPIO_NOPULL;
    gpio.Speed = GPIO_SPEED_FREQ_LOW;
    gpio.Alternate = GPIO_AF5_SPI1;
    HAL_GPIO_Init(GPIOA, &gpio);

    hspi1.Instance = SPI1;
    hspi1.Init.Mode = SPI_MODE_MASTER;
    hspi1.Init.Direction = SPI_DIRECTION_2LINES;
    hspi1.Init.DataSize = SPI_DATASIZE_8BIT;
    hspi1.Init.CLKPolarity = SPI_POLARITY_LOW;
    hspi1.Init.CLKPhase = SPI_PHASE_1EDGE;
    hspi1.Init.BaudRatePrescaler = SPI_BAUDRATEPRESCALER_64;
    hspi1.Init.FirstBit = SPI_FIRSTBIT_MSB;
    HAL_SPI_Init(&hspi1);
}

This is correct, took 5 seconds, and would have taken me 10 minutes of cross-referencing the reference manual. The prescaler calculation (64 MHz / 64 = 1 MHz) is right. The AF mapping (AF5 for SPI1 on PA5-7) is right.

Time saved: 10 minutes per peripheral init. Maybe 30-40 minutes per project.

2. Protocol Decoders and Data Parsers

Parsing sensor data, decoding protocol frames, bit manipulation — AI assistants handle this well because the logic is well-defined and the edge cases are enumerable.

Example: "Parse this BME280 temperature reading from raw registers"

int32_t bme280_compensate_temperature(int32_t adc_T,
                                       struct bme280_calib *cal) {
    int32_t var1 = ((((adc_T >> 3) - ((int32_t)cal->dig_T1 << 1))) *
                    ((int32_t)cal->dig_T2)) >> 11;
    int32_t var2 = (((((adc_T >> 4) - ((int32_t)cal->dig_T1)) *
                      ((adc_T >> 4) - ((int32_t)cal->dig_T1))) >> 12) *
                    ((int32_t)cal->dig_T3)) >> 14;
    return (var1 + var2);
}

This is directly from the BME280 datasheet compensation formula. AI gets it right because it's seen this exact code in thousands of projects.

3. Test Scaffolding

AI is good at generating test cases for embedded code — especially when you give it the function signature and describe the edge cases.

"Write Unity test cases for this CRC-16 function, including: empty input, single byte, known test vector, maximum length buffer."

This saves 15-20 minutes per function and produces tests I might not have thought of.

4. Build System Configuration

CMake for cross-compilation is arcane. AI assistants know the incantations:

"Generate a CMake toolchain file for ARM GCC targeting Cortex-M4 with FPU"

This consistently produces working output. CMake is well-documented online and AI has seen thousands of examples.

5. Documentation and Comments

"Add doxygen comments to this driver interface header" — AI does this well. It reads the parameter names, infers the purpose, and produces reasonable documentation.

Where AI Assistants Are Dangerous

1. Register-Level Code for Uncommon Peripherals

Ask for LTDC (LCD controller) configuration on STM32F4 and you'll get plausible-looking code that doesn't work. The AI has seen fewer examples of LTDC than SPI, so it generates something that looks right but has wrong timing parameters or missing register fields.

Rule: If the peripheral has fewer than 1000 open-source code examples on GitHub, don't trust AI-generated register-level code without verifying against the reference manual.

2. DMA Configuration

This is where I've seen the most AI-generated bugs. DMA involves channel assignment, priority, FIFO thresholds, memory alignment, and peripheral-specific constraints. AI gets the structure right but misses constraints like "DMA2 Stream 0 Channel 3 is the only valid assignment for SPI1 RX on this specific STM32 variant."

// AI-generated DMA config — looks correct but...
hdma.Init.Channel = DMA_CHANNEL_3;  // Wrong channel for this peripheral
hdma.Init.Direction = DMA_PERIPH_TO_MEMORY;
hdma.Init.PeriphInc = DMA_PINC_DISABLE;
hdma.Init.MemInc = DMA_MINC_ENABLE;
hdma.Init.FIFOThreshold = DMA_FIFO_THRESHOLD_FULL;  // Bad choice for small transfers

Rule: Always verify DMA channel assignments against the DMA request mapping table in the reference manual. AI can't reliably do this.

3. Interrupt Priority and RTOS Integration

AI assistants don't understand the runtime implications of interrupt priorities. They'll generate code that assigns ISR priorities without considering what other interrupts are active, whether the RTOS uses BASEPRI masking, or what configMAX_SYSCALL_INTERRUPT_PRIORITY is set to in FreeRTOS.

4. Timing-Critical Code

Anything that depends on cycle-accurate timing — bit-banged protocols, pulse measurement, ISR latency — is a bad fit for AI assistance. The AI doesn't know your clock speed, pipeline behavior, or compiler optimization settings.

5. Security-Sensitive Code

Cryptographic operations, secure boot, key storage. Don't use AI for this. The surface area for subtle bugs is too large, and the consequences of getting it wrong are too severe.

How I Actually Use AI in My Workflow

Morning: Open the project, use Copilot for autocomplete on routine code. It fills in struct initializations, for-loop bodies, and switch-case arms.

Architecture questions: "I need SPI communication between two MCUs with flow control. What patterns work?" — I ask Claude, get 3 approaches with tradeoffs, then implement the one that fits.

Debugging: "This SPI transfer returns HAL_TIMEOUT. The clock is configured for 1 MHz, CPOL=0, CPHA=0. What should I check?" — AI gives a reasonable debugging checklist. Not always right, but a good starting point.

Code review: Paste a function into Claude and ask "What bugs or edge cases do you see?" — catches things like integer overflow in ADC scaling, missing null checks on buffer pointers, off-by-one in circular buffer indices.

What I never do: Copy-paste AI-generated code into production without reading every line. Especially register-level code. Especially DMA.

The Embedded-Specific Gap

AI assistants are trained on web and application code. The embedded domain has unique challenges they handle poorly:

Hardware datasheets are not in their training data (or poorly represented)
Real-time constraints aren't something they can reason about
Memory-constrained environments mean patterns that work in application code (dynamic allocation, string formatting) are wrong in embedded
Vendor-specific errata — every MCU has hardware bugs documented in errata sheets. AI doesn't know about them.

The ideal embedded AI assistant would:

Have the MCU's reference manual in context
Know the specific chip variant and its errata
Understand RTOS-specific constraints (stack sizes, priority inversions)
Verify DMA channel assignments against the mapping table
Flag timing assumptions that depend on clock configuration

We're not there yet. But we're closer than we were a year ago.

Bottom Line

AI code assistants save me 30-60 minutes per day on embedded projects. Mostly from boilerplate generation, test scaffolding, and build system configuration.

They produce dangerous output for DMA, interrupt priorities, and uncommon peripherals. The cost of a subtle register-level bug in production embedded code is much higher than in a web app — hours of debugging with an oscilloscope and logic analyzer, or worse, a field failure.

Use them as a first draft generator, not a finished code source. Every line gets reviewed against the reference manual. That discipline turns AI from a liability into a genuine productivity boost.

Pranav Jain writes middleware and abstraction layers for embedded systems. Find him on GitHub.

I Reviewed 5 Open-Source HALs — What They Got Right and Wrong

Pranav Jain — Thu, 20 Aug 2026 10:01:27 +0000

I've spent the last few years writing abstraction layers between hardware and application software. Part of my job is knowing what's out there, what works, and what breaks when you need it most. So I went through five open-source hardware abstraction layers and evaluated them on the criteria that matter for production firmware.

Here's what I found.

The Evaluation Criteria

I scored each HAL on five dimensions:

Portability — How many MCU families does it support? How hard is it to add a new one?
Performance — What's the overhead vs direct register access?
API Design — Is the API intuitive? Consistent? Does it leak hardware details?
Documentation — Can a new developer figure it out without reading the source?
Production Readiness — Is it used in real products? Are there gotchas?

Scale: 1 (poor) to 5 (excellent).

1. Zephyr RTOS Device Driver Model

What it is: Zephyr isn't just an RTOS — it's a full operating system with a driver model based on Linux's device tree concept. Hardware is described in .dts files, and drivers bind to device tree nodes.

Example — GPIO:

#include <zephyr/drivers/gpio.h>

#define LED_NODE DT_ALIAS(led0)
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED_NODE, gpios);

void main(void) {
    gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
    while (1) {
        gpio_pin_toggle_dt(&led);
        k_msleep(500);
    }
}

What they got right:

Device tree separates hardware description from driver code. Your app code literally doesn't know which MCU it's running on.
Consistent API across all peripherals. GPIO, SPI, I2C, UART all follow the same pattern.
Massive MCU support — STM32, nRF, ESP32, NXP, TI, Renesas, Microchip, RISC-V families.
Active community, regular releases, Linux Foundation backing.

What they got wrong:

Learning curve is steep. Device tree overlay syntax is intimidating for embedded engineers coming from bare-metal.
Build system (west + CMake + Kconfig) is powerful but complex. First build can take 30 minutes of setup.
Overhead isn't zero. The driver model uses function pointer dispatch, which adds a few cycles per call. Fine for most apps, not ideal for bit-banging at MHz speeds.
Flash footprint starts around 40-60KB minimum. Not viable for small Cortex-M0 parts with 32KB flash.

Scores:
| Portability | Performance | API Design | Documentation | Production Ready |
|:-:|:-:|:-:|:-:|:-:|
| 5 | 3 | 4 | 4 | 5 |

Verdict: Best choice if your project can afford the footprint and learning curve. The portability is unmatched.

2. CMSIS (Cortex Microcontroller Software Interface Standard)

What it is: ARM's official standard for Cortex-M software interfaces. Defines core access functions, DSP intrinsics, RTOS API, and driver APIs.

Example — GPIO (CMSIS-Driver):

#include "Driver_GPIO.h"

extern ARM_DRIVER_GPIO Driver_GPIO0;

void led_init(void) {
    Driver_GPIO0.Setup(5, NULL);  // Pin 5
    Driver_GPIO0.SetDirection(5, ARM_GPIO_OUTPUT);
}

void led_toggle(void) {
    static int state = 0;
    Driver_GPIO0.SetOutput(5, state ^= 1);
}

What they got right:

It's a standard. If every vendor implemented it, portability would be solved.
CMSIS-Core (register access, NVIC, SysTick) is universally used and excellent.
CMSIS-DSP is genuinely useful and well-optimized.

What they got wrong:

Almost nobody implements CMSIS-Driver in practice. Vendors ship their own HALs (STM32 HAL, nRF drivers) instead.
The driver API is over-abstracted. It tries to be generic enough for every peripheral on every chip, resulting in an API that's awkward for all of them.
Documentation exists but is dense and spec-like, not tutorial-like.
CMSIS-RTOS is a wrapper API, not a real RTOS. It adds overhead without adding capability.

Scores:
| Portability | Performance | API Design | Documentation | Production Ready |
|:-:|:-:|:-:|:-:|:-:|
| 2 | 4 | 2 | 3 | 3 |

Verdict: CMSIS-Core is essential. CMSIS-Driver is a good idea that the industry ignored. Don't build on it unless you want to maintain the vendor implementations yourself.

3. Arduino HAL

What it is: The most successful embedded abstraction layer in terms of adoption. digitalWrite(), analogRead(), Serial.begin() — you know it.

Example:

void setup() {
    pinMode(LED_BUILTIN, OUTPUT);
    Serial.begin(115200);
}

void loop() {
    digitalWrite(LED_BUILTIN, HIGH);
    delay(500);
    digitalWrite(LED_BUILTIN, LOW);
    delay(500);
    Serial.println("blink");
}

What they got right:

Simplicity. A beginner can blink an LED in 5 minutes. That's an achievement.
Massive ecosystem. Libraries for every sensor, display, and communication module.
Runs on Arduino AVR, ESP32 (arduino-esp32), STM32 (STM32duino), nRF (Adafruit), RP2040. Genuine portability.

What they got wrong:

No DMA, no interrupts (without platform-specific extensions), no low-power modes. The API hides too much.
digitalWrite() is slow. On AVR, it's ~50 clock cycles vs 2 for direct port manipulation. On ARM it's better, but still has overhead from pin lookup.
Global state everywhere. One Serial object, one SPI object. Multi-instance is hacked in.
C++ requirement. Many embedded teams work in C. Arduino forces C++ with its class-based API.
Error handling is nonexistent. Functions either work or silently fail. No error codes, no status flags.

Scores:
| Portability | Performance | API Design | Documentation | Production Ready |
|:-:|:-:|:-:|:-:|:-:|
| 4 | 2 | 3 | 5 | 2 |

Verdict: Great for prototypes and education. Not for production firmware that needs DMA, interrupts, or low power. The API design philosophy (hide everything) is the opposite of what embedded needs (control everything).

4. libopencm3

What it is: An open-source, community-maintained firmware library for ARM Cortex-M microcontrollers. Lower level than STM32 HAL, higher level than direct register access.

Example — GPIO:

#include <libopencm3/stm32/rcc.h>
#include <libopencm3/stm32/gpio.h>

void led_init(void) {
    rcc_periph_clock_enable(RCC_GPIOA);
    gpio_mode_setup(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO5);
}

void led_toggle(void) {
    gpio_toggle(GPIOA, GPIO5);
}

What they got right:

Clean, C-only API. No opaque handles, no callback registration, no HAL_StatusTypeDef. Just function calls that map closely to hardware operations.
Thin. The overhead is minimal — most functions compile to a handful of register writes.
Supports STM32, EFM32, LPC, SAM, and some others. Not as wide as Zephyr but respectable.
Good linker scripts and startup code included. Build system is straightforward.

What they got wrong:

Community-maintained means inconsistent coverage. Some MCU families (STM32F1/F4) are well-supported. Others have gaps.
Not enough abstraction for easy porting. The API uses vendor-specific register names (GPIOA, RCC_GPIOA). Porting from STM32 to SAM requires changing every call.
No RTOS integration. It's purely a peripheral library.
Documentation is sparse. You'll read source code.

Scores:
| Portability | Performance | API Design | Documentation | Production Ready |
|:-:|:-:|:-:|:-:|:-:|
| 2 | 5 | 4 | 2 | 3 |

Verdict: Excellent for single-MCU projects where you want clean register access without the bloat of vendor HALs. Not a portability solution.

5. Tock OS

What it is: A secure embedded operating system written in Rust. Uses Rust's type system and ownership model to enforce isolation between the kernel, drivers, and applications.

Example — GPIO (Tock capsule):

// Kernel-side driver (capsule)
impl<'a, G: hil::gpio::Pin> hil::gpio::Client for GpioDriver<'a, G> {
    fn fired(&self) {
        self.callback.map(|callback| {
            callback.schedule(0, 0, 0);
        });
    }
}

What they got right:

Memory safety guaranteed by the compiler. Buffer overflows, use-after-free, data races — caught at compile time.
Strong isolation model. Untrusted applications can't crash the kernel or other apps.
The hardware interface layer (HIL) traits are well-designed. Clean separation between hardware-specific and hardware-independent code.
Academic rigor — published in SOSP, backed by serious research.

What they got wrong:

Rust on embedded is still maturing. Toolchain support, debugging tools, and community knowledge are improving but behind C.
Very limited MCU support compared to C-based alternatives. Primarily Nordic nRF52, some STM32, some RISC-V.
Overhead from the capsule/process model. More suitable for application processors (Cortex-M4+) than constrained MCUs.
Small community. If you hit a problem, there are fewer people who can help.
Hard to integrate with existing C codebases. If you have 50K lines of C firmware, Tock isn't a migration target.

Scores:
| Portability | Performance | API Design | Documentation | Production Ready |
|:-:|:-:|:-:|:-:|:-:|
| 2 | 3 | 5 | 3 | 2 |

Verdict: The future of secure embedded systems, but not the present for most teams. If you're starting a greenfield project on a supported MCU and your team knows Rust, it's worth evaluating.

Summary Scorecard

HAL	Portability	Performance	API Design	Docs	Production	Total
Zephyr	5	3	4	4	5	21
CMSIS	2	4	2	3	3	14
Arduino	4	2	3	5	2	16
libopencm3	2	5	4	2	3	16
Tock	2	3	5	3	2	15

What I'd Actually Recommend

For a new production project that needs portability: Zephyr. The learning curve is real, but the portability payoff is worth it. The ecosystem is growing fast.

For a bare-metal project on a single MCU: libopencm3 (if your MCU is supported) or the vendor HAL with a thin abstraction layer on top.

For a prototype or proof-of-concept: Arduino. Get it working, then rewrite for production.

For security-critical applications on supported hardware: Look at Tock. It's early but the safety guarantees are compelling.

For everyone: Don't use CMSIS-Driver. Use CMSIS-Core (it's great), but build your own driver abstraction or use Zephyr's.

And regardless of which HAL you choose — keep vendor types out of your application code. That single rule does more for portability than any framework.

Pranav Jain builds the middleware between hardware and application software. Find him on GitHub.

How to Test Firmware Without Physical Hardware

Pranav Jain — Thu, 20 Aug 2026 10:01:16 +0000

Most firmware teams test by flashing the board and watching an LED blink. That works until your test matrix is 200 cases, your CI pipeline needs to run on every commit, and the dev kit is on someone else's desk.

Here's how I test firmware without hardware for roughly 80% of the test surface. The remaining 20% — timing-critical code, analog peripherals, RF — still needs real silicon. But 80% is enough to catch the bugs that matter.

The Testing Pyramid for Firmware

Borrow the concept from web development but adapt it:

        /\
       /  \       Hardware-in-the-loop (HIL)
      /    \      Real board, real peripherals
     /------\
    /        \    Integration tests on target
   /          \   QEMU or native_sim
  /------------\
 /              \  Unit tests on host (x86)
/________________\ Mocked HAL, no hardware

Most of your tests should be at the bottom. Fast, cheap, run on any machine.

Level 1: Unit Tests on Host (x86)

This is the highest-ROI testing strategy for firmware. Compile your application code for your development machine, mock the hardware interfaces, test with any C test framework.

The Setup

Your code needs to be structured so that application logic doesn't directly call vendor HAL functions:

// application/sensor_reader.c
#include "hal/spi.h"
#include "hal/gpio.h"

#define SENSOR_CS_PIN ((gpio_pin_t){.port = 0, .pin = 4})

int sensor_read_temperature(int16_t *temp_out) {
    uint8_t cmd = 0x80;  // Read temperature register
    uint8_t rx[2] = {0};

    gpio_write(SENSOR_CS_PIN, 0);
    int err = spi_transfer(SPI_BUS_0, &cmd, rx, 2);
    gpio_write(SENSOR_CS_PIN, 1);

    if (err != 0) return err;

    *temp_out = (int16_t)((rx[0] << 8) | rx[1]) / 16;
    return 0;
}

Now mock the HAL for host testing:

// test/mocks/mock_spi.c
#include "hal/spi.h"
#include <string.h>

static uint8_t spi_rx_buffer[256];
static size_t spi_rx_len = 0;
static int spi_fail_next = 0;

void mock_spi_set_rx_data(const uint8_t *data, size_t len) {
    memcpy(spi_rx_buffer, data, len);
    spi_rx_len = len;
}

void mock_spi_set_fail(int fail) {
    spi_fail_next = fail;
}

int spi_transfer(spi_bus_t bus, const uint8_t *tx, uint8_t *rx, size_t len) {
    if (spi_fail_next) {
        spi_fail_next = 0;
        return -1;
    }
    if (rx && spi_rx_len >= len) {
        memcpy(rx, spi_rx_buffer, len);
    }
    return 0;
}

And the test:

// test/test_sensor_reader.c
#include "unity.h"  // or any C test framework
#include "application/sensor_reader.h"
#include "test/mocks/mock_spi.h"

void test_sensor_read_temperature_normal(void) {
    // 25.0°C = 400 raw = 0x0190
    uint8_t fake_data[] = {0x01, 0x90};
    mock_spi_set_rx_data(fake_data, 2);

    int16_t temp;
    int err = sensor_read_temperature(&temp);

    TEST_ASSERT_EQUAL(0, err);
    TEST_ASSERT_EQUAL(25, temp);
}

void test_sensor_read_temperature_spi_failure(void) {
    mock_spi_set_fail(1);

    int16_t temp;
    int err = sensor_read_temperature(&temp);

    TEST_ASSERT_NOT_EQUAL(0, err);
}

void test_sensor_read_negative_temperature(void) {
    // -10.0°C = -160 raw = 0xFF60
    uint8_t fake_data[] = {0xFF, 0x60};
    mock_spi_set_rx_data(fake_data, 2);

    int16_t temp;
    int err = sensor_read_temperature(&temp);

    TEST_ASSERT_EQUAL(0, err);
    TEST_ASSERT_EQUAL(-10, temp);
}

Compile and run on your laptop:

gcc -o test_sensor test/test_sensor_reader.c \
    application/sensor_reader.c \
    test/mocks/mock_spi.c test/mocks/mock_gpio.c \
    -Iinclude -Itest/frameworks/unity/src \
    test/frameworks/unity/src/unity.c
./test_sensor

Runs in milliseconds. No hardware. Catches logic bugs, edge cases, error handling.

What You Can Test This Way

Data parsing and protocol decoding
State machines
Command handlers
Configuration validation
Error handling paths
Math and algorithms
Buffer management
Anything that doesn't depend on timing or real peripherals

What You CAN'T Test This Way

Real-time behavior (ISR latency, DMA timing)
Peripheral initialization sequences
Power management
Analog signal paths
RF communication
Boot sequences

Level 2: QEMU for ARM Targets

QEMU emulates ARM Cortex-M processors well enough to run firmware images. It won't emulate your specific board's peripherals, but it handles the CPU, memory map, NVIC, and SysTick.

Zephyr + QEMU

Zephyr has first-class QEMU support:

# Build for QEMU Cortex-M3
west build -b qemu_cortex_m3 samples/hello_world
west build -t run

# Output:
# *** Booting Zephyr OS build v3.x.0 ***
# Hello World! qemu_cortex_m3

This runs your Zephyr application in QEMU — including the kernel, scheduler, and any drivers that have QEMU backends.

What QEMU Gives You

RTOS task scheduling and synchronization testing
Memory allocation and stack overflow detection
Kernel API correctness
Multi-threaded logic bugs

What QEMU Doesn't Give You

Real peripheral behavior (SPI, I2C, GPIO are stubs or absent)
Real timing (QEMU runs faster or slower than real hardware)
Board-specific initialization

Level 3: Zephyr native_sim (Best of Both Worlds)

This is my favorite approach. Zephyr's native_sim target compiles your firmware as a native Linux/macOS executable. It uses POSIX threads to simulate Zephyr's threading model, and you can link against host-side libraries.

west build -b native_sim samples/hello_world
./build/zephyr/zephyr.exe

Why this is powerful:

// Your Zephyr application
#include <zephyr/kernel.h>
#include <zephyr/drivers/gpio.h>

void main(void) {
    const struct device *gpio = DEVICE_DT_GET(DT_NODELABEL(gpio0));
    gpio_pin_configure(gpio, 13, GPIO_OUTPUT);

    while (1) {
        gpio_pin_toggle(gpio, 13);
        k_msleep(500);
    }
}

On native_sim, this compiles to a normal executable. The GPIO driver is a stub that logs calls. You can add assertions, inject faults, and run under Valgrind or AddressSanitizer:

west build -b native_sim -DCONFIG_ASAN=y my_app
./build/zephyr/zephyr.exe
# AddressSanitizer catches buffer overflows, use-after-free, etc.

Level 4: Hardware-in-the-Loop (HIL)

For the 20% that needs real hardware, automate it:

┌──────────┐     USB/SWD      ┌──────────┐
│  CI Host │ ──────────────── │  Dev Kit  │
│  (RPi)   │     Serial       │  (DUT)    │
│          │ ──────────────── │           │
└──────────┘                  └──────────┘

A Raspberry Pi (or any Linux machine) connected to your dev kit via SWD (for flashing) and serial (for output). The CI pipeline:

Flashes the firmware via OpenOCD / pyOCD / nrfjprog
Resets the board
Reads serial output
Asserts on expected output
Reports pass/fail

#!/bin/bash
# hil_test.sh
pyocd flash build/firmware.hex
pyocd reset
timeout 10 cat /dev/ttyACM0 | grep -q "SELF_TEST: PASS"
if [ $? -eq 0 ]; then
    echo "HIL test PASSED"
else
    echo "HIL test FAILED"
    exit 1
fi

CI Pipeline Example

# .github/workflows/firmware-test.yml
name: Firmware Tests
on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build and run unit tests
        run: |
          mkdir build && cd build
          cmake .. -DTARGET=host_test
          make
          ctest --output-on-failure

  zephyr-native:
    runs-on: ubuntu-latest
    container: ghcr.io/zephyrproject-rtos/ci:latest
    steps:
      - uses: actions/checkout@v4
      - name: Build for native_sim
        run: |
          west build -b native_sim app
          timeout 30 ./build/zephyr/zephyr.exe || true
      - name: Run with ASAN
        run: |
          west build -b native_sim app -- -DCONFIG_ASAN=y
          timeout 30 ./build/zephyr/zephyr.exe

  # HIL tests run on self-hosted runner with physical board
  hil-tests:
    runs-on: self-hosted  # RPi with connected dev kit
    needs: [unit-tests, zephyr-native]
    steps:
      - uses: actions/checkout@v4
      - name: Flash and test
        run: ./scripts/hil_test.sh

Unit tests and native_sim run on every commit (free, fast). HIL tests run on merge to main (needs hardware, slower).

Practical Advice

Start with unit tests on host. If your code can't compile for x86 because of vendor HAL dependencies, that's the first problem to fix. Introduce a HAL interface, mock it, get your application code compiling on the host.

Use Unity or CMock for C testing. They're lightweight, embedded-friendly, and widely used. Unity is just a single .c and .h file.

Don't mock too much. If you're mocking 15 interfaces to test one function, your function is too coupled. Refactor.

Keep tests fast. All host-side tests should complete in under 10 seconds. If they don't, something is wrong.

Test error paths. The happy path usually works. The bugs are in: SPI timeout handling, buffer overflow on unexpected response length, negative temperature values, config validation edge cases.

Measure coverage, but don't worship it. 80% coverage with meaningful tests beats 100% coverage with trivial assertions.

The Payoff

On a recent project, we had 340 unit tests running on x86, 20 integration tests on native_sim, and 12 HIL tests on a self-hosted runner. The unit tests caught 90% of bugs before they ever touched hardware. The average debug cycle went from "flash, observe, wonder, flash again" (15 minutes) to "run test, see failure, fix, run test" (30 seconds).

It's more work upfront. But firmware debugging is expensive — an hour saved per bug, across hundreds of bugs, across the life of a project, is measured in weeks.

Pranav Jain is an embedded systems engineer focused on middleware, abstraction layers, and developer tooling for firmware teams. Find him on GitHub.

The Chip Shortage Taught Us One Thing: Don't Vendor-Lock Your Firmware

Pranav Jain — Thu, 20 Aug 2026 09:53:39 +0000

Between 2021 and 2024, I watched firmware teams go through the five stages of grief. Their chip was on a 52-week lead time. The drop-in replacement didn't exist. And their entire codebase was welded to one vendor's HAL.

Now that lead times have mostly normalized, it's tempting to forget. Don't. The shortage exposed a structural weakness in how most teams write firmware, and the fix isn't "keep more inventory." It's in how you architect your code.

The Pattern I Saw Repeatedly

Company ships a product on STM32F4. Works great. Firmware is 30-50K lines of C, tightly coupled to STM32 HAL. Then:

STM32F4 goes to 40-week lead time
Purchasing finds an nRF52840 that's available NOW
Engineering estimates the port at "2-3 weeks"
Actual port takes 8-12 weeks
Product launch slips a quarter

I saw this pattern at three different companies between 2022 and 2023. The details varied, but the story was always the same: the firmware was married to the silicon.

Why "Just Use Zephyr" Isn't the Full Answer

The reflexive response is "use Zephyr RTOS" or "use an RTOS with a HAL." And yes, Zephyr's device tree model gives you portability. But:

Most firmware doesn't run an RTOS. Bare-metal is still the majority of embedded projects, especially at the lower end. If you're on a Cortex-M0 with 32KB flash, Zephyr isn't an option.

RTOS HALs have their own lock-in. You're not locked to STM32 HAL anymore — you're locked to Zephyr's API. If Zephyr's SPI driver doesn't support your use case (say, a specific DMA mode), you're back to writing vendor-specific code anyway.

The abstraction has to be yours. The only HAL you fully control is one you wrote. It doesn't need to be complex. It needs to be intentional.

What Portable Firmware Actually Looks Like

Here's what the teams that survived the shortage had in common:

1. A Thin Peripheral Interface

// hal/gpio.h — YOUR abstraction, not the vendor's
typedef struct {
    uint8_t port;
    uint8_t pin;
} gpio_pin_t;

typedef enum {
    GPIO_MODE_INPUT,
    GPIO_MODE_OUTPUT_PP,
    GPIO_MODE_OUTPUT_OD,
    GPIO_MODE_AF
} gpio_mode_t;

int gpio_init(gpio_pin_t pin, gpio_mode_t mode);
int gpio_write(gpio_pin_t pin, int value);
int gpio_read(gpio_pin_t pin);
int gpio_toggle(gpio_pin_t pin);

This is maybe 50 lines of header. The implementation file is different per target:

// hal/stm32/gpio.c
#include "hal/gpio.h"
#include "stm32f4xx_hal.h"

int gpio_init(gpio_pin_t pin, gpio_mode_t mode) {
    GPIO_InitTypeDef init = {0};
    init.Pin = (1U << pin.pin);
    init.Mode = (mode == GPIO_MODE_OUTPUT_PP) ? GPIO_MODE_OUTPUT_PP : GPIO_MODE_INPUT;
    init.Pull = GPIO_NOPULL;
    init.Speed = GPIO_SPEED_FREQ_LOW;

    GPIO_TypeDef *port = /* port lookup */;
    HAL_GPIO_Init(port, &init);
    return 0;
}

// hal/nrf52/gpio.c
#include "hal/gpio.h"
#include "nrf_gpio.h"

int gpio_init(gpio_pin_t pin, gpio_mode_t mode) {
    uint32_t nrf_pin = NRF_GPIO_PIN_MAP(pin.port, pin.pin);
    if (mode == GPIO_MODE_OUTPUT_PP) {
        nrf_gpio_cfg_output(nrf_pin);
    } else {
        nrf_gpio_cfg_input(nrf_pin, NRF_GPIO_PIN_NOPULL);
    }
    return 0;
}

When the shortage hit, the team with this structure swapped backends in 3 days. The team without it spent 6 weeks.

2. Build System That Supports Multiple Targets

# CMakeLists.txt
option(TARGET_MCU "Target MCU family" "stm32f4")

if(TARGET_MCU STREQUAL "stm32f4")
    add_subdirectory(hal/stm32)
    target_compile_definitions(app PRIVATE TARGET_STM32F4)
elseif(TARGET_MCU STREQUAL "nrf52")
    add_subdirectory(hal/nrf52)
    target_compile_definitions(app PRIVATE TARGET_NRF52)
endif()

If your build system can't switch targets with a single flag, your abstraction isn't real.

3. No Vendor Types in Application Code

This is the rule that matters most. If your application code contains GPIO_TypeDef, nrf_gpio_pin_map, or esp_err_t, you have a portability problem. Vendor types belong in the backend implementation files — nowhere else.

// BAD — vendor type leaked into application
void sensor_init(void) {
    GPIO_InitTypeDef gpio = {0};
    gpio.Pin = GPIO_PIN_5;
    gpio.Mode = GPIO_MODE_OUTPUT_PP;
    HAL_GPIO_Init(GPIOA, &gpio);
}

// GOOD — application uses your types only
void sensor_init(void) {
    gpio_pin_t cs_pin = {.port = 0, .pin = 5};
    gpio_init(cs_pin, GPIO_MODE_OUTPUT_PP);
}

4. Test Without Hardware

The teams that ported fastest had tests that ran on their host machine (x86), not on the target. They mocked the HAL interface:

// test/mock_gpio.c
static int gpio_states[256] = {0};

int gpio_write(gpio_pin_t pin, int value) {
    gpio_states[pin.pin] = value;
    return 0;
}

int gpio_read(gpio_pin_t pin) {
    return gpio_states[pin.pin];
}

When they switched MCUs, the application tests still passed. They only needed new tests for the backend implementation — which is a much smaller surface area.

The Cost of NOT Doing This

Let me put numbers on it. From three migrations I was involved with:

Project	LOC	Abstraction?	Port Time	Bugs Found Post-Port
A	45K	None	11 weeks	23
B	38K	Partial (GPIO/UART only)	5 weeks	8
C	52K	Full (all peripherals)	2 weeks	2

Project C had more code but ported 5x faster. The abstraction cost maybe 2 weeks to build originally. It paid for itself on the first port.

The "But We'll Never Switch" Fallacy

I've heard this from every team that eventually had to switch. "We're committed to STM32." "Nordic is our long-term partner." "We'll never need to port."

Until:

Your chip goes EOL
A new product variant needs a different feature set
Your customer requires a specific silicon vendor
A cheaper chip cuts your BOM by $2 (which, at volume, is millions)
Another shortage hits

The question isn't whether you'll port. It's when.

What I'd Do on a New Project Today

If I were starting a bare-metal project tomorrow:

Day 1: Define the peripheral interface (GPIO, SPI, I2C, UART, Timer — maybe 200 lines of headers total)
Day 2-3: Implement backend for the primary target
Day 3: Set up CMake with target selection
Day 3: Write mock backends for host testing
Ongoing: Never let vendor types leak past the HAL boundary

Total overhead: 2-3 days. Insurance against a multi-week port later.

If you're using an RTOS, the RTOS likely provides the abstraction. But verify: can you actually switch targets with just a config change? If not, you have hidden vendor dependencies.

The Broader Lesson

The chip shortage wasn't a freak event. It was a stress test. And it revealed that most firmware architectures are optimized for the happy path (one chip, forever) rather than the realistic path (you'll switch eventually).

The fix is simple. Not easy — it requires discipline to keep vendor code out of your application layer. But simple. A thin abstraction, a switchable build system, and the willingness to spend 2-3 days on infrastructure at the start of a project.

The teams that did this barely noticed the shortage. Everyone else had a very expensive year.

Pranav Jain is an embedded systems engineer specializing in middleware and abstraction layers between hardware and application software. He's building PortPilot, a tool that automates MCU migration analysis. Find him on GitHub.

Designing a HAL That Doesn't Lock You In

Pranav Jain — Thu, 20 Aug 2026 09:53:28 +0000

Every embedded engineer has lived through this moment: your company's chip supplier emails you that the MCU you designed around is end-of-life, or lead times just jumped to 52 weeks. You stare at 40,000 lines of firmware that call HAL_SPI_Transmit() in 200 places, and you realize your "abstraction" was just ST's abstraction. You're locked in.

I've spent years writing the mid-layer software that sits between customer applications and firmware — the abstraction that's supposed to make hardware swappable. I've seen what works, what doesn't, and what looks elegant in a conference talk but falls apart when you actually need to port to a different silicon vendor. This post is the guide I wish I'd had five years ago.

The Problem Statement

A hardware abstraction layer has one job: let the code above it not care which chip is below it. That sounds simple. It isn't. The tension is between three competing goals:

Portability — the whole point. Write once, run on STM32, nRF, ESP32, RP2040.
Performance — embedded systems have hard timing constraints. Every layer of indirection costs cycles.
Expressiveness — different MCUs have different capabilities. Your abstraction either exposes them (and leaks hardware details) or hides them (and loses functionality).

Pick two. The art is in knowing which two matter for your project.

The Landscape: How Everyone Else Does It

Before building something custom, let's look at what exists and where each approach breaks down.

CMSIS: The Lowest Common Denominator

ARM's Cortex Microcontroller Software Interface Standard gives you register-level access with consistent naming. It's not really an abstraction — it's a naming convention for registers.

// CMSIS-style GPIO toggle on STM32
GPIOA->ODR ^= GPIO_PIN_5;

// Same idea on an LPC
LPC_GPIO0->FIOPIN ^= (1 << 22);

CMSIS standardizes the Cortex-M core peripherals (NVIC, SysTick, MPU) beautifully. But GPIO? SPI? UART? Those are vendor peripherals, and CMSIS doesn't touch them. Every vendor's register map is different, and CMSIS doesn't help you bridge that gap.

Verdict: CMSIS is a foundation, not a HAL. You still need something on top.

STM32 HAL: The Golden Handcuffs

ST's HAL is the most widely used abstraction in the embedded world, mostly because STM32 is the most widely used MCU family. It's comprehensive, well-documented, and it will absolutely destroy your portability.

// STM32 HAL SPI transmit
SPI_HandleTypeDef hspi1;
uint8_t tx_buf[] = {0xAA, 0xBB, 0xCC};
HAL_SPI_Transmit(&hspi1, tx_buf, sizeof(tx_buf), HAL_MAX_DELAY);

The problem isn't that HAL_SPI_Transmit is a bad API. It's actually pretty good. The problem is that SPI_HandleTypeDef contains 15 fields that are deeply STM32-specific — the prescaler values map to ST's clock tree, the alternate function pin mappings are ST-specific, and the DMA channel configuration assumes ST's DMA controller topology.

When you call HAL_SPI_Init(), you're committing to ST's entire initialization model. Every file that touches that handle is now ST-locked, even if it never reads a vendor-specific field.

I've seen codebases where the "platform-independent" business logic imports stm32f4xx_hal.h because someone passed an SPI_HandleTypeDef* through three layers of function calls. That's the lock-in. It's not the function call — it's the type that leaks upward.

Arduino: Simplicity at a Cost

Arduino's approach is the opposite extreme: hide everything behind the simplest possible API.

// Arduino SPI
SPI.begin();
SPI.transfer(0xAA);

// Arduino GPIO
digitalWrite(13, HIGH);

This is genuinely portable — Arduino runs on AVR, SAMD, ESP32, RP2040, STM32, and more. But the cost is severe. digitalWrite() is famously slow (50-80 cycles on AVR vs. 1-2 cycles for direct port manipulation) because it does a pin lookup table traversal at runtime. You can't configure DMA-driven SPI transfers. You can't set up half-duplex mode. You can't do pin-level interrupts with configurable edge detection on some platforms.

Arduino proves that you can build a universal HAL, but it also proves that "universal" often means "universally limited."

Zephyr: Device Tree and the Nuclear Option

Zephyr RTOS takes the most sophisticated approach: device tree bindings (borrowed from Linux) combined with a driver model that separates API, driver implementation, and hardware description.

// Zephyr GPIO — device tree driven
const struct device *gpio_dev = DEVICE_DT_GET(DT_NODELABEL(gpio0));
gpio_pin_configure(gpio_dev, PIN, GPIO_OUTPUT_ACTIVE);
gpio_pin_set(gpio_dev, PIN, 1);

// Zephyr SPI — same pattern
const struct device *spi_dev = DEVICE_DT_GET(DT_NODELABEL(spi1));
struct spi_buf tx_buf = { .buf = data, .len = sizeof(data) };
struct spi_buf_set tx = { .buffers = &tx_buf, .count = 1 };
struct spi_config cfg = {
    .frequency = 1000000,
    .operation = SPI_WORD_SET(8) | SPI_TRANSFER_MSB,
};
spi_write(spi_dev, &cfg, &tx);

The hardware description lives in .dts files:

&spi1 {
    status = "okay";
    cs-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>;
    my_sensor: sensor@0 {
        compatible = "bosch,bme280";
        reg = <0>;
        spi-max-frequency = <1000000>;
    };
};

This is the gold standard for portability. The same application code runs on any board with a Zephyr BSP. Swapping MCUs means changing the device tree overlay and the board config — zero application code changes.

But Zephyr is an entire operating system. You're adopting a build system (west + CMake + Kconfig), a threading model, a memory management policy, a logging framework, and a driver model. For a blinking LED project, this is absurd. For a product with 3+ year lifecycle and potential MCU swaps, it might be exactly right.

Verdict: If you can afford the complexity, Zephyr's model is the best-designed HAL in the embedded ecosystem. But "can you afford the complexity" is doing a lot of heavy lifting in that sentence.

Hand-Rolled: The Default Choice

Most production firmware I've worked on uses a hand-rolled HAL. Not because engineers sat down and designed one, but because someone created hal_gpio.h one afternoon and it grew organically. These range from elegant to horrifying.

The horrifying ones look like this:

// The "abstraction" that isn't
#ifdef STM32F4
    #include "stm32f4xx_hal.h"
    #define MY_SPI_HANDLE hspi1
    #define MY_SPI_TRANSMIT(buf, len) HAL_SPI_Transmit(&MY_SPI_HANDLE, buf, len, 1000)
#elif defined(NRF52)
    #include "nrfx_spi.h"
    #define MY_SPI_HANDLE m_spi
    #define MY_SPI_TRANSMIT(buf, len) nrfx_spi_xfer(&MY_SPI_HANDLE, \
        &(nrfx_spi_xfer_desc_t){.p_tx_buffer = buf, .tx_length = len}, 0)
#endif

This is a thin preprocessor skin over vendor APIs. It "works" until you need error handling (each vendor returns errors differently), or async transfers (each vendor's callback model is different), or you add a third platform. The #ifdef jungle grows until no one can reason about it.

What Actually Works: Building a Portable GPIO + SPI Abstraction

Here's how I'd design a HAL for a team that needs to support 2-3 MCU families without adopting Zephyr. This is the pattern I've used in production.

Principle 1: Your Types, Not Theirs

The single most important rule: never let a vendor type appear in your public API. The moment SPI_HandleTypeDef or nrfx_spi_t shows up in a header that application code includes, you're locked in.

Define your own types. They can be thin wrappers — that's fine. But they're yours.

// hal/hal_gpio.h — YOUR public API
#pragma once
#include <stdint.h>
#include <stdbool.h>

typedef enum {
    HAL_GPIO_MODE_INPUT,
    HAL_GPIO_MODE_OUTPUT_PP,   // push-pull
    HAL_GPIO_MODE_OUTPUT_OD,   // open-drain
    HAL_GPIO_MODE_AF,          // alternate function (SPI, I2C, etc.)
} hal_gpio_mode_t;

typedef enum {
    HAL_GPIO_PULL_NONE,
    HAL_GPIO_PULL_UP,
    HAL_GPIO_PULL_DOWN,
} hal_gpio_pull_t;

typedef struct {
    uint8_t port;    // 0 = GPIOA / P0, 1 = GPIOB / P1, etc.
    uint8_t pin;     // 0-15 typically
} hal_gpio_pin_t;

typedef struct {
    hal_gpio_mode_t mode;
    hal_gpio_pull_t pull;
    uint8_t af_num;  // alternate function number (ignored if mode != AF)
} hal_gpio_config_t;

// API
int hal_gpio_init(hal_gpio_pin_t pin, const hal_gpio_config_t *cfg);
int hal_gpio_write(hal_gpio_pin_t pin, bool state);
bool hal_gpio_read(hal_gpio_pin_t pin);
int hal_gpio_toggle(hal_gpio_pin_t pin);

Notice what's missing: no GPIO_TypeDef*, no nrf_gpio_pin_dir_t, no vendor anything. Application code includes this header and only this header.

Principle 2: One Implementation File Per Platform

Each platform gets its own .c file. The build system picks which one to compile.

// hal/stm32/hal_gpio_stm32.c
#include "hal/hal_gpio.h"
#include "stm32f4xx_hal.h"   // vendor header — confined to this file

static GPIO_TypeDef* port_map[] = { GPIOA, GPIOB, GPIOC, GPIOD, GPIOE };

int hal_gpio_init(hal_gpio_pin_t pin, const hal_gpio_config_t *cfg) {
    if (pin.port >= sizeof(port_map)/sizeof(port_map[0])) return -1;

    // Enable clock — this is the kind of vendor-specific detail
    // that MUST live in the platform file
    __HAL_RCC_GPIOA_CLK_ENABLE();  // simplified; real code uses port index

    GPIO_InitTypeDef gpio_init = {
        .Pin  = (1U << pin.pin),
        .Mode = (cfg->mode == HAL_GPIO_MODE_OUTPUT_PP) ? GPIO_MODE_OUTPUT_PP :
                (cfg->mode == HAL_GPIO_MODE_OUTPUT_OD) ? GPIO_MODE_OUTPUT_OD :
                (cfg->mode == HAL_GPIO_MODE_AF)        ? GPIO_MODE_AF_PP :
                                                         GPIO_MODE_INPUT,
        .Pull = (cfg->pull == HAL_GPIO_PULL_UP)   ? GPIO_PULLUP :
                (cfg->pull == HAL_GPIO_PULL_DOWN) ? GPIO_PULLDOWN :
                                                    GPIO_NOPULL,
        .Speed = GPIO_SPEED_FREQ_HIGH,
        .Alternate = cfg->af_num,
    };
    HAL_GPIO_Init(port_map[pin.port], &gpio_init);
    return 0;
}

int hal_gpio_write(hal_gpio_pin_t pin, bool state) {
    HAL_GPIO_WritePin(port_map[pin.port], (1U << pin.pin),
                      state ? GPIO_PIN_SET : GPIO_PIN_RESET);
    return 0;
}

bool hal_gpio_read(hal_gpio_pin_t pin) {
    return HAL_GPIO_ReadPin(port_map[pin.port], (1U << pin.pin)) == GPIO_PIN_SET;
}

int hal_gpio_toggle(hal_gpio_pin_t pin) {
    HAL_GPIO_TogglePin(port_map[pin.port], (1U << pin.pin));
    return 0;
}

// hal/nrf52/hal_gpio_nrf52.c
#include "hal/hal_gpio.h"
#include "nrf_gpio.h"

// nRF uses a flat pin numbering: port * 32 + pin
static inline uint32_t to_nrf_pin(hal_gpio_pin_t p) {
    return (uint32_t)p.port * 32 + p.pin;
}

int hal_gpio_init(hal_gpio_pin_t pin, const hal_gpio_config_t *cfg) {
    uint32_t npin = to_nrf_pin(pin);
    nrf_gpio_pin_pull_t pull =
        (cfg->pull == HAL_GPIO_PULL_UP)   ? NRF_GPIO_PIN_PULLUP :
        (cfg->pull == HAL_GPIO_PULL_DOWN) ? NRF_GPIO_PIN_PULLDOWN :
                                            NRF_GPIO_PIN_NOPULL;
    if (cfg->mode == HAL_GPIO_MODE_INPUT) {
        nrf_gpio_cfg_input(npin, pull);
    } else {
        nrf_gpio_cfg_output(npin);
    }
    return 0;
}

int hal_gpio_write(hal_gpio_pin_t pin, bool state) {
    state ? nrf_gpio_pin_set(to_nrf_pin(pin))
          : nrf_gpio_pin_clear(to_nrf_pin(pin));
    return 0;
}

bool hal_gpio_read(hal_gpio_pin_t pin) {
    return nrf_gpio_pin_read(to_nrf_pin(pin)) != 0;
}

int hal_gpio_toggle(hal_gpio_pin_t pin) {
    nrf_gpio_pin_toggle(to_nrf_pin(pin));
    return 0;
}

The application code is identical regardless of which platform file is compiled. That's the whole point.

Principle 3: SPI — Where It Gets Interesting

SPI is harder than GPIO because it has more modes, needs error handling, and often involves DMA for performance. Here's a practical abstraction:

// hal/hal_spi.h
#pragma once
#include "hal/hal_gpio.h"
#include <stdint.h>
#include <stddef.h>

typedef struct hal_spi hal_spi_t;  // opaque — defined per platform

typedef enum {
    HAL_SPI_MODE_0,  // CPOL=0, CPHA=0
    HAL_SPI_MODE_1,  // CPOL=0, CPHA=1
    HAL_SPI_MODE_2,  // CPOL=1, CPHA=0
    HAL_SPI_MODE_3,  // CPOL=1, CPHA=1
} hal_spi_mode_t;

typedef enum {
    HAL_SPI_BIT_ORDER_MSB_FIRST,
    HAL_SPI_BIT_ORDER_LSB_FIRST,
} hal_spi_bit_order_t;

typedef struct {
    uint32_t            max_freq_hz;
    hal_spi_mode_t      mode;
    hal_spi_bit_order_t bit_order;
    hal_gpio_pin_t      cs_pin;       // managed by HAL, not by caller
    bool                cs_active_low;
} hal_spi_config_t;

typedef void (*hal_spi_callback_t)(int status, void *ctx);

// Lifecycle
hal_spi_t *hal_spi_open(uint8_t instance, const hal_spi_config_t *cfg);
void       hal_spi_close(hal_spi_t *spi);

// Blocking
int hal_spi_transfer(hal_spi_t *spi, const uint8_t *tx, uint8_t *rx, size_t len);
int hal_spi_write(hal_spi_t *spi, const uint8_t *tx, size_t len);
int hal_spi_read(hal_spi_t *spi, uint8_t *rx, size_t len);

// Async (optional — returns -ENOTSUP if platform doesn't support it)
int hal_spi_transfer_async(hal_spi_t *spi, const uint8_t *tx, uint8_t *rx,
                           size_t len, hal_spi_callback_t cb, void *ctx);

Key design decisions here:

Opaque handle. hal_spi_t is forward-declared in the header and defined in each platform's .c file. This is the critical firewall — application code can't reach into the handle and touch vendor-specific fields because it doesn't know what they are.

CS pin management. The HAL asserts/deasserts chip select. This sounds minor but it's one of the most common sources of porting bugs. Different vendors handle CS differently (hardware vs. software, active high vs. low), and if your application code manages CS directly, every call site needs platform ifdefs.

Async as optional. Not every platform supports DMA-driven SPI with the same callback model. Rather than forcing a lowest-common-denominator async API, we let it return -ENOTSUP and let the caller fall back to blocking. Pragmatic beats pure.

The Dispatch Question: Compile-Time vs. Runtime

This is where HAL design gets philosophical. How does hal_spi_transfer() know which implementation to call?

Option A: Compile-Time Dispatch (Link-Time Selection)

The simplest approach: only one platform .c file is compiled into the binary. The linker resolves hal_spi_transfer to whichever implementation was compiled.

# Makefile
ifeq ($(PLATFORM),stm32)
    HAL_SRC = hal/stm32/hal_spi_stm32.c hal/stm32/hal_gpio_stm32.c
else ifeq ($(PLATFORM),nrf52)
    HAL_SRC = hal/nrf52/hal_spi_nrf52.c hal/nrf52/hal_gpio_nrf52.c
endif

Pros: Zero overhead. No function pointers, no vtables, no indirection. The compiler can inline everything. This is what you want for hard real-time systems where every cycle matters.

Cons: You can only target one platform per binary. You can't have a test binary that mocks the hardware — unless you add a hal/mock/ platform and compile against that.

This is the approach I recommend for 90% of projects. The "one platform per binary" limitation sounds restrictive until you realize that's what you're doing anyway — you don't ship the same .elf to an STM32 and an nRF52.

Option B: Function Pointer Tables

// hal/hal_spi.h (function pointer variant)
typedef struct {
    hal_spi_t* (*open)(uint8_t instance, const hal_spi_config_t *cfg);
    void       (*close)(hal_spi_t *spi);
    int        (*transfer)(hal_spi_t *spi, const uint8_t *tx, uint8_t *rx, size_t len);
    int        (*write)(hal_spi_t *spi, const uint8_t *tx, size_t len);
    int        (*read)(hal_spi_t *spi, uint8_t *rx, size_t len);
} hal_spi_ops_t;

// Each platform registers its ops
extern const hal_spi_ops_t hal_spi_ops;

// Application code calls through the table
#define hal_spi_transfer(spi, tx, rx, len) hal_spi_ops.transfer(spi, tx, rx, len)

Pros: You can swap implementations at link time or at runtime. Makes mocking trivial for tests — just plug in a mock ops table. This is essentially what Zephyr does under the hood.

Cons: One level of pointer indirection per call. On a Cortex-M4 at 168 MHz, this is ~2-5 extra cycles — irrelevant for SPI (the bus itself is the bottleneck) but potentially meaningful for GPIO bit-banging in a tight loop.

Option C: C++ Virtual Dispatch (vtable)

If you're in C++ land:

class ISpiDriver {
public:
    virtual ~ISpiDriver() = default;
    virtual int transfer(const uint8_t *tx, uint8_t *rx, size_t len) = 0;
    virtual int write(const uint8_t *tx, size_t len) = 0;
};

class Stm32SpiDriver : public ISpiDriver { /* ... */ };
class Nrf52SpiDriver : public ISpiDriver { /* ... */ };

This is functionally identical to Option B but with language support for the dispatch. Same overhead, slightly cleaner syntax, and you get type safety on the ops table for free. The downside is that many embedded teams avoid C++ virtual dispatch because the vtable pointer adds 4 bytes per object instance, and the compiler-generated vtable code is harder to audit in safety-critical contexts.

Option D: Preprocessor Switching

// hal_spi.h
#if defined(PLATFORM_STM32)
    #include "hal/stm32/hal_spi_stm32_inline.h"
#elif defined(PLATFORM_NRF52)
    #include "hal/nrf52/hal_spi_nrf52_inline.h"
#endif

This is compile-time dispatch with the implementations inlined into the header. Maximum performance (everything can be inlined and optimized), but it means your public headers pull in vendor headers transitively. The whole point of the abstraction was to avoid this. Use this only for truly hot-path operations where the function call overhead is measured and proven to matter.

What I'd Actually Recommend

After shipping firmware on STM32, nRF, TI, and Renesas parts, here's my practical decision tree:

If you're starting a new product with potential for MCU changes (most products):

Use compile-time dispatch (Option A) with the opaque handle pattern. Define your own types. One .c per platform, selected by the build system. This gives you zero overhead, clean separation, and easy porting. When you need to test, add a hal/mock/ platform with stub implementations.

If you're building a framework or SDK that ships to other developers:

Use function pointer tables (Option B). Your users might need to mock, extend, or substitute drivers. The pointer indirection cost is negligible for anything above bit-bang-speed peripherals. This is the right tradeoff for flexibility.

If you're already using Zephyr or considering an RTOS:

Just use Zephyr's driver model. Seriously. Don't build a second HAL on top of Zephyr's HAL — that's two layers of abstraction for the same job. Zephyr's device tree + driver API is the most well-designed HAL in the ecosystem. The cost is adopting Zephyr, but if you're already there, you've already paid it.

If your product will only ever run on one MCU family:

Don't build a HAL at all. Use the vendor HAL (STM32 HAL, nrfx, ESP-IDF drivers) directly. A HAL is insurance against hardware changes. If that risk is genuinely zero, the insurance premium (development time, code complexity, debugging difficulty) isn't worth paying.

Common Mistakes

A few patterns I've seen fail repeatedly:

Leaking vendor types through "convenience" macros. Someone adds #define MY_SPI hspi1 and now every file that uses MY_SPI transitively depends on ST's headers. The macro looked harmless. It wasn't.

Over-abstracting initialization. Init is where platforms differ the most (clock trees, pin muxing, DMA channel allocation). Trying to make init generic leads to massive config structs that are just as vendor-specific as the original API but harder to understand. Let init be platform-specific. Abstract the operations, not the setup.

Abstracting too early. Don't build a HAL on day one of a project. Write directly against the vendor HAL, get the product working, then extract the abstraction boundary once you can see which operations are actually used. Premature abstraction creates APIs that don't match real usage patterns.

Ignoring error semantics. STM32 HAL returns HAL_StatusTypeDef (OK, ERROR, BUSY, TIMEOUT). nrfx returns nrfx_err_t. ESP-IDF returns esp_err_t. If your HAL just returns int with 0 for success and -1 for failure, you've lost the ability to distinguish between "bus busy, retry later" and "hardware fault, pin not configured." Define your own error codes that capture the categories your application actually needs to handle.

The Test Story

The strongest argument for a clean HAL isn't portability — it's testability. With the opaque handle pattern and compile-time dispatch, you can create a hal/mock/ implementation that:

Records every call (what was written, to which pin/bus)
Returns scripted responses (inject error conditions)
Validates sequencing (CS asserted before transfer, released after)
Runs on your development machine, not on target hardware

This means your application logic — the part that talks to sensors, runs protocols, makes decisions — can be tested on x86 with a standard test framework. No JTAG required. No waiting for hardware. No "it works on my board" debugging.

// hal/mock/hal_spi_mock.c
static struct {
    uint8_t tx_log[4096];
    size_t  tx_log_pos;
    uint8_t rx_script[4096];
    size_t  rx_script_pos;
    int     next_error;
} mock_state;

int hal_spi_transfer(hal_spi_t *spi, const uint8_t *tx, uint8_t *rx, size_t len) {
    if (mock_state.next_error) {
        int err = mock_state.next_error;
        mock_state.next_error = 0;
        return err;
    }
    memcpy(&mock_state.tx_log[mock_state.tx_log_pos], tx, len);
    mock_state.tx_log_pos += len;
    memcpy(rx, &mock_state.rx_script[mock_state.rx_script_pos], len);
    mock_state.rx_script_pos += len;
    return 0;
}

// Test helper: inject an error on the next call
void mock_spi_set_next_error(int err) {
    mock_state.next_error = err;
}

This mock compiles and runs on any platform. Your CI pipeline catches protocol bugs before hardware is even available. That's the real payoff of a well-designed HAL.

Closing Thoughts

The best HAL is the one your team can actually maintain. I've seen beautiful, theoretically perfect abstractions that nobody understood and everyone worked around. I've also seen ugly #ifdef forests that somehow shipped reliable products for a decade.

The principles that matter:

Your types at the boundary. Vendor types stay in platform files.
Opaque handles. Application code can't reach into hardware-specific fields.
Abstract operations, not init. Let setup be messy and platform-specific.
Compile-time dispatch by default. Add indirection only when you have a concrete reason.
Mock-friendly from day one. If you can't test it on x86, your abstraction has holes.

The goal isn't a perfect universal API. The goal is that when — not if — you need to swap silicon, the damage is contained to a set of well-defined platform files, and your application logic doesn't change.

That's a HAL that doesn't lock you in.

Pranav Jain is a semiconductor software engineer specializing in the abstraction layer between customer applications and firmware. He works with C++, Python, and embedded systems across multiple MCU platforms. Find his open-source work on GitHub.

10 Mistakes Companies Make When Porting Firmware Between MCU Families

Pranav Jain — Thu, 20 Aug 2026 09:44:33 +0000

I've spent years working in the layer between customer software and firmware — the middleware that has to survive MCU swaps, silicon shortages, and last-minute BOM changes. I've watched teams burn weeks on firmware ports that should have taken days, and I've done enough post-mortems to see the same mistakes repeat across companies.

These aren't theoretical. Every mistake below comes from real porting efforts I've seen or been called in to fix. Most involve moving between STM32, ESP32, and nRF52 — the three families that cover probably 80% of new embedded designs in 2026.

If you're planning a firmware port (or trying to build firmware that won't need a painful port later), this is the list I wish someone had given me five years ago.

Mistake 1: Copy-Pasting Vendor HAL Calls Into Application Logic

This is the original sin of firmware porting. Engineers write application code that directly calls HAL_SPI_Transmit() or nrf_drv_spi_transfer() in business logic functions. When the MCU changes, every file that touches a peripheral has to be rewritten.

The mistake:

// sensor_driver.c — STM32 version
#include "stm32f4xx_hal.h"

extern SPI_HandleTypeDef hspi1;

int sensor_read_temperature(uint16_t *temp_raw) {
    uint8_t cmd = 0xD0;
    uint8_t buf[2];

    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_4, GPIO_PIN_RESET); // CS low
    HAL_SPI_Transmit(&hspi1, &cmd, 1, 100);
    HAL_SPI_Receive(&hspi1, buf, 2, 100);
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_4, GPIO_PIN_SET);   // CS high

    *temp_raw = (buf[0] << 8) | buf[1];
    return 0;
}

Now you need to port to nRF52. Every line of this function changes. The SPI API is different, the GPIO API is different, and the pin numbering is completely different. Multiply this by 30 sensor/actuator functions and you're looking at a week of tedious, error-prone work.

The fix: Wrap peripheral access behind a thin abstraction. The application code calls your API, not the vendor's.

// hal_spi.h — your abstraction
typedef struct hal_spi* hal_spi_t;

int hal_spi_init(hal_spi_t *handle, const hal_spi_config_t *cfg);
int hal_spi_transfer(hal_spi_t handle, const uint8_t *tx, uint8_t *rx, size_t len);
int hal_spi_cs_assert(hal_spi_t handle);
int hal_spi_cs_deassert(hal_spi_t handle);

// sensor_driver.c — portable version
int sensor_read_temperature(hal_spi_t spi, uint16_t *temp_raw) {
    uint8_t cmd = 0xD0;
    uint8_t buf[2];

    hal_spi_cs_assert(spi);
    hal_spi_transfer(spi, &cmd, NULL, 1);
    hal_spi_transfer(spi, NULL, buf, 2);
    hal_spi_cs_deassert(spi);

    *temp_raw = (buf[0] << 8) | buf[1];
    return 0;
}

Now porting means writing one new hal_spi_nrf52.c backend. The sensor driver doesn't change at all. This is the single highest-ROI investment in any firmware architecture.

Mistake 2: Hardcoding Interrupt Priorities

STM32 uses a 4-bit priority field (0-15, where 0 is highest). nRF52 uses 3 bits (0-7). ESP32's interrupt system is completely different — it uses levels 1-6 with dedicated high-priority interrupts that can only run from IRAM.

The mistake:

// stm32_setup.c
void setup_interrupts(void) {
    HAL_NVIC_SetPriority(USART1_IRQn, 5, 0);  // UART at priority 5
    HAL_NVIC_SetPriority(SPI1_IRQn, 3, 0);    // SPI at priority 3
    HAL_NVIC_SetPriority(TIM2_IRQn, 1, 0);    // Timer at priority 1 (high)
    HAL_NVIC_SetPriority(EXTI0_IRQn, 2, 0);   // External interrupt at 2
}

Port this to nRF52 and priorities 5 and above don't exist — the maximum is 7, but the SoftDevice (BLE stack) reserves priorities 0, 1, and 4. Your "high priority" timer at 1 now collides with the SoftDevice and causes random BLE disconnections that take a week to debug.

The fix: Define priority levels semantically and map them per platform.

// irq_priorities.h
typedef enum {
    IRQ_PRIO_CRITICAL,   // timing-critical, cannot be preempted
    IRQ_PRIO_HIGH,       // fast peripherals (SPI, timer callbacks)
    IRQ_PRIO_MEDIUM,     // standard peripherals (UART, I2C)
    IRQ_PRIO_LOW,        // background tasks (ADC, low-rate sensors)
} irq_priority_level_t;

// irq_priorities_stm32.h
#define IRQ_PRIO_MAP_CRITICAL  1
#define IRQ_PRIO_MAP_HIGH      3
#define IRQ_PRIO_MAP_MEDIUM    5
#define IRQ_PRIO_MAP_LOW       8

// irq_priorities_nrf52.h (SoftDevice reserves 0, 1, 4)
#define IRQ_PRIO_MAP_CRITICAL  2
#define IRQ_PRIO_MAP_HIGH      3
#define IRQ_PRIO_MAP_MEDIUM    5
#define IRQ_PRIO_MAP_LOW       6

Document which priority levels the BLE/Wi-Fi stack reserves. This avoids the most common source of "it works on STM32 but randomly crashes on nRF52" bugs.

Mistake 3: Assuming Memory Layout Is Portable

STM32F4 has a flat memory map — flash, SRAM, and peripherals all in one address space. ESP32 has instruction RAM (IRAM), data RAM (DRAM), SPI flash with caching, and RTC slow memory. nRF52 has flash, RAM, and the SoftDevice sitting in the first chunk of both.

The mistake:

// Works on STM32 — a function pointer stored in flash and called normally
typedef void (*callback_t)(void);

const callback_t isr_table[] __attribute__((section(".rodata"))) = {
    handler_timer,
    handler_spi,
    handler_uart,
};

// On ESP32, this crashes. Functions called from interrupts MUST be in IRAM,
// not flash. Flash access is disabled during SPI operations and cache misses
// cause exceptions in ISR context.

The fix for ESP32:

// ESP32 — ISR handlers must be in IRAM
void IRAM_ATTR handler_timer(void *arg) {
    // This function lives in IRAM, safe to call from interrupts
    // IMPORTANT: anything this function calls must also be in IRAM
    // or be inlined. No calls to flash-resident code.
    gpio_set_level(LED_PIN, 1);  // gpio_set_level is IRAM-safe
}

// Do NOT call printf, logging functions, or anything that
// accesses flash from an IRAM_ATTR function

On nRF52 with SoftDevice, the first ~116KB of flash and ~8KB of RAM are owned by the SoftDevice. Your linker script must start application code after the SoftDevice region, and the size changes between SoftDevice versions (S132 v7.0 vs v7.2 have different sizes). I've seen boards that worked perfectly until a SoftDevice update shifted the memory map and the application overwrote SoftDevice data.

Build a memory map document for each target. Not in someone's head — in a file checked into the repo. Include reserved regions, stack sizes, and heap configuration.

Mistake 4: Ignoring Clock Tree Differences

Every MCU family has a different clock tree, and peripherals derive their clocks from different sources. A SPI peripheral running at 8 MHz on STM32 might end up at 6.67 MHz or 10 MHz on nRF52 because the available dividers are different.

The mistake:

// STM32: APB2 clock is 84 MHz, SPI prescaler = 16 → 5.25 MHz SPI clock
spi_handle.Init.BaudRatePrescaler = SPI_BAUDRATEPRESCALER_16;

// nRF52: SPI frequency options are discrete:
// 125K, 250K, 500K, 1M, 2M, 4M, 8M
// There is no 5.25 MHz option. Engineer picks 8M and the
// sensor can't handle it. Or picks 4M and the data rate
// is too slow for the application.

This is worse for UART. STM32 can generate almost any baud rate from its flexible prescalers. nRF52 generates baud rates from a 16 MHz clock with limited dividers — 115200 baud actually runs at 115942 baud (0.64% error). For most UART devices this is fine, but I've seen it cause framing errors with picky GPS modules that barely tolerate 0.5% error.

The fix: Specify peripheral speeds as requirements (minimum and maximum), not as exact register values.

// peripheral_config.h — specify intent, not register values
typedef struct {
    uint32_t freq_min_hz;   // minimum acceptable clock
    uint32_t freq_max_hz;   // maximum acceptable clock
    uint32_t freq_target_hz; // ideal clock
} spi_clock_requirement_t;

// The platform-specific init code finds the best available
// divider and logs a warning if it falls outside the range.
int hal_spi_init(hal_spi_t *handle, const hal_spi_config_t *cfg) {
    uint32_t actual_freq = find_closest_spi_freq(cfg->clock.freq_target_hz);
    if (actual_freq < cfg->clock.freq_min_hz ||
        actual_freq > cfg->clock.freq_max_hz) {
        LOG_WARN("SPI%d: requested %u Hz, got %u Hz (out of range)",
                 cfg->instance, cfg->clock.freq_target_hz, actual_freq);
        return -EINVAL;
    }
    LOG_INFO("SPI%d: configured at %u Hz (target: %u Hz)",
             cfg->instance, actual_freq, cfg->clock.freq_target_hz);
    // ... configure the peripheral
    return 0;
}

Mistake 5: Porting the RTOS Configuration Verbatim

Teams running FreeRTOS on STM32 copy their FreeRTOSConfig.h to the ESP32 build and wonder why things break. The problem: ESP32's FreeRTOS is a fork by Espressif (ESP-IDF FreeRTOS) that adds symmetric multiprocessing, has different defaults for tick rate, and uses a different idle task hook mechanism.

The mistake:

// FreeRTOSConfig.h — copied from STM32 project
#define configUSE_PREEMPTION         1
#define configTICK_RATE_HZ           1000
#define configMINIMAL_STACK_SIZE     128  // in words (512 bytes on ARM)
#define configTOTAL_HEAP_SIZE        (32 * 1024)
#define configUSE_TICKLESS_IDLE      1

Problems when this lands on ESP32:

configMINIMAL_STACK_SIZE of 128 words (512 bytes) is dangerously small on ESP32 — ESP-IDF tasks typically need 2048-4096 bytes minimum because of deeper call stacks in the Wi-Fi/BLE stack.
configTOTAL_HEAP_SIZE is ignored — ESP32 uses its own multi-region heap allocator.
configUSE_TICKLESS_IDLE interacts badly with Wi-Fi power management on ESP32.

On nRF52 with SoftDevice, you can't use FreeRTOS's standard vPortSVCHandler and xPortPendSVHandler — the SoftDevice owns those interrupt vectors. You need the nRF52-specific FreeRTOS port that routes through the SoftDevice.

The fix: Treat RTOS configuration as platform-specific. Keep a base config with shared application-level settings (task priorities, queue sizes) and a platform config with hardware-dependent values.

// rtos_config_common.h — shared across all platforms
#define APP_TASK_PRIORITY_SENSOR     3
#define APP_TASK_PRIORITY_COMMS      4
#define APP_TASK_PRIORITY_CONTROL    5
#define APP_QUEUE_SIZE_SENSOR        16
#define APP_QUEUE_SIZE_CMD           8

// rtos_config_stm32.h
#define PLATFORM_MIN_STACK_SIZE      512   // bytes
#define PLATFORM_DEFAULT_STACK_SIZE  1024
#define PLATFORM_TICK_RATE_HZ        1000
#define PLATFORM_USE_TICKLESS_IDLE   1

// rtos_config_esp32.h
#define PLATFORM_MIN_STACK_SIZE      2048  // ESP-IDF needs more
#define PLATFORM_DEFAULT_STACK_SIZE  4096
#define PLATFORM_TICK_RATE_HZ        100   // ESP-IDF default
#define PLATFORM_USE_TICKLESS_IDLE   0     // conflicts with Wi-Fi PM

Mistake 6: Not Auditing DMA Channel Allocation

DMA is one of the least portable subsystems across MCU families. STM32F4 has 2 DMA controllers with 8 streams each, and each stream can connect to specific peripherals via a request mapping table. nRF52 uses EasyDMA, which is peripheral-specific — each peripheral (SPI, I2C, UART) has its own DMA tied to it. ESP32 uses a GDMA controller where channels are dynamically assignable.

The mistake:

// STM32: manually assign DMA stream to SPI
// DMA1 Stream 3, Channel 0 → SPI2_RX (from reference manual)
hdma_spi2_rx.Instance = DMA1_Stream3;
hdma_spi2_rx.Init.Channel = DMA_CHANNEL_0;
hdma_spi2_rx.Init.Direction = DMA_PERIPH_TO_MEMORY;
// ...

// Engineer ports to nRF52 and tries to find equivalent DMA channels.
// There are none. nRF52's EasyDMA is built into each peripheral.
// You configure it by setting the TXD.PTR, TXD.MAXCNT, RXD.PTR, RXD.MAXCNT
// registers on the SPIM peripheral itself.

The fix: Abstract DMA as a property of the peripheral, not a separate subsystem.

// Your SPI config struct should express whether DMA is desired,
// not which DMA channel to use
typedef struct {
    uint8_t instance;          // SPI0, SPI1, etc.
    uint32_t freq_hz;
    bool use_dma;              // platform code handles the details
    size_t dma_threshold;      // only use DMA for transfers > N bytes
} hal_spi_config_t;

// hal_spi_stm32.c — DMA setup is internal
static int setup_dma_for_spi(uint8_t spi_instance, dma_handles_t *dma) {
    // Look up DMA stream/channel from a mapping table
    const dma_mapping_t *map = get_spi_dma_mapping(spi_instance);
    if (!map) {
        LOG_WARN("No DMA available for SPI%d, falling back to polling", spi_instance);
        return -ENOTSUP;
    }
    // ... configure DMA
    return 0;
}

// hal_spi_nrf52.c — EasyDMA is automatic, just set the buffer pointers
// No separate DMA configuration needed

The key insight: on some platforms DMA is a separate resource you must manage; on others it's transparent. Your abstraction should hide this difference.

Mistake 7: Forgetting That GPIO Numbering Means Different Things

STM32 uses port+pin (GPIOA pin 5). nRF52 uses a flat numbering scheme (P0.05, P0.13, P1.09). ESP32 uses GPIO numbers (GPIO_NUM_18) that may or may not correspond to the physical pin on the package. On top of this, pin muxing rules differ — STM32 has alternate function registers, nRF52 lets you route most peripherals to any pin, and ESP32 uses a GPIO matrix with some restrictions on certain functions.

The mistake:

// Scattered across the codebase, different files:
#define LED_PIN    GPIO_PIN_5       // Which port? GPIOA? GPIOB?
#define BUTTON_PIN 13               // Is this a port pin or a flat GPIO number?
#define SPI_CS     4                // 4 on which port?

This is ambiguous even on a single platform. During a port, it's a nightmare.

The fix: One file, one table, fully qualified.

// board_pinmap.h — ONE file defines ALL pin assignments for a board
// This file is the ONLY thing that changes when the PCB changes

#if defined(BOARD_CUSTOM_STM32F4)
    #define PIN_LED_STATUS     { .port = GPIOA, .pin = 5 }
    #define PIN_BUTTON_USER    { .port = GPIOC, .pin = 13 }
    #define PIN_SPI_SENSOR_CS  { .port = GPIOA, .pin = 4 }
    #define PIN_UART_DEBUG_TX  { .port = GPIOA, .pin = 2 }
    #define PIN_UART_DEBUG_RX  { .port = GPIOA, .pin = 3 }

#elif defined(BOARD_CUSTOM_NRF52840)
    // nRF52 uses flat pin numbers: port * 32 + pin
    #define PIN_LED_STATUS     NRF_GPIO_PIN_MAP(0, 13)
    #define PIN_BUTTON_USER    NRF_GPIO_PIN_MAP(0, 11)
    #define PIN_SPI_SENSOR_CS  NRF_GPIO_PIN_MAP(1, 8)
    #define PIN_UART_DEBUG_TX  NRF_GPIO_PIN_MAP(0, 6)
    #define PIN_UART_DEBUG_RX  NRF_GPIO_PIN_MAP(0, 8)

#elif defined(BOARD_CUSTOM_ESP32S3)
    #define PIN_LED_STATUS     GPIO_NUM_2
    #define PIN_BUTTON_USER    GPIO_NUM_0
    #define PIN_SPI_SENSOR_CS  GPIO_NUM_10
    #define PIN_UART_DEBUG_TX  GPIO_NUM_43
    #define PIN_UART_DEBUG_RX  GPIO_NUM_44

#else
    #error "No board defined — add your pin map"
#endif

When you port to a new board, you add one #elif block. Nothing else in the codebase mentions pin numbers.

Mistake 8: Testing Only the Happy Path After Porting

The firmware boots, the LED blinks, SPI reads return data, UART prints work. Ship it, right? No. The failure modes are where ports break.

What gets missed:

Peripheral error recovery. STM32's HAL sets error flags on hspi.ErrorCode — your error handler clears them and retries. nRF52's SPIM peripheral uses event registers (EVENTS_STOPPED) that work differently. Your error recovery code from STM32 does nothing on nRF52, so the first bus error hangs the SPI peripheral forever.
Timing edge cases. A watchdog timer that worked with STM32's 32 kHz LSI oscillator (which has +/- 10% accuracy) may trip on nRF52's 32.768 kHz crystal (much more accurate), or vice versa, depending on how you calculated the timeout.
Power state transitions. Sleep/wake behavior is wildly different. STM32 has STOP, STANDBY, and SHUTDOWN modes. nRF52 has System ON (idle with RAM retention) and System OFF. ESP32 has light sleep, deep sleep, and hibernation. Your "wake from sleep" code is not portable.
Stack overflow under load. A task that used 400 bytes of stack on STM32 might use 800 on ESP32 due to deeper call chains in ESP-IDF library functions.

The fix: Build a porting test checklist and run it on every target.

// port_validation_tests.c — run on each new target
void test_spi_error_recovery(void) {
    // Intentionally cause a bus error (disconnect MISO)
    // Verify the driver detects and recovers
    hal_spi_transfer(spi, tx, rx, 4);
    assert(hal_spi_get_error(spi) != HAL_ERR_NONE);
    hal_spi_reset(spi);
    // Verify SPI works again after recovery
    int ret = hal_spi_transfer(spi, tx, rx, 4);
    assert(ret == 0);
}

void test_watchdog_timing(void) {
    // Start watchdog with 2-second timeout
    hal_wdt_start(2000);
    // Sleep for 1.9 seconds — should NOT trigger
    hal_delay_ms(1900);
    hal_wdt_feed();
    // If we get here, the watchdog timing is correct on this platform
}

void test_sleep_wake_integrity(void) {
    volatile uint32_t canary = 0xDEADBEEF;
    hal_enter_sleep(SLEEP_MODE_LIGHT);
    // ... external interrupt wakes us
    assert(canary == 0xDEADBEEF);  // RAM retained?
    assert(hal_spi_transfer(spi, tx, rx, 4) == 0);  // peripherals re-inited?
}

Mistake 9: Trying to Port Everything at Once

I've seen teams attempt to port an entire 50-file firmware project in one shot. They create a new target in the build system, switch all the HAL calls, and then spend three weeks debugging because nothing works and they have no idea which change broke what.

The fix: Port in layers, bottom-up, validating at each step.

Week 1: Board bring-up. Get the chip running — clock config, a blinking LED, and printf over UART. Nothing else. If this doesn't work, you can't debug anything above it.
Week 2: Peripheral drivers. Port one peripheral at a time. SPI first (because sensors usually need it), then I2C, then timers, then DMA. Test each one in isolation with a simple loopback or sensor read before moving on.
Week 3: RTOS + middleware. Bring up FreeRTOS (or Zephyr, or your RTOS of choice) with a single task. Verify scheduling, then add tasks one at a time. Verify inter-task communication (queues, semaphores) before adding application logic.
Week 4: Application logic. If your abstraction layer is done right, this step should require zero changes to application code. If it requires changes, your abstraction leaked — fix the abstraction, don't patch the application.

Commit at each step. If step 3 breaks something, you can diff against step 2 and see exactly what changed.

Mistake 10: No Automated Build for Multiple Targets

After the port, you have two (or more) targets. Developers work on one target and forget to compile the other. Six months later someone tries to build the second target and it's broken — header files moved, function signatures changed, a new module was added without a platform implementation.

The mistake:

# "Just build the one you're working on"
make TARGET=stm32f4
# Nobody runs this for months:
make TARGET=nrf52840
# It's been broken since March

The fix: CI that builds every target on every commit.

# .github/workflows/firmware-build.yml
name: Multi-target firmware build
on: [push, pull_request]

jobs:
  build:
    strategy:
      matrix:
        target: [stm32f4, nrf52840, esp32s3]
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/your-org/firmware-toolchain:latest
    steps:
      - uses: actions/checkout@v4
      - name: Build ${{ matrix.target }}
        run: make TARGET=${{ matrix.target }}
      - name: Run unit tests
        run: make test TARGET=${{ matrix.target }}

If you don't have CI, at minimum add a build_all.sh script and run it before every merge. The 30 seconds it takes to compile both targets saves the hours it takes to fix a broken build that drifted for months.

The Common Thread

Every one of these mistakes comes from the same root cause: treating firmware porting as a search-and-replace exercise instead of an architecture problem.

The time to make firmware portable is before you need to port it. The second best time is when you're planning the port — before you start changing code. An afternoon spent mapping out peripheral differences, memory layouts, and interrupt schemes saves weeks of debugging.

If you're facing a port right now and the codebase has no abstraction layer, resist the temptation to "just get it working" on the new target by copy-pasting and patching. You'll end up maintaining two divergent codebases. Take the time to extract an abstraction layer during the port — it's the last time you'll need to do this work.

Cross-MCU Migration: A Practical Guide

Pranav Jain — Thu, 20 Aug 2026 09:44:09 +0000

You've been told to port the firmware from one MCU to another. Maybe the chip went EOL. Maybe the shortage made it unavailable. Maybe the new product variant needs Bluetooth and your current MCU doesn't have it.

Whatever the reason, you're staring at tens of thousands of lines of C that were written for one specific chip, and you need them running on a different one. This guide is the process I follow. It won't make the port painless, but it'll keep you from wasting time on the wrong things.

Before You Touch Any Code

Step 0: Understand the Target

Before you change a single line, answer these questions about the target MCU:

Question	Why It Matters
What's the clock tree look like?	Peripheral speeds, PLL config, clock domains are never the same
What DMA model does it use?	Linked-list DMA vs channel-based vs no DMA — big architectural impact
What's the interrupt priority scheme?	ARM NVIC is standard, but the number of priority levels and grouping differs
What SDK/HAL does the vendor provide?	STM32 HAL vs nRF Connect SDK vs ESP-IDF — completely different philosophies
What's the flash/RAM budget?	Tight MCUs may need code restructuring
What RTOS does the vendor SDK expect?	nRF Connect SDK assumes Zephyr. ESP-IDF has FreeRTOS built in. STM32 HAL is RTOS-agnostic.

Spend a day on this. Read the reference manual's clock tree and peripheral overview sections. It saves weeks later.

Step 1: Dependency Audit

This is the most important step. Catalog every vendor-specific dependency in your codebase.

# Quick audit for STM32 HAL dependencies
grep -rn "HAL_\|LL_\|__HAL_\|stm32" src/ --include="*.c" --include="*.h" | \
  grep -v "// " | \
  sort -t: -k1,1 | \
  uniq -c | sort -rn > hal_dependencies.txt

# Count by peripheral type
grep -oP "HAL_(GPIO|SPI|I2C|UART|TIM|DMA|ADC|DAC|RCC|PWR|FLASH|RTC|IWDG|WWDG|CAN|USB|ETH)" \
  hal_dependencies.txt | sort | uniq -c | sort -rn

Typical output:

    187 HAL_GPIO
    143 HAL_SPI
     98 HAL_I2C
     87 HAL_TIM
     76 HAL_UART
     54 HAL_DMA
     34 HAL_ADC
     29 HAL_RCC
     18 HAL_PWR
     12 HAL_FLASH
      8 HAL_RTC

This tells you where the work is. GPIO and SPI will take the most effort not because they're complex, but because there are the most call sites.

Step 2: Classify Each Dependency

Not all HAL calls are equal. Classify them:

Direct equivalents (green): The target MCU has a function that does exactly the same thing with different syntax. HAL_GPIO_WritePin() → nrf_gpio_pin_write(). These are mechanical translations.

Behavioral differences (yellow): The target MCU can do the same thing, but the API works differently. STM32's SPI uses handles and callbacks; nRF Connect SDK uses Zephyr's SPI API with transaction descriptors. You need to understand both models.

No equivalent (red): The target MCU doesn't have the feature, or implements it fundamentally differently. STM32's flexible DMA linked-list mode vs nRF52's EasyDMA which has a different set of constraints. These need redesign.

Migration Effort Matrix:

┌─────────────────────────────────────────────────┐
│  Peripheral   │  Calls  │ Class  │ Est. Effort  │
├───────────────┼─────────┼────────┼──────────────┤
│  GPIO         │   187   │ Green  │   1 day      │
│  SPI          │   143   │ Yellow │   3 days     │
│  I2C          │    98   │ Yellow │   2 days     │
│  Timer        │    87   │ Yellow │   3 days     │
│  UART         │    76   │ Green  │   1 day      │
│  DMA          │    54   │ Red    │   5 days     │
│  ADC          │    34   │ Yellow │   2 days     │
│  Clock config │    29   │ Red    │   2 days     │
│  Power mgmt   │    18   │ Yellow │   1 day      │
│  Flash/NVM    │    12   │ Red    │   2 days     │
│  RTC          │     8   │ Green  │   0.5 days   │
├───────────────┼─────────┼────────┼──────────────┤
│  TOTAL        │   746   │        │  ~22 days    │
└─────────────────────────────────────────────────┘

The Migration Process

Phase 1: Build System (Days 1-2)

Get the project compiling for the new target — even if nothing works yet.

# CMakeLists.txt — add target selection
set(TARGET_MCU "stm32f4" CACHE STRING "Target MCU family")
set_property(CACHE TARGET_MCU PROPERTY STRINGS stm32f4 nrf52840 esp32s3)

if(TARGET_MCU STREQUAL "nrf52840")
    set(CMAKE_TOOLCHAIN_FILE ${NRF_SDK_PATH}/toolchain.cmake)
    add_subdirectory(hal/nrf52)
elseif(TARGET_MCU STREQUAL "stm32f4")
    add_subdirectory(hal/stm32)
endif()

# Application code is the SAME regardless of target
add_subdirectory(application)
target_link_libraries(application PRIVATE hal)

If you're migrating to a Zephyr-based SDK (nRF Connect), you'll need to restructure into a Zephyr application. This is a bigger lift:

my_project/
├── CMakeLists.txt      # Zephyr-style CMake
├── prj.conf            # Kconfig
├── boards/             # Board overlays
│   ├── nrf52840dk_nrf52840.overlay
│   └── nucleo_f429zi.overlay
├── src/
│   └── main.c
└── hal/                # Your abstraction (if not using Zephyr's drivers directly)

Phase 2: Clock Tree and Startup (Days 2-3)

This is where most estimates go wrong. Every MCU has a different clock tree, and getting it wrong produces bizarre failures later.

STM32: CubeMX generates SystemClock_Config(). Clock tree has HSE/HSI → PLL → SYSCLK → AHB/APB prescalers.

nRF52: Simpler clock model. HFCLK (64 MHz, from crystal or RC) and LFCLK (32.768 kHz). Less configurable but less error-prone.

ESP32: Dual-core, much more complex. PLL, CPU frequency, APB frequency, RTC clocks.

Don't try to match clock-for-clock. Understand what frequencies your peripherals need and configure the target's clock tree to deliver them.

// STM32: complex clock config generated by CubeMX
void SystemClock_Config(void) {
    RCC_OscInitTypeDef RCC_OscInitStruct = {0};
    RCC_ClkInitTypeDef RCC_ClkInitStruct = {0};
    // ... 40 lines of clock configuration
}

// nRF52: much simpler
// Most clock setup happens automatically via Zephyr's devicetree
// or a few register writes
void clock_init(void) {
    NRF_CLOCK->TASKS_HFCLKSTART = 1;
    while (!NRF_CLOCK->EVENTS_HFCLKSTARTED);
}

Phase 3: Green Peripherals First (Days 3-5)

Start with the easy wins. GPIO, UART, basic timers.

GPIO migration between any two Cortex-M MCUs is mostly mechanical:

// STM32 → nRF52 GPIO mapping
// HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET)
// becomes:
// nrf_gpio_pin_set(NRF_GPIO_PIN_MAP(0, 5))

// Or if you have an abstraction layer:
// gpio_write((gpio_pin_t){0, 5}, 1)  // same call, different backend

Get LEDs blinking and UART printing. This validates your build system, startup code, and basic peripheral access. Everything else builds on this.

Phase 4: Yellow Peripherals (Days 5-15)

SPI, I2C, and timers usually have behavioral differences that require understanding both MCU's models.

SPI example: STM32 → nRF52 (Zephyr)

// STM32 HAL SPI
HAL_SPI_TransmitReceive(&hspi1, tx_buf, rx_buf, len, HAL_MAX_DELAY);

// Zephyr SPI (used by nRF Connect SDK)
struct spi_buf tx = {.buf = tx_buf, .len = len};
struct spi_buf rx = {.buf = rx_buf, .len = len};
struct spi_buf_set tx_set = {.buffers = &tx, .count = 1};
struct spi_buf_set rx_set = {.buffers = &rx, .count = 1};
spi_transceive(spi_dev, &spi_cfg, &tx_set, &rx_set);

The API model is completely different (handle+callback vs device+descriptor), but the functionality is the same. Don't try to write a compatibility wrapper that makes Zephyr's API look like STM32's. Learn the target's API and use it idiomatically.

Phase 5: Red Peripherals (Days 15-22)

DMA, complex timers, and power management. These are where the real work is.

DMA is the biggest headache. Every MCU family implements DMA differently:

STM32: DMA streams/channels, each assignable to specific peripherals. Flexible but complex.
nRF52: EasyDMA, tightly integrated with each peripheral. Less flexible but simpler.
ESP32: GDMA with channel allocation. Different yet again.

There is no mechanical translation. You need to understand what the DMA was doing (circular buffer? ping-pong? linked list?) and redesign it for the target's DMA model.

// STM32: DMA circular buffer for ADC
hdma_adc.Init.Mode = DMA_CIRCULAR;
hdma_adc.Init.MemInc = DMA_MINC_ENABLE;
HAL_DMA_Start(&hdma_adc, (uint32_t)&ADC1->DR, (uint32_t)adc_buf, ADC_BUF_LEN);

// nRF52: SAADC with EasyDMA — completely different model
nrfx_saadc_buffer_set(adc_buf, ADC_BUF_LEN);
// EasyDMA handles the transfer internally — no separate DMA config

Phase 6: Integration Testing (Days 22-25)

Once all peripherals are ported, test the system as a whole:

Peripheral smoke test: Each peripheral works in isolation
Communication test: SPI/I2C devices respond correctly
Timing test: Real-time operations meet deadlines
Power test: Sleep modes work, current consumption is acceptable
Stress test: Run for 48 hours, check for memory leaks, watchdog resets

Phase 7: Edge Cases (Days 25-28)

These are what catches teams 3 weeks into testing:

Interrupt priority differences: STM32 has 16 priority levels, nRF52 has 4 (in some configs). If your original code relied on fine-grained priorities, you need to restructure.
Byte ordering in peripheral registers: Usually the same (little-endian ARM), but DMA scatter-gather can expose ordering issues.
Startup timing: Some peripherals need time to stabilize after power-on. Your original code might have had implicit delays from slow clock startup that the new MCU doesn't have.
Brownout behavior: Different MCUs handle power dips differently. Test power-off-power-on sequences.

The Estimation Formula

From my experience, here's a rough formula:

Estimated weeks = (LOC / 10000) × peripheral_complexity × abstraction_factor

where:
  peripheral_complexity = 1.0 (GPIO/UART only)
                        = 1.5 (+ SPI/I2C)
                        = 2.5 (+ DMA/complex timers)
                        = 4.0 (+ USB/Ethernet/RF)

  abstraction_factor = 0.3 (full HAL abstraction in place)
                     = 1.0 (no abstraction)
                     = 1.5 (spaghetti code, vendor types everywhere)

Example: 40K LOC, SPI+DMA, no abstraction = (40/10) × 2.5 × 1.0 = 10 weeks.

Add 30% for testing and edge cases. So ~13 weeks. If your manager says "4 weeks," show them this formula.

Tools That Help

grep / ripgrep: Fast dependency auditing
ctags / cscope: Navigate call chains to find hidden vendor dependencies
Compiler warnings: Build for the new target with -Wall -Werror early — the compiler will find most API mismatches
Git branches: Keep the original working on main, do the port on a branch. You'll need to compare.
CI with multiple targets: Build for both old and new target on every commit during the migration

What I'm Building

I'm working on a tool called PortPilot that automates the dependency audit and mapping phases (Steps 1-2 above). It scans your firmware, classifies every vendor HAL call, and generates a migration report showing what maps directly, what needs review, and what needs redesign.

It won't do the port for you — the red peripherals still need engineering judgment. But it cuts the audit from a week to an hour and makes sure you don't miss anything.

Pranav Jain is an embedded systems engineer specializing in the middleware layer between hardware and application software. Find him on GitHub.