Skip to content

About

Practical guide to writing one library that runs natively on both Arduino and ESP-IDF: a framework-agnostic core with a compile-time HAL, one repository layout, and publishing to Arduino Library Manager, ESP Component Registry and PlatformIO Registry.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

127 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Dual-Framework Library Guide

One repository with a framework-agnostic core and compile-time HAL, published to the Arduino Library Manager, the ESP Component Registry and the PlatformIO Registry

Native Arduino library & ESP-IDF component from a single codebase: a practical guide to architecture, repository layout, and publishing, with one repository and no compatibility layer. It covers the Arduino Library Manager, the ESP Component Registry, and the PlatformIO Registry.

Who it's for: developers who want to write a single library that works natively on both Arduino and ESP-IDF (including PlatformIO), starting from either ecosystem.


Table of Contents


Why build a library that's native to both Arduino & ESP-IDF

Before diving into the technical constraints, it's worth answering a more fundamental question: why accept the complexity of supporting both Arduino and ESP-IDF natively at all? Why not simply choose one ecosystem, or rely on Arduino-as-a-component as a compatibility layer?

Spoiler: the final solution is far less complicated than this guide might suggest. Most of the discussion that follows is not about complexity, but about explaining the constraints, trade-offs, and reasoning that led to each architectural choice.


🚪 Arduino is still the front door

Arduino is, and will remain for a long time, the primary entry point into embedded development.

Its greatest strength is not raw technical capability, but accessibility. Projects can be initialized in seconds, the API is intentionally approachable, and compiling and flashing firmware is often reduced to a single click. Beginners, hobbyists, educators, and even experienced developers building quick prototypes. This reduction in friction is not a secondary advantage: it is the very reason the platform became dominant and continues to attract the largest community in the embedded world.

Ignoring Arduino means ignoring where most users begin.


⚙️ ESP-IDF is becoming the destination

At the same time, ESP-IDF is increasingly establishing itself as a reference platform for ESP32 development, not only for greenfield professional projects, but also for projects that originally grew within the Arduino ecosystem itself.

A concrete signal is ESPHome's migration toward ESP-IDF: a project born and grown within the Arduino ecosystem that chose to move its engine onto native ESP-IDF.

There is also a technical reality that is often underestimated:

when you write Arduino code for an ESP32 board, you're already running on top of ESP-IDF.

arduino-esp32 is itself a layer built on top of ESP-IDF as a component, not an independent alternative. The question isn't "Arduino or IDF?" but rather:

Do you want to interact directly with the platform's engine, or through an additional translation layer?


🔄 Compatibility layers solve portability, not dependency

The Arduino as an ESP-IDF component compatibility layer lets you run an existing Arduino sketch inside an IDF project with minimal effort, preserving compatibility with a vast amount of existing code. It's a valid trade-off for reusing code without rewriting it, but it isn't free: application code still goes through Arduino APIs such as digitalWrite and pinMode, which are then translated into ESP-IDF calls.

The per-call overhead is often modest. The real price is architectural: a library tied to the Arduino core forces that entire framework into every native IDF project that uses it.


🧩 A HAL addresses the problem at the source

Designing with a Hardware Abstraction Layer (HAL) from the start solves the problem at its root.

Rather than choosing one ecosystem and translating toward the other, the application layer remains completely independent of both. This also removes the after-the-fact work described in Espressif's guide on Porting a library to an ESP-IDF component: there is nothing to port, because the library is native to both ecosystems from the start. Protocol handling, algorithms, state management, calculations, and business logic stay framework-agnostic. Only the lowest layer, the one that actually touches the hardware resources, changes according to the selected framework.

Most importantly, that choice is resolved at compile time, not at runtime (see Chapter 3). The result is a single codebase where each framework keeps its native implementation path, with no runtime switches or translation layers: native performance on both sides, with application logic written and maintained once.


📚 The purpose of this repository

This guide documents the architecture, constraints, and practical decisions required to make that approach work in a real-world library. It covers everything from the non-negotiable requirements of each ecosystem, to repository organization, build integration, and publication across all major distribution channels:

Addressing this architectural choice right from the start helps avoid the need to adapt or refactor the library at a later stage.

Note

Reference implementation: this guide comes from the practical experience of developing my CS123x library. It follows almost every pattern, layout, and configuration described in these chapters. A few differences remain, as the guide evolved beyond the original implementation through additional research and experimentation across both frameworks.

Tested with: ESP-IDF v6.1 (native), PlatformIO espressif32@6.4.0 (IDF 5.1.1), Arduino IDE 2.3.x. Registry/tool behavior observed in September 2026; it may change.

Warning

The guide is based on a C++ class shared by both frameworks. The previously mentioned CS123x library, was born for Arduino and then adapted to ESP-IDF quickly, by adding only the HAL and the Arduino facade. This approach sits halfway between using the Arduino-ESP32 component — which brings the whole framework along — and rewriting the core in C with ESP-IDF convention. In the future, the guide may be updated to follow the path of a C core for ESP-IDF — with error handling through esp_err_t, if possible — and a C++ facade class for Arduino.


License

This guide is dual-licensed:

CC BY 4.0

If you reuse or adapt the text, give credit as: "Dual-Framework Library Guide" by FMazz97, https://github.com/FMazz97/dual-framework-library-guide, and indicate if changes were made. Code snippets can be reused under the MIT terms, keeping the copyright notice.

These licenses apply to all versions, commits, and historical revisions of this repository.


About

Practical guide to writing one library that runs natively on both Arduino and ESP-IDF: a framework-agnostic core with a compile-time HAL, one repository layout, and publishing to Arduino Library Manager, ESP Component Registry and PlatformIO Registry.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors