Skip to content

How we build

A driver is the chip's datasheet turned into C++. We build each one as if it could end up in a safety-classified product, and we say plainly how far each one has got.

The process in one picture

Pipeline in four columns in which a public datasheet and an independent chip model feed the CI checks, an independent review round follows, and a release candidate with a stated hardware level comes out.Pipeline in four columns in which a public datasheet and an independent chip model feed the CI checks, an independent review round follows, and a release candidate with a stated hardware level comes out.
What stands between a datasheet and a release candidate
Figure description and sources

The Inputs column holds the public datasheet and a model of the chip written from it, apart from the driver. The CI column holds host tests with compile-fail cases, sanitizers and fuzzing, coverage and complexity limits, clang-tidy and cppcheck, and the MISRA C++:2023 scan with the C++20 profile. The Review column holds an independent review round, where mutants of every fix must be caught by a test, and a check of every claim against the code. The Release column holds the release candidate, with its tag, its documentation site and its stated hardware level.

Drawn from: docs/model/driver-gates.pipeline.yml.

Practice What it means here
Public datasheets only A driver is written from documents anyone can read. A chip whose register map is under NDA is declined
IEC 62304, up to Class C The process maps onto the standard's clauses so a manufacturer can use a component in software of any safety class, Class C included. It is not a certificate: see below
MISRA C++:2023 Every pull request runs the MISRA scan; each deviation is recorded with its reason
Independent review A reviewer who did not write the driver, its model or its tests reviews it, in rounds, until nothing is left
Fuzzing A fuzzer corrupts and replaces what the chip sends back and resets the chip at any point, on every pull request
Mutation testing Reviewers break each fix on purpose; a test must fail on every mutant
Coverage and complexity gates 85 % lines and 75 % branches at least, and limits on function size and complexity
Release candidates Every driver ships as a -rc tag first, with its hardware level stated in the release text
Hardware validation levels H0, H1 and H2 say how far the driver has been checked on a real chip

A driver never touches the SDK

Everything that depends on your MCU sits behind a small port class that you write, and the driver only calls its hooks.

The driver owns Your port owns
Register framing, reset and chip-ID checks, conversions, CRCs Bringing the bus up, moving bytes, optional GPIO, delay and log hooks
Units, ranges and Config presets with datasheet defaults Pins, clocks, DMA, locking, which SPI or I2C peripheral

The port derives from the driver's interface with CRTP (class MyPort : public chip::SpiInterface<MyPort>) and a C++20 concept checks every required hook at compile time. There are no virtual calls, so the compiler can inline the port into the driver.

Predictable on small MCUs

  • No exceptions, no heap, no RTTI. Every call returns Result<T>: a value, or an Error that says what went wrong (Bus, Timeout, DeviceIdMismatch, chip-specific faults).
  • Nothing happens in a constructor. EnsureInitialized() does the first I/O, so you decide when the bus is touched.
  • Bounded waits. A driver never blocks forever on a busy flag.
  • No reading it can't trust. A driver reports a bad reading as an Error, not as a measurement: the BMP581 driver, for one, refuses a stuck line, a reset value and anything outside the measurement range.

Brand-free

A driver is named after its chip, not after a product: repository driver-<chip>, namespace <chip>::. A product's pin map or modes never go into a shared repository.

Kind of "specific" Example Where it lives
Chip-specific the registers of one sensor that chip's driver
MCU-specific an ESP-IDF SPI port a port, built only for that family
Product-specific one product's pin map or modes the product's own repository, through extension points

Tested without hardware

Every driver builds and runs its tests on the host with CMake and ctest. The chip model is written from the datasheet, not from the driver, so a wrong constant in the driver can't hide behind the same wrong constant in the model. The model changes state on its own, resets mid-session and completes measurements in time, so a missed reset fails a test.

  • Error paths are forced: every bus transfer fails in turn, and every error the driver can return is produced.
  • Compile-fail tests check that a broken port does not compile.
  • A fuzzer (libFuzzer with the address and undefined-behaviour sanitizers, 120 s per target on every pull request) corrupts the replies and checks that no broken line is returned as data. Every input that ever broke a promise stays in the replayed corpus, so a fixed bug stays fixed.
Sequence of a driver start and one measurement, in which the firmware starts the driver, the driver checks the chip through the port and returns a result, and a later call returns a value or an error code.Sequence of a driver start and one measurement, in which the firmware starts the driver, the driver checks the chip through the port and returns a result, and a later call returns a value or an error code.
One measurement through a driver
Figure description and sources

The Firmware calls EnsureInitialized on the Driver. The Driver sends its first transfers to the Port, which moves the bytes on the bus to the Chip and returns the replies. The Driver checks the chip identity against the datasheet and returns a Result to the Firmware. A later measurement call goes through the Port the same way, and the Driver returns either the value in physical units or an Error, never a number it could not trust.

Drawn from: docs/model/one-measurement.seq.yml.

Coding standards

Standard Used for
MISRA C++:2023 with Technical Corrigendum 1 (2026) C++ code. Every guideline is classified in a compliance matrix: decided by a tool, checked in review, left to a commercial checker, or not applicable with a reason
MISRA C:2025 C code; its matrix follows the same format
SEI CERT C++ and C Security baseline, checked by clang-tidy and cppcheck
C++ Core Guidelines Design and idiom, through clang-tidy
NASA/JPL Power of Ten Embedded discipline

We follow the approach MISRA itself defines in MISRA Compliance:2020: an enforcement plan, a re-categorisation plan where our profile is stricter, a deviation record for every departure from a required guideline, and a compliance summary with each release. Mandatory guidelines are never deviated. Every pull request runs the MISRA scan with the open CodeQL coding-standards pack on a host and a Cortex-M build; the commercial checker is added at the safety level.

Independent review

A review round is one independent reviewer, one fixer and one verdict, repeated until the stop rule holds.

  • The reviewer did not write the driver, its model or its tests, works read-only, and never sees the builder's conclusions.
  • Mechanical results come first: lint, the gate log and the CI lines are not re-argued.
  • The reviewer verifies the previous round's fixes at the cause by building mutants: revert the fix, or change a constant in its guard. A fix is accepted only if a test fails on its mutant.
  • Every claim in the docs and the build report ("never", "always", "returns") is checked against the code and a test.
  • The judgement questions go to the reviewer: is the datasheet read correctly, is the state machine complete, is the model independent of the driver.

Anything a script can decide moves out of review into lint or a test, so reviewers spend their time on judgement.

Assurance levels

Not every repository needs the same rigour. Each declares one of three levels, and each includes the one below it.

Matrix of the checks and evidence asked for at the standard, high and safety assurance levels, from lint and host tests for every repository to a signed evidence package at safety.Matrix of the checks and evidence asked for at the standard, high and safety assurance levels, from lint and host tests for every repository to a signed evidence package at safety.
What each assurance level asks for
Figure description and sources

Rows are the checks and evidence. Columns are the three assurance levels standard, high and safety. A cell says required, measured or not required in words and with a mark. Format, lint, static analysis, host tests, the strict documentation build, the sign-off check and the CI gate are required at every level. Sanitizers, a coverage floor, builds for every supported target, warning-free Doxygen on the public API and a deviation record for every suppressed finding start at high. Requirement traceability, full branch and MC/DC coverage, the coding-standard matrix with a commercial MISRA checker, an anomaly list and a signed evidence package start at safety.

Drawn from: docs/model/assurance-levels.matrix.yml.

Drivers are built at high from their first release. Safety is chosen per component, when a product team intends to qualify it, and commits the project to keeping the evidence current for every release.

Using a component in a medical device

IEC 62304 applies to a manufacturer's process, not to a library. A manufacturer can use a Kokeb component as SOUP (software of unknown provenance), or bring it under their own process by forking it at a release. The handbook's IEC 62304 page maps each clause of the standard onto what a component provides. A component at the safety level is not "IEC 62304 compliant": risk management, hazard analysis, system testing and the device's technical file stay with the manufacturer.

Releases and release candidates

  1. The driver is built and reviewed until the full local rehearsal of CI passes.
  2. It is published in a public repository, and main must be green with its docs published.
  3. The first tag is a release candidate, vX.Y.Z-rc.1. Its release text states the hardware level. A release candidate publishes its docs under its own tag and does not move latest.
  4. A release candidate that passes the bench is tagged again, on the same commit, as vX.Y.Z.

All 22 public drivers are at v0.1.0-rc.1 today.

Hardware validation levels

Tests prove the driver against a model of the chip written from the datasheet. A bench proves the model. Each driver states how far it has been checked as a level, in its metadata and as a badge on its README.

State machine of the three hardware validation levels H0, H1 and H2, from a host model only, to a bench rig run with logs kept, to a hardware engineer's sign-off.State machine of the three hardware validation levels H0, H1 and H2, from a host model only, to a bench rig run with logs kept, to a hardware engineer's sign-off.
Hardware validation levels
Figure description and sources

A driver starts at H0, where it has only been run against a model of the chip on the host. It reaches H1 when a defined bench rig has run the example and the rig document and the logs are kept. It reaches H2 when a hardware engineer has reviewed the rig and the steps and signed off. The level is written in the driver's metadata file and shown as a badge on its README.

Drawn from: docs/model/hardware-levels.state.yml.

Level Means
H0 Host model only: never run on a chip. Releases say not hardware-verified
H1 A defined bench rig ran the example; the rig document and the logs are kept
H2 A hardware engineer reviewed the rig and the steps and signed off

Every public driver is at H0 today. We don't call a driver verified without the evidence for H1 or H2.

Language standard

Drivers target C++20 today. One language level across every repository lets any driver sit under any library. C++20 gives concepts for the port contract, requires for optional hooks, std::span for caller buffers and designated initialisers for configuration, and it is supported by ESP-IDF 5.x and current STM32 toolchains without the lag that C++23 has on vendor compilers.

  • It is checked, not assumed. Every target builds as ISO C++20 with compiler extensions off and -pedantic-errors, and every public header also compiles on its own at -std=c++20 with each compiler the repository ships for. ESP-IDF's own default dialect is newer, so without that check a C++23 feature would compile on one toolchain and break on another.
  • It is a profile, not "anything in C++20". MISRA C++:2023 is written for C++17, so the handbook's C++20 profile sorts the features into use, use with rules and forbid: 58 guidelines (4 mandatory, 36 required, 18 advisory). Anything from C++23 or later is a violation even where the compiler accepts it.
  • It is recorded. A driver states its standard in its README badge and its build settings (cxx_std_20). Raising the compiler a caller needs is a breaking change, so a release that does it lists it under Breaking in its changelog.

It will move up. There is no date, and a move is not a surprise. It happens when all of these hold:

Condition Why
Every compiler we ship for supports the standard: the ESP-IDF toolchain, the CI compilers and the Cortex-M toolchain A language level that one target can't build is not a level
The C++20 profile and its MISRA mapping are extended to it, in one pull request with the rule list and the deviation record The coding standard fixes the language standard, so the checks must know the new one first
A decision record replaces ADR-0010 A rule is not loosened or changed without a recorded reason
The release that adopts it lists the new compiler requirement as breaking Callers choose when to move

The same checks in every repository

Check What it catches
Strict docs build, link check, figure and generated-table drift Broken links, stale diagrams, docs that disagree with the code
Host build and tests, clang-tidy, cppcheck Bugs, undefined behaviour, the port contract
clang-format, markdownlint, yamllint Style drift
DCO sign-off, required files, MIT licence Provenance and licensing
The handbook check Rules with an ID, run as code
CI gate One required check that passes only when everything else did

The rules are in the handbook. Every rule has an ID, a level and the check that verifies it.

Supply-chain hygiene

Every third-party GitHub Action is pinned to a commit SHA on a real release tag and reviewed before it is allowed in the organisation; tools without a trusted action are downloaded from their own release and checked against a pinned SHA-256. Dependabot keeps the pins current. Secret scanning with push protection, Dependabot alerts and CodeQL are on for every repository.

Licence and sign-off

Everything is MIT licensed, Copyright (c) 2026 The Kokeb Labs Authors. There is no CLA: you sign off each commit (git commit -s) to certify the Developer Certificate of Origin.