Skip to content

HardFOC core library

HardFOC Core

The layer between the HardFOC device drivers and a board HAL. hf-core wraps each driver in a thread-safe handler that takes Base* interfaces, collects the MCU interfaces, RTOS wrappers and utilities, and builds and tests all of it on a host machine with no MCU toolchain.

Quickstart Handlers Source on GitHub

A device driver knows its chip and nothing else: it talks through a small CRTP interface and leaves locking, bring-up order and bus sharing to its user. A board HAL knows its pins and buses. hf-core is what sits between them, so that every HAL wires a TMC9660 or a BNO08x the same way and no code above the HAL includes an MCU SDK.

Layer diagram of the HardFOC platform. At the bottom, the MCU SDK and RTOS and the device driver repositories. Above them hf-core-drivers (drivers, interface wrap, pin config) and hf-core-utils (RTOS wrapper, general and CANopen utilities). On those, the hf-core handlers. Above the handlers, the board HALs, and at the top the products.Layer diagram of the HardFOC platform. At the bottom, the MCU SDK and RTOS and the device driver repositories. Above them hf-core-drivers (drivers, interface wrap, pin config) and hf-core-utils (RTOS wrapper, general and CANopen utilities). On those, the hf-core handlers. Above the handlers, the board HALs, and at the top the products.
Where hf-core sits
Figure description and sources

From the bottom up. Each device driver is its own repository and talks to its chip through a small CRTP interface; hf-core-drivers collects them as submodules, together with hf-internal-interface-wrap (the Base* interfaces and their ESP32 and STM32 implementations) and hf-pincfg. hf-core-utils collects the RTOS wrapper, the general utilities and the CANopen helpers. hf-core's handlers sit on top of those three: each one wraps one driver behind a thread-safe API that takes Base* interfaces. A board HAL creates the MCU peripherals, constructs the handlers it needs and exposes managers; a product is firmware on one board HAL. The driver list is read from cmake/hf_core_build_settings.cmake and the handler list from handlers/.

Drawn from: cmake/hf_core_build_settings.cmake driver and utility paths; handlers/ handler folders; figure module docs/diagrams/figures/platform-layers.py.

What you get

  • 23 handlers, one per device family. Each takes BaseSpi, BaseI2c, BaseUart, BaseGpio or BaseAdc references, initialises its driver on first use and serialises calls with a recursive mutex. See Handlers.
  • One CMake file for every consumer. cmake/hf_core_build_settings.cmake turns HF_CORE_ENABLE_* switches into sources, include directories, ESP-IDF requirements and compile definitions. See Integration and Feature switches.
  • A host build with mocks. HF_CORE_MCU=NONE, HF_CORE_RTOS=NONE: handlers, drivers and utilities compile and run on Linux or macOS against scriptable fakes of the Base* interfaces. See Host build and mocks.
  • Threads and locking without the RTOS in your code. RtosMutex, MutexLockGuard, BaseThread and the OS abstraction map to FreeRTOS on target and to a no-op backend with a fake clock on the host. See Threading and RTOS.
  • CANopen helpers on BaseCan. Frame builders and parsers for NMT, SDO, heartbeat, emergency and CiA 402, and a bridge to any BaseCan. See CANopen.
  • A checked MCU boundary. Only the interface implementations and a short list of files may include vendor headers; the host build proves the rest is portable. See MCU boundary.

Used by

Repository Uses hf-core for
hf-hal-vortex-v1 Vortex V1: TMC9660, AS5047U, BNO08x, PCAL95555, PCA9685, NTC and WS2812 handlers, the Vortex driver, CANopen
hf-hal-flux-v1 Flux V1: ADS7952, MCP9700, NTC, TLE92466ED, MAX22200, Alicat BASIS-2, FDO2 and WS2812 handlers, CANopen
hf-utils-and-drivers Superseded by hf-core; kept for older projects

Where to go next

  • Quickstart

    Add hf-core to a project and drive a handler in 20 lines.

  • Platform overview

    The layers, the repositories and how one call travels through them.

  • Handlers

    Every handler, its driver, its interfaces and its switch.

  • Host build and mocks

    Build and test without hardware, from hf-core or from a HAL.