DEV Community: Aliaksandr Liapin

Designing a HAL Abstraction That Actually Ports — Lessons from 3 MCU Families

Aliaksandr Liapin — Tue, 14 Apr 2026 03:57:40 +0000

"Just add a HAL layer" is the most common advice in embedded development. It's also the most under-explained. After porting a battery monitoring SDK across nRF52840, STM32L476, and ESP32-C3, here's what I learned about HAL design that actually works in practice.

The Problem

I needed to read battery voltage on three MCU families. Sounds simple — until you realize each one does it completely differently:

Platform	VDD Strategy	How it works
nRF52840	Direct SAADC	Internal mux connects VDD to the ADC. Read it like any channel.
STM32L476	VREFINT sensor	ADC measures a ~1.21V internal bandgap reference. Back-calculate VDD using factory calibration data stored in ROM.
ESP32-C3	Voltage divider	Can't read VDD at all. Route battery through external resistors to a GPIO pin.

Three fundamentally different approaches. Same end result: battery voltage in millivolts.

Attempt 1: The Giant #ifdef

The obvious first approach:

int read_battery_mv(void) {
#if defined(CONFIG_SOC_SERIES_NRF52X)
    // 30 lines of nRF SAADC code
#elif defined(CONFIG_SOC_SERIES_STM32L4X)
    // 40 lines of VREFINT sensor code
#elif defined(CONFIG_SOC_SERIES_ESP32C3)
    // 25 lines of voltage divider code
#endif
}

This works for two platforms. By three, it's unreadable. By four, it's unmaintainable. Every new feature means touching every #ifdef block.

What Actually Works: Separate the What from the How

The key insight: split platform constants from platform logic.

Layer 1: Platform Constants (one header)

A single header file defines what each platform needs — no logic, just values:

// battery_adc_platform.h

#if defined(CONFIG_SOC_SERIES_NRF52X)
    #define BATTERY_ADC_DT_NODE    DT_NODELABEL(adc)
    #define BATTERY_ADC_VDD_INPUT  NRF_SAADC_VDD
    #define BATTERY_ADC_VDD_GAIN   ADC_GAIN_1_6
    #define BATTERY_ADC_VDD_REF_MV 600

#elif defined(CONFIG_SOC_SERIES_STM32L4X)
    #define BATTERY_ADC_VDD_USE_VREFINT 1
    // No ADC config needed — uses Zephyr sensor driver

#elif defined(CONFIG_SOC_SERIES_ESP32C3)
    #define BATTERY_ADC_VDD_USE_DIVIDER    1
    #define BATTERY_ADC_VDD_DIVIDER_RATIO  2
    #define BATTERY_ADC_DT_NODE    DT_NODELABEL(adc0)
    #define BATTERY_ADC_VDD_INPUT  2  // GPIO2
    #define BATTERY_ADC_VDD_GAIN   ADC_GAIN_1_4
    #define BATTERY_ADC_VDD_REF_MV 2500
#endif

Adding a fourth platform means adding 5-10 lines to this one file.

Layer 2: Strategy Selection (one C file)

The ADC driver selects its strategy based on the flags from Layer 1:

// battery_hal_adc_zephyr.c

#if defined(BATTERY_ADC_VDD_USE_VREFINT)
    // STM32: use Zephyr vref sensor driver
    // sensor_sample_fetch() → sensor_channel_get(VOLTAGE) → mV

#elif defined(BATTERY_ADC_VDD_USE_DIVIDER)
    // ESP32: raw ADC read → adc_raw_to_millivolts() → multiply by ratio

#else
    // nRF52: raw ADC read → adc_raw_to_millivolts() → done
#endif

Each block is self-contained. They don't interact. You can read one without understanding the others.

Layer 3: Everything Above (zero platform awareness)

The voltage module, SoC estimator, telemetry collector, and BLE transport don't include any platform headers. They call:

int battery_hal_adc_read_raw(int16_t *raw_out);
int battery_hal_adc_raw_to_pin_mv(int16_t raw, int32_t *mv_out);

That's it. They don't know if the voltage came from SAADC, VREFINT, or a resistor divider. They don't care.

The Temperature Sensor Problem

Temperature was trickier. Each platform names its die temp sensor differently in the devicetree:

Platform	Node label
nRF52840	`temp`
STM32L476	`die_temp`
ESP32-C3	`coretemp`

The solution: a devicetree-driven fallback chain with zero CONFIG_SOC_SERIES_* checks:

#if DT_NODE_EXISTS(DT_NODELABEL(temp))
#define BATTERY_TEMP_NODE DT_NODELABEL(temp)
#elif DT_NODE_EXISTS(DT_NODELABEL(die_temp))
#define BATTERY_TEMP_NODE DT_NODELABEL(die_temp)
#elif DT_NODE_EXISTS(DT_NODELABEL(coretemp))
#define BATTERY_TEMP_NODE DT_NODELABEL(coretemp)
#endif

The rest of the file — sensor_sample_fetch(), sensor_channel_get(SENSOR_CHAN_DIE_TEMP) — is identical across all platforms. Zephyr's sensor API handles the underlying driver differences.

This pattern is more resilient than #ifdef chains. If a future platform uses temp (same as nRF), it works automatically with zero changes.

What I Got Wrong (and Fixed)

Mistake 1: Hardcoded ADC parameters

My first NTC thermistor driver had this:

#define NTC_ADC_ACQ_TIME  ADC_ACQ_TIME(ADC_ACQ_TIME_MICROSECONDS, 40)

Worked on nRF52840 and STM32. Crashed on ESP32-C3 — the driver only accepts ADC_ACQ_TIME_DEFAULT. Same for .calibrate = true and .oversampling = 4 in the ADC sequence struct.

Fix: platform-conditional defaults in the NTC driver. Lesson: even "standard" Zephyr APIs have platform-specific capabilities.

Mistake 2: Assuming VDD is readable

I designed the API around battery_hal_adc_read_raw() + battery_hal_adc_raw_to_pin_mv() — a raw ADC read followed by a conversion. This maps cleanly to nRF52 and ESP32.

But STM32's VREFINT path doesn't use the ADC driver at all — it uses the Zephyr sensor API (sensor_sample_fetch). The "raw" value is meaningless; the real millivolts come from the sensor channel.

I solved this by storing the computed millivolts in a global during read_raw() and returning them from raw_to_pin_mv(), ignoring the raw parameter. It's a pragmatic hack that keeps the interface stable.

A cleaner design would have been a single battery_hal_adc_read_mv(int32_t *mv_out) function. But by the time I hit this problem, the two-function API was used everywhere. The adapter pattern was the right tradeoff.

Mistake 3: NVS flash page size

I hardcoded the NVS sector size to 4096 bytes (nRF52840 flash page size). STM32L476 has 2048-byte pages. The fix: query it at runtime:

struct flash_pages_info page_info;
flash_get_page_info_by_offs(flash_dev, offset, &page_info);
nvs.sector_size = page_info.size;

Lesson: even infrastructure like flash storage has platform-specific geometry.

The Porting Checklist

After three ports, here's my checklist for adding a new platform:

Add platform section to battery_adc_platform.h (~10 lines)
- ADC node label, VDD input channel, gain, reference, strategy flag
- NTC channel, gain, reference
Create board overlay (app/boards/<board>.overlay)
- Enable ADC, temperature sensor, GPIO aliases
Create board config (app/boards/<board>.conf)
- Kconfig: temp source, BLE, charger pins
Check devicetree node labels
- Die temp sensor name? Add to the fallback chain if new.
- ADC node name? Add to NTC driver if different.
Test ADC sequence compatibility
- Does the platform support oversampling? Calibrate flag? Custom acquisition time?
Build and verify — no core module changes should be needed.

If step 6 requires core changes, the HAL interface is incomplete. Go back and fix the abstraction.

Results

Platform	Flash	RAM	Core code changes
nRF52840-DK	152 KB	30 KB	(original)
NUCLEO-L476RG	38 KB	10 KB	0
ESP32-C3 DevKitM	356 KB	138 KB	0

Zero core module, intelligence, telemetry, or transport changes across all three ports. Only HAL files and board configs.

Key Takeaways

Separate constants from logic. A platform header with just #defines is easy to extend. Logic with #ifdefs is not.
Use devicetree fallback chains instead of CONFIG_SOC_SERIES_* checks where possible. They're more resilient to new platforms.
Design for the weird platform. If you design your HAL around the easiest platform (nRF52's direct VDD read), the others won't fit. Design for the most constrained one and the simple cases fall out naturally.
Test on host, validate on hardware. 69 tests run in under 2 seconds without any embedded toolchain. Hardware validation is the final step, not the first.
The HAL boundary is where you'll find bugs. Most issues during porting were at the HAL edge — ADC parameters that don't transfer, node labels that differ, flash page sizes that vary. The core logic never broke.

How I Built a Portable Battery SDK That Runs on 3 MCU Platforms

Aliaksandr Liapin — Fri, 10 Apr 2026 06:03:39 +0000

Every battery-powered IoT project ends up reimplementing the same things: ADC voltage reading, SoC estimation, power state management, temperature monitoring. After doing this for the third time, I built a reusable SDK that handles all of it.

Watch the 4-minute demo

What is iBattery SDK?

It's an open-source C library (Apache 2.0) that provides a standardized battery intelligence layer for embedded devices running Zephyr RTOS. You init it with one call, and it gives you:

Voltage measurement with moving average filtering
State-of-Charge estimation via lookup table interpolation (CR2032 + LiPo)
Temperature monitoring (on-chip die sensor or external NTC thermistor)
Power state machine (ACTIVE → IDLE → SLEEP → CRITICAL, with charger integration)
BLE telemetry streaming to a Python gateway → InfluxDB → Grafana dashboard

The entire core uses ~48 bytes of static RAM, integer-only math, and zero heap allocation.

The Portability Challenge

The interesting part was making it run on 3 very different MCUs without changing any core code.

The HAL Abstraction

All platform-specific code lives behind a Hardware Abstraction Layer. The core modules only call HAL functions — they never include vendor headers. Porting to a new platform means implementing 5-6 HAL functions and adding board config files.

Three Different VDD Strategies

Each MCU reads battery voltage differently:

nRF52840 — reads VDD directly via the SAADC internal input. Simplest approach: configure gain and reference voltage, read the ADC.

STM32L476 — can't read VDD directly. Uses VREFINT: an internal ~1.21V bandgap reference. The ADC measures VREFINT against VDDA, and factory calibration data in ROM lets you back-calculate VDD.

ESP32-C3 — also can't read VDD. Uses an external voltage divider: two 100K resistors split the battery voltage in half, and the ADC reads the midpoint. Firmware multiplies by 2.

All three strategies are hidden behind the same battery_hal_adc_read_raw() / battery_hal_adc_raw_to_pin_mv() interface. The temperature module, SoC estimator, and telemetry layer don't know or care which MCU they're running on.

Platform Config in One Header

The battery_adc_platform.h header is the master switch:

#if defined(CONFIG_SOC_SERIES_NRF52X)
    // Direct SAADC, 1/6 gain, 0.6V reference
#elif defined(CONFIG_SOC_SERIES_STM32L4X)
    // VREFINT sensor, factory calibration
#elif defined(CONFIG_SOC_SERIES_ESP32C3)
    // Voltage divider, 12dB attenuation
#endif

Adding a fourth platform is ~50 lines of config in this header plus a board overlay and Kconfig file. No C code changes needed.

The Full Pipeline

The SDK doesn't stop at the firmware. There's a complete telemetry pipeline:

MCU (BLE GATT notifications, 24-byte packets every 2s)
  → Python gateway (bleak library, auto-reconnect)
    → InfluxDB 2.x (time-series storage)
      → Grafana (11-panel dashboard)

The gateway includes real-time anomaly detection, battery health scoring, remaining useful life estimation, and charge cycle analysis — all accessible via CLI.

Build Matrix

Platform	Flash	RAM	BLE
nRF52840-DK	152 KB	30 KB	Native
NUCLEO-L476RG	38 KB	10 KB	Shield
ESP32-C3 DevKitM	356 KB	138 KB	Native

Getting Started

# Clone
git clone https://github.com/aliaksandr-liapin/ibattery-sdk.git

# Run tests (no hardware needed)
cd ibattery-sdk
cmake -B build_tests tests && cmake --build build_tests
ctest --test-dir build_tests --output-on-failure
# 11 C test suites pass

# Build for nRF52840
west build -b nrf52840dk/nrf52840 app

# Start the cloud stack
cd cloud && docker compose up -d
cd gateway && pip install -e .
ibattery-gateway run
# Open http://localhost:3000 for Grafana dashboard

What I Learned

HAL design matters more than you think. Getting the abstraction boundary right on the first platform (nRF52840) made the STM32 and ESP32 ports almost trivial.
Integer-only math is worth the constraint. No FPU dependency means the code runs identically on Cortex-M4F, Cortex-M4, and RISC-V without any float promotion surprises.
Zephyr's devicetree is painful but powerful. Once you understand overlays and Kconfig, adding a new board is mostly config — not code.
Test on host, validate on hardware. 69 tests run in under 1 second on macOS without any embedded toolchain. Hardware validation is the final step, not the first.