Request a firmware review
Menu

Portable firmware architecture: surviving a chip change

Reader question: How should we structure our firmware so that a forced change of microcontroller or radio module costs weeks, not a rewrite?

Micrograph-style illustration of a seed with hooked spines clinging to a single animal hair, with the seed tinted amber.

Put abstraction seams where hardware changes and nowhere else: describe the board as data, put each device behind a small interface your application owns, keep the vendor’s hardware abstraction code in one layer of drivers, and keep the application logic buildable on a laptop. Then accept that the radio stack, the low-power modes, secure boot and key storage, and the flash layout will be redone for each new chip, and plan for that work instead of trying to abstract it. With those four seams, a forced chip change becomes new board files, new drivers and a re-validation of the hard parts: weeks of work, not a rewrite.

Fumbar is a Denver firm that writes embedded firmware and over-the-air update systems for hardware startups. This guide is written for the first firmware engineer or CTO who expects a second board revision, a supply problem or a better radio part within the product’s life. The facts come from the Zephyr Project, Espressif and Arm documentation, checked in November 2026; the examples are labeled fictional.

Why chips change, and what a change actually costs

Startups change silicon for ordinary reasons: a part goes on allocation, a cheaper or lower-power sibling appears, the product needs a radio the current chip lacks, or the vendor marks the part not recommended for new designs. The cost of the change depends far less on the new chip than on how much of the old code knew which chip it was running on.

How to pick the replacement is covered in how to choose a microcontroller for a connected product. This article is about the code you bring with you. The useful question is not “is our firmware portable?” but “which files would change for each kind of hardware change, and is that list short?”

Kind of change Example What should change What should not change
Board revision, same chip A sensor moves to another I2C bus; an external flash chip is added Board description only Drivers, application
New chip, same family A larger-flash sibling in the same series Board description, flash layout, a few driver settings Application, most drivers
New chip, different vendor Moving to another vendor’s wireless SoC Board description, drivers, radio integration, power modes, secure boot, flash layout, factory programming Application logic and its tests
New radio module A different cellular module after a supply problem Modem driver and its command scripts, power sequencing Application, message formats

If your honest answer for the last two rows includes “application logic”, the seams below are where the time goes. If it already says what the table says, you mainly need to protect what you have.

Signs the code already knows too much about the chip

A ten-minute audit tells you where you stand. Each of these is common in prototype code and each turns a chip change into a rewrite of the files involved:

  • Pin numbers, I2C addresses or SPI chip-select lines written as literals in application files.
  • Vendor types (handles, status enums, configuration structures) in the signatures of application functions.
  • Busy-wait delays and register reads inside state machines or calculations.
  • Interrupt handlers that contain product logic instead of handing data to a thread.
  • Flash addresses for settings or logs computed in application code rather than taken from a partition table.
  • Tests that can only run on the target board, or no tests at all.

Count the hits per directory. The count is a rough estimate of the files a chip change would touch outside the driver layer, and it tells you which seam to start with.

Seam 1: describe the board as data, not code

The first seam keeps pin numbers, bus assignments, clock choices and memory partitions in one description of the board, read by the code at build time, instead of scattered through source files. A board revision then changes data, and code review shows exactly what moved.

Devicetree in Zephyr

Zephyr does this with devicetree. Its documentation defines a devicetree as “a hierarchical data structure primarily used to describe hardware”, used “to describe hardware to the Device Driver Model” and “to provide that hardware’s initial configuration”. The build turns the devicetree sources into a generated C header, and code reads it through macros that “all start with DT_”.

Applications should refer to devices by role, not by address. The devicetree HOWTOs put it directly: “One way to allow application code to run unmodified on multiple boards is by supporting a devicetree alias to specify the hardware specific portions.” The application asks for the device behind an alias such as soil-sensor; each board’s devicetree or overlay file decides which bus and address that is.

Overlays make board revisions cheap. If you do not name overlay files explicitly, the build looks in the application’s boards/ directory for <BOARD>.overlay and, “If the current board has multiple revisions”, for <BOARD>_<revision>.overlay as well. The board porting guide adds revision handling to the board definition: revisions can be numbers, major.minor.patch or single letters “from A to Z”, and with the default fuzzy matching, “if revisions A, D, and F are defined and the user builds for plank@E, the build system will target revision D.” You only write configuration for revisions that change something.

The same files carry the flash map. Zephyr’s devicetree API includes conveniences for the fixed-partitions compatible “used to encode information about flash memory partitions”, and a chosen node, zephyr,code-partition, names the partition the image is linked into. Bootloader, image slots and storage are part of the board description, which is where they belong when a revision adds a flash chip.

A custom board definition is a small project, not a fork

For your own board, the porting guide lists the mandatory files: a board.yml with “high-level meta data of the boards such as the boards names, their SoCs, and variants”, a devicetree file declaring the SoC, connectors and other hardware, and Kconfig files with default settings. The guide also states the precondition: “Files in the board directory inherit support for at least one SoC and all of its features. Therefore, Zephyr must support your SoC as well.” That sentence is why SoC support belongs on the chip-selection scorecard.

Keep your board directory in your own repository, outside the Zephyr tree, so that upgrading Zephyr does not mean merging your board into a fork. Expect occasional upstream changes to the format itself: the porting guide notes that a new hardware model arrived after Zephyr 3.6.0 and that “A decision was made not to provide direct backwards compatibility for the previous model” for out-of-tree boards.

Without Zephyr

On FreeRTOS or bare metal the same seam is one header or one constant structure per board, board_revc.h and board_revd.h for example, selected by the build system and included only by drivers. The rules are what matter: no pin numbers in application files, one file per board revision, and the flash partition table defined in the same place as the pins.

Example (fictional). Loamwick’s LW-1 soil probe runs Zephyr on a Bluetooth LE microcontroller with 1 MB of internal flash. Rev C boards are the prototypes and Rev D boards the trial units. The flash budget calculator shows the 412 KB image fills 92.8% of a 448 KB slot and that 25% growth would not fit, so Rev E will add an external flash chip for the second image slot. Because the board is described in devicetree, Rev E is mostly a new overlay: a SPI flash node, the secondary slot moved into a partition on that chip, and the internal partitions resized. The sensor and radio code do not change, and the application still finds its sensor through the same alias.

Seam 2: put each device behind an interface the application owns

The second seam gives every hardware-facing part of the product (each sensor, actuator, storage area and link) a small interface written in the product’s own terms, so the application never calls a vendor function or handles a vendor type. When a part changes, you write a new implementation of the same interface and the callers stay as they are.

Zephyr’s driver model already does half of this

In Zephyr’s device driver model, “Each type of driver (e.g. UART, SPI, I2C) is supported by a generic type API”, and each driver fills in a structure of function pointers for that API at initialization. An application that talks to “an I2C bus” through i2c.h does not care which vendor’s I2C peripheral is underneath.

The sensor API goes a level higher: it reads and configures “devices that take real world measurements in meaningful units” through channels, attributes and triggers. If your part has an upstream Zephyr sensor driver, a sensor swap can be a devicetree change. Note what the same page says about the API itself: there are two ways to read samples, “Fetch and Get” and “Read and Decode”, and “It’s expected that in the near future Fetch and Get will be deprecated”. Generic interfaces move too, which is one reason to keep your own thin layer above them.

Write the interface in the product’s terms

Your own interface sits between the application and whatever driver API exists. Name it after what the product does, not after the part:

/* soil_sensor.h: owned by the application; no vendor types */
struct soil_reading {
    int32_t moisture_permille;  /* 0 to 1000 */
    int32_t temp_centi_c;       /* hundredths of a degree C */
};
int soil_sensor_init(void);
int soil_sensor_read(struct soil_reading *out); /* 0 or -errno */

Five rules keep these interfaces small enough to be worth having:

  1. Units in the types. Return engineering units the application uses, never raw register counts. Calibration belongs to the implementation.
  2. No vendor types in signatures. If a vendor enum or handle appears in the header, the seam has leaked.
  3. Errors as plain codes. One convention across all interfaces, such as zero or a negative errno value.
  4. Timing stated, not implied. Say whether a call blocks, for how long at most, and from which context it may be called.
  5. One implementation per part, plus a fake. The fake returns scripted readings for host tests and costs a few dozen lines.

Example (fictional). A team building a Wi-Fi water-leak sensor learns that its humidity sensor will be out of stock for six months. Its application reads humidity through a three-function interface in percent relative humidity, with a fake used by the host tests. The replacement part has a different I2C address, a different conversion formula and a slower measurement. The engineer adds the new part to the board description, writes a new implementation of the same three functions with its own conversion and timing, and updates the interface comment to say the call may now block for up to 20 ms. The application and its tests do not change; the new driver gets its own bench test against a reference hygrometer.

Interfaces at this level are product-specific, so there are only a handful: the sensors, the storage, the link to the gateway or cloud, the user interface. Do not write an interface for every peripheral the chip has. Write one for each thing the product would notice if it changed.

If you write in Rust, the ecosystem has standardized the lower half of this seam. The Rust Embedded Working Group’s embedded-hal 1.0, released January 9, 2024, provides traits “for using peripherals commonly available in microcontrollers such as GPIO, UART, SPI or I2C”, so that drivers “work on any microcontroller with an embedded-hal implementation without modifying them”. You still want the product-level interface above it.

Seam 3: keep vendor HAL code in one layer

The third seam confines the chip vendor’s register headers, hardware abstraction layer (HAL) and SDK calls to one directory of drivers and board support. Everything above that layer compiles without the vendor’s headers. When the chip changes, that directory is replaced and nothing else is edited.

What vendor layers promise, and what they do not

Vendor HALs are written for portability across the vendor’s own chips, which is useful but narrower than it sounds. Espressif’s hardware abstraction guide describes three layers: a Low Level (LL) layer that turns register access into functions, a HAL that models “the operational process of a peripheral as a set of general steps”, and a driver layer for applications. It explains that the HAL API “for a particular peripheral remains mostly the same across multiple targets/chip versions”, meaning across Espressif’s targets. It also carries a warning worth reading twice: the hardware abstraction API, excluding the driver layer and the shared type headers, “should be considered an experimental feature, thus cannot be considered public API”, and “may change in between non-major release versions.”

The lesson is general. Build your own drivers on the vendor’s supported public layer (the driver API in ESP-IDF’s case), not on internals, and keep those calls inside your driver directory where an SDK upgrade can only break one place.

Treat SDK upgrades as practice for a chip change

Vendor SDKs and RTOSes release on their own schedules, and security fixes arrive through them. Pin the exact SDK version in the build (a manifest, a submodule or a lock file), upgrade on purpose rather than by accident, and record which files changed in each upgrade. If an SDK upgrade touches files outside the driver and board directories, the boundary has leaked, and the same leak would cost you on a chip change. A team that can take an SDK upgrade in a day or two, with the host tests and the hardware rig green afterward, has most of what a chip change needs.

Where CMSIS fits

On Arm Cortex-M parts, CMSIS standardizes the layer below the vendor HAL. Arm describes it as having “started as a vendor-independent hardware abstraction layer for Arm Cortex-M based processors”. CMSIS-Core gives “Standardized access to Arm Cortex processor cores” (interrupt controller, system tick, fault registers), CMSIS-Driver defines “Generic peripheral driver interfaces for middleware”, and CMSIS-RTOS2 is a “Common API for real-time operating systems”. Arm is also clear about the limit: CMSIS “is not a huge software layer that introduces overhead and does not define standard peripherals.”

So CMSIS-Core code (interrupt priorities, fault handling, cycle counters) moves between Cortex-M vendors with little change, while peripheral code still depends on each vendor’s drivers unless a CMSIS-Driver implementation exists for the part. Moving to a non-Arm core, such as RISC-V, leaves CMSIS behind entirely.

Enforce the boundary in the build

A boundary that lives only in a design document erodes within a few months. Make it mechanical:

  • Put vendor include paths only on the driver and board targets in the build system, so that an application file including a vendor header fails to compile.
  • Add a CI check that searches application directories for vendor header names and fails the build if it finds one.
  • Review every new file under the driver directory with the question “could this be in the application instead?”, and every new application file with the opposite question.

Seam 4: application logic that builds and runs on a laptop

The fourth seam keeps the product’s logic (state machines, message encoding, calibration math, scheduling decisions, the update agent’s decisions) in code that compiles for a desktop computer as well as for the chip. If it runs on a laptop, it does not depend on the chip, and it survives a chip change by definition.

This seam overlaps with testing, and the details of host-side unit tests, fakes and CI are in firmware testing for startups. The portability point is narrower: the share of your code that builds on the host is a direct measure of how much of it will move to a new chip unchanged.

Zephyr makes the measurement easy. Its native_sim board compiles a Zephyr application “together with the Zephyr kernel, and libraries, creating a normal Linux executable”. The board “does not intend to simulate any particular HW”, but it provides some peripherals, such as a UART and an Ethernet driver, to let application code run. Any module that builds for native_sim with your fakes in place has no hidden chip dependency.

Two habits keep this seam open. Pass time and randomness into logic as parameters or through an interface, rather than reading a hardware timer inside a calculation. And keep interrupt handlers short: copy data, signal a thread, return. Logic inside an interrupt handler is logic that cannot run on a laptop.

What to move to the host build first

Not all logic is worth separating on day one. Start with the code that changes most often and fails in the most expensive ways:

  1. The reading and reporting schedule. When to wake, measure, store and send, including what happens when the link is down for a day.
  2. Message encoding and decoding. Every byte the device sends to the gateway or the cloud, and every command it accepts, with tests for malformed input.
  3. Calibration and unit conversion. The formulas that turn raw readings into the numbers customers see.
  4. The update agent’s decisions. Whether to accept an offered image, when to install it, and when to confirm it, with the actual flash writes behind an interface.
  5. Error handling and retry policy. Backoff timers, limits and what the device does when storage is full.

Each of these is plain C or Rust once its inputs arrive through parameters and interfaces. Together they are often most of what makes the product different, which is why they are worth carrying from chip to chip intact.

Application logic State machines, encoding, calibration; builds on a laptop Product interfaces soil_sensor, storage, link; no vendor types Drivers and vendor HAL The only code that includes vendor headers Board description (data) Devicetree or one board header; pins, buses, flash map Hardware: chip, board, radio module Stays on a chip change Same source files, same host tests, re-run on the new hardware Redone per chip Radio stack integration Low-power modes Secure boot and keys Flash layout Factory programming Radio certification Green: kept across a chip change. Amber: replaced or redone.
Figure 1. The four seams as layers. A chip change should replace the amber layers and leave the green ones untouched; the right-hand column lists work that no abstraction removes. Diagram by the Fumbar editorial team, based on the Zephyr devicetree, device driver model and native_sim documentation, checked November 2026.

What you cannot abstract cheaply

Some parts of a connected product are bound to the chip so tightly that an abstraction layer over them costs more than redoing them: the radio stack, the low-power modes, secure boot and key storage, the flash layout and the factory process. Do not try to make these portable. Isolate them, document them, and put them in the estimate for any chip change.

Radio stacks

Bluetooth LE shows the problem. Zephyr’s stack architecture page splits the stack into a Host, a Controller that “implements the Link Layer”, and the radio hardware. Between Host and Controller the Bluetooth specification defines the Host Controller Interface (HCI), which makes it “possible to combine Hosts and Controllers from different vendors”. But in the single-chip configuration most products use, “the Bluetooth Host and the Bluetooth Controller communicate directly through function calls and queues in RAM”, and the specification “does not specify how HCI is implemented in this single-chip configuration”. In practice the controller on a wireless SoC comes with that chip’s SDK and is bound to its timing and radio calibration.

What carries over is the host-side code: your GATT services, your advertising data, your connection logic, when written against a host stack you keep. What does not carry over is the controller, the radio’s RF calibration and the qualification work. Treat a radio chip change as a radio project.

Cellular modules behave similarly at a different layer. Zephyr’s modem modules separate the transport (a “modem pipe” over UART or CMUX channels) from “scripted AT command communication with a modem”, where “AT commands are organized into scripts”. That structure is the right one for your own code too: message formats and retry policy above an interface, and module-specific AT scripts, power sequencing and firmware quirks below it. A module change then means new scripts, new power-on timing and new carrier testing, not new application code.

Low-power modes

Sleep states, retention options and wake sources differ chip by chip, and they decide battery life. Zephyr’s system power management gives the kernel a common way to enter supported power states, but its own documentation warns that “depending on the SoC and the power mode in question, not all peripherals may be active, and therefore some wake-up sources may not be usable in all power modes.” Keep the power policy (when to sleep, what may wake the device) in one module, and expect to re-measure sleep current and re-tune that module on every new chip.

Secure boot, keys and the flash layout

Root-of-trust features are physical. Espressif documents, for example, that the ESP32 can store “Only one public key” for Secure Boot v2 while the ESP32-S3 holds “Up to three public keys” with permanent revocation. Key slots, one-time programmable fuses, debug lock options and anti-rollback counters change with the chip, so the provisioning steps, the factory station and the signing setup change too. A bootloader that runs on many chips, such as MCUboot, keeps the image format and update logic stable, but its port, its flash partitions and its key storage are still per chip.

The flash layout follows the chip’s sector geometry and size, which is why the board description should own it and why every chip change should start with the flash budget calculator.

Area Why it resists abstraction What to do instead
Radio controller and RF calibration Vendor-specific, timing-critical, tied to qualification Keep host-side logic above an interface; budget a radio project per chip
Cellular module AT dialects, power sequencing, carrier testing Module-specific scripts below a link interface
Low-power modes Different states, retention and wake sources One power policy module; re-measure every time
Secure boot and keys Fuses, key slots, revocation and counters differ Document the provisioning steps per chip; re-test lockdown
Flash layout Sector sizes and capacity differ Keep it in the board description; recompute per chip
Factory programming and test Tools and interfaces are vendor-specific Keep the test steps in a script with a per-chip backend

Which seams pay back at seed stage, and which are premature

For a seed-stage team, the first three seams usually pay back within one board revision, and the fourth pays back through testing before any chip change happens. Abstractions beyond them (a portability layer over the RTOS, a generic HAL for every peripheral, a plug-in system for radios) usually cost more than they save until a second product or a second chip is actually planned.

Seam or abstraction Cost now When it pays back Judgment for a small team
Board as data (devicetree or one header) Low with Zephyr; a day or two elsewhere The first board revision Do it from the first board
Product interfaces for sensors, storage, link A header and a fake per device The first part substitution, and every host test Do it for each device the product depends on
Vendor code confined to one layer Discipline and a CI check The first SDK upgrade or chip change Do it, and enforce it mechanically
Logic that builds on a laptop Moderate: separating timing and I/O from logic Immediately, through tests Do it for state machines and encoding
Your own layer over the RTOS Wrapping threads, queues, timers Only when moving between RTOSes Skip unless an RTOS change is planned
Your own HAL for every peripheral Large and mostly unused Rarely Skip; use the RTOS or vendor driver API
An abstraction over the radio controller Large, and still leaks timing and RF Almost never at this stage Skip; isolate and budget instead

The judgment column is ours, not a measured result, and a team that already knows it will ship on two chips should move the RTOS layer up the list. The test is simple: write an abstraction when you can name the second implementation and roughly when it will be needed. An abstraction with only one implementation and no planned second one is an extra layer to debug.

Over-abstraction has costs that do not show up in a design review. Every extra layer is another place to set a breakpoint when a fault occurs, another set of function pointers that hides the real call from the reader, and more flash in a product that may already be short of it. Generic layers also tend to expose only what every chip has in common, which pushes engineers to bypass them for the one feature they need, and a bypassed layer is worse than none. Keep the layers you add thin, product-specific and few.

The RTOS choice interacts with this. Zephyr provides the board-as-data seam, a generic driver model and a host build out of the box; FreeRTOS and bare-metal projects build the same seams by hand, which is entirely workable for a small codebase. The trade-offs are covered in Zephyr, FreeRTOS or bare metal.

How to keep the seams from eroding

Seams erode under deadline pressure, one convenient shortcut at a time, and nobody notices until the next board revision. Three cheap habits keep them in place for the life of the product.

Write the rules down where the code lives. A one-page architecture note in the repository, next to the code, with the layer diagram, the list of product interfaces, the directories each layer may use and the rule for new abstractions. New engineers read it in their first week; reviewers point to it instead of arguing from memory. Documentation that a client team can run with is part of how Fumbar hands work over, and this page is the natural first item in it.

Make the build enforce what the note says. Include paths per layer, the CI search for vendor headers in application directories, and a host build of the application that fails when someone adds a hardware call where it does not belong. A rule the build enforces does not depend on anyone remembering it.

Review hardware changes as interface changes. When the hardware team proposes a different part or a new board revision, ask which interfaces and which board files it touches before it is approved. The answer is usually “one driver and one overlay”, and when it is not, you find out during design review rather than during bring-up.

A chip change, step by step

When a change is forced on you, work from the bottom of the layer diagram up, and validate the hard parts before porting anything easy. The order below keeps the risky work early, while there is still time to change course.

  1. Inventory the coupling. Search the repository for vendor headers and SDK calls outside the driver and board directories. Each hit is a leak to fix before or during the port.
  2. Recompute the flash layout. Enter the new chip’s flash size, sector size, bootloader, storage and current image size in the flash budget calculator. Decide whether two image slots still fit internally.
  3. Bring up the board. New board files or devicetree, clocks, debug access and each peripheral, with measurements recorded. Board bring-up is a defined step of its own; see the board bring-up service for what it covers.
  4. Prove the hard parts first. On the new chip, before porting features: bootloader with signed images and a forced rollback, the radio link at range, the lowest-power sleep state with measured current, and debug lock on a production-configured unit.
  5. Port the drivers behind the existing interfaces. Each interface keeps its header; only the implementation changes. Run the same host tests against the fakes to confirm the application is untouched.
  6. Run hardware-in-the-loop tests. The rig that tested the old board runs against the new one, with any new board-specific fixtures. The test automation service describes that kind of rig.
  7. Plan the release train. Units in the field keep the old chip. Build one signed image per hardware revision from the same source tree, and put the revision in the version string and file name, as the version scheme builder does with its default revd_1.2.0-rc.2_b217.signed.bin example.
  8. Re-certify and re-measure. Radio certification, battery life and factory test time all need fresh numbers on the new hardware.

Example (fictional). Suppose that after the Rev E change, Loamwick’s microcontroller went on allocation and the team had to move the LW-1 probe to another vendor’s Bluetooth LE chip. Steps 1 and 2 would show two leaks (a vendor delay call in the sensor state machine and a register read in the battery check) and confirm that the new chip’s flash still needs the external chip for the second slot. Step 4 would be most of the work: a new MCUboot port and key provisioning, the radio link to the gateway re-tested at the trial plots’ distances, and sleep current re-measured against the three-year battery requirement. The soil sensor interface, the reading schedule, the message format to the gateway and their host tests would move unchanged, and Rev C and Rev D probes already in the field would keep receiving their own signed images.

What to do before your next board revision

You do not need a chip change to start; the seams pay for themselves on the next board revision. In order of value for a small team:

  1. Move pins, buses and the flash map into one board description per revision, and remove hard-coded pin numbers from application files.
  2. List the devices the product depends on and give each a small interface with units, plain error codes and a fake.
  3. Put vendor include paths only on the driver layer and add the CI check that fails on a vendor header in application code.
  4. Build the application logic for the host (native_sim, or a plain host build for FreeRTOS and bare-metal code) and run it in CI.
  5. Write down the chip-bound parts: radio integration, power policy, secure boot and provisioning, flash layout, factory test. For each, note which files hold it and how you would re-validate it.
  6. Record the decision rule for new abstractions: none without a named second implementation.

The firmware development service is where this structure is set up in a new codebase or retrofitted into an existing one. If you are facing a board revision or a forced chip change now, a firmware review from Fumbar reads your schematics, code, flash layout and update plan and ends in a written plan with the risks and the order of work; you can request a firmware review.

Facing this decision on a real device?

If this article describes a choice in front of you, a firmware review puts it in writing for your board, your code and your update plan.

Request a firmware review

Or email sales@fumbar.com, or call (720) 675-4202.