The goal is not to replace the detailed documentation for each module.
These libraries are all small, but they are not random utilities. Together they form a set of shared infrastructure for building embedded application code that is: - more consistent - easier to reason about - easier to extend - less likely to devolve into every subsystem inventing its own incompatible habits Which, naturally, is what happens the moment shared infrastructure is missing. # Design philosophy of the shared library layer Before going into the individual libraries, it helps to understand the common design pattern behind them.These libraries are not trying to be a giant framework. They are trying to provide **targeted, reusable building blocks** for recurring embedded problems:
- reporting success and failure consistently - logging runtime behavior in a uniform way - storing shared variable-sized state in a controlled memory region - scheduling work by discrete priority - decoding and dispatching incoming protocol messages to the correct subsystem The philosophy behind them is mostly this: ### Centralize recurring patterns If every module invents its own result codes, logging style, queueing scheme, and packet dispatching logic, the system becomes harder to maintain very quickly. These libraries centralize those patterns so the rest of the application can focus on subsystem logic instead of re-solving the same infrastructure problems over and over. ### Keep APIs small and practical The libraries generally expose narrow APIs with very specific purposes. ### Prefer explicit ownership and caller-provided resources Several of these modules rely on the caller to provide memory, configuration, or queue storage.That is not accidental. It keeps ownership visible and lets the application control where resources live.
### Separate policy from mechanism where useful A few libraries expose a generic interface while allowing board-specific or implementation-specific backends. Examples: - the logging API is conceptually transport-agnostic even though the current implementation uses UART - the packet dispatcher API is conceptually about routing decoded packets even though the current implementation uses FreeRTOS queues and tasks - the KV pool lets callers decide where metadata and storage memory live ### Be honest about constraints These are embedded libraries and we are not that good at coding. A lot of their usefulness depends on respecting their assumptions: - some are single-consumer by design - some are not ISR-safe - some assume static lifetime of configuration objects - some have concurrency limitations that matter a lotThat is why documentation matters here. These modules are only “simple” if you already know their rules.
# How the libraries fit together At a system level, the libraries can be thought of as falling into a few categories. ### Core utility infrastructure These are foundational and broadly reusable: - `result` - `logging`They define how modules report status and how the system reports runtime information.
### Storage and local scheduling infrastructure These are reusable building blocks for internal system behavior: - `bucketed_pqueue` - `kv_pool` They solve internal resource management and work scheduling problems. ### Communication and protocol infrastructure These are more application-flow oriented: - packet dispatcher / decoding task - packet dispatcher macrosThey take incoming protocol messages and move them to the right processing logic.
A good mental model is: - `result` defines how functions communicate success and failure - `logging` defines how the system communicates information outward - `bucketed_pqueue` defines how work can be prioritized internally - `kv_pool` defines how variable-sized keyed data can be stored safely in managed memory - the dispatcher layer defines how external messages enter the application and get routed to the correct handlers