The Caffeine Framework

Caffeine-HAL

A modern, strictly C11-compliant, header-only Hardware Abstraction Layer (HAL) for embedded systems.

Overview

Caffeine-HAL provides a polymorphic, Virtual Method Table (VMT) based interface for microcontrollers (primarily ARM Cortex-M). It is designed to be lightweight, thread-safe, and highly portable by decoupling the generic peripheral logic from vendor-specific board configurations.

Key Features

Zero-Copy & Header-Only: Designed as a CMake INTERFACE library for easy integration.
Universe Standard: Uses the ci-all-sources preset for global formatting and documentation, ensuring every peripheral interface is consistently validated.
Mock Library Support: Provides a standalone caffeine::hal-mock STATIC library for native host testing of upper layers (SAL, Apps) without hardware dependencies. Automatically enabled via the global CFN_BUILD_TESTS flag.
Modular Base Driver: All peripherals inherit from a common base (cfn_hal_base.h), ensuring a consistent lifecycle.
Thread-Safe by Design: Optimized locking strategy using CFN_HAL_WITH_LOCK for clean multi-threaded RTOS environments.
Pragmatic Static Analysis: Pre-configured for clang-format, clang-tidy, and cppcheck (Allman style).

Quick Start

1. Integration (CMake)

You can easily integrate Caffeine-HAL into your project using modern CMake.

Option A: FetchContent (Recommended) Download and link the library automatically during the CMake configure step.

include(FetchContent)
FetchContent_Declare(
    caffeine-hal
    GIT_REPOSITORY https://github.com/while-one/caffeine-hal.git
    GIT_TAG        main # Or a specific release tag
)
FetchContent_MakeAvailable(caffeine-hal)
 
target_link_libraries(your_app PRIVATE caffeine::hal)

Option B: Native Testing with Mocks Enable the global test flag to automatically expose the mock library.

set(CFN_BUILD_TESTS ON)
FetchContent_MakeAvailable(caffeine-hal)
 
# Use the mock target for your unit tests
target_link_libraries(your_test_bin PRIVATE caffeine::hal caffeine::hal-mock)

Development & Analysis

The project includes built-in targets for maintaining code quality:

Format Code: cmake --build build --target caffeine-hal-format
Run Static Analysis: cmake --build build --target caffeine-hal-analyze
Run Unit Tests: cmake --build build --target caffeine-hal-test (Requires -D CFN_BUILD_TESTS=ON)

Build Environment (Docker & Local)

Use the framework's centralized scripts for orchestration:

# Full Quality Gate (Format -> Analyze -> Build -> Test)
./caffeine-build/scripts/ci.sh all
 
# Build using the native Linux stage
./caffeine-build/scripts/build.sh unit-tests-gtest
 
# Perform a clean build
./caffeine-build/scripts/build.sh --clean unit-tests-gtest

Directory Structure

caffeine-build/: Submodule containing centralized build presets, toolchains, scripts, and hardware target definitions.
include/: Foundational hardware abstraction headers and polymorphic VMT definitions.
src/mock/: Stubs and bridges for the caffeine::hal-mock library.
tests/: GTest suite for validating framework logic on host.

Documentation

The API reference for this repository is generated automatically via Doxygen and hosted on GitHub Pages.

📚 View the Caffeine-HAL API Documentation

The Caffeine Framework Layers

**Generic Interface (caffeine-hal):** This repository. Definitions of the HAL and Virtual Method Tables (VMTs).
**Hardware Ports (caffeine-hal-ports):** Concrete implementations for specific vendors. Encapsulates low-level hardware definitions into target scripts (e.g., stm32f417vgtx.cmake).
**Middleware (caffeine-sal):** Hardware-agnostic device drivers and connectivity abstractions.
**Application (caffeine-app-mvp):** Top-level business logic utilizing the framework.

Support the Gallery

While this library is no Mondrian, it deals with a different form of abstraction art. Hardware abstraction is a craft of its own—one that keeps your application code portable and your debugging sessions short.

Whether Caffeine is fueling an elegant embedded project or just helping you wake up your hardware, you can contribute in the following ways:

Star and Share: If you find this project useful, give it a star on GitHub and share it with your fellow firmware engineers. It helps others find the library and grows the Caffeine community.
Show and Tell: If you are using Caffeine in a project (personal or professional), let me know! Hearing how it's being used is a motivator.
Propose Features: If the library is missing a specific "brushstroke," let's design the interface together.
Port New Targets: Help us expand the collection by porting the HAL to new silicon or peripheral sets.
Expand the HIL Lab: Contributions go primarily toward acquiring new development boards. These serve as dedicated Hardware-in-the-Loop test targets, ensuring every commit remains rock-solid across our entire fleet of supported hardware.

If my projects helped you, feel free to buy me a brew. Or if it caused you an extra debugging session, open a PR!

License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.