How armink/flashdb works
1. Repository purpose
- This is FlashDB, an embedded storage library for microcontrollers and other constrained systems.
- The repo is organized around a small core database engine plus a separate flash abstraction layer and multiple platform demos.
2. Core database subsystem
- The main library lives under src/ and inc/.
- src/fdb_kvdb.c implements the key-value database.
- src/fdb_tsdb.c implements the time-series database.
- src/fdb.c, src/fdb_file.c, and src/fdb_utils.c provide shared database logic, record/file handling, and utility functions.
- inc/flashdb.h is the public entry point for consumers of the library.
3. Database modes and responsibilities
- KVDB is for persistent settings, parameters, and small blobs/strings.
- TSDB is for append-heavy timestamped records and log-like data.
- These two modes share common storage primitives but expose different access patterns and metadata handling.
4. Flash abstraction boundary
- port/fal/ contains the Flash Abstraction Layer (FAL).
- FAL isolates FlashDB from device-specific flash drivers and partition layouts.
- Its source files (fal.c, fal_flash.c, fal_partition.c) manage flash devices, partition tables, and low-level read/write/erase operations.
- This boundary is central to the architecture: FlashDB does not talk directly to hardware flash; it talks to FAL.
5. Platform-specific porting layer
- Each demo includes a small platform port that connects FAL to actual flash hardware.
- Examples:
- demos/esp32_spi_flash/components/FlashDB/porting/fal_flash_esp32_port.c
- demos/esp8266_spi_flash/components/FlashDB/porting/fal_flash_esp8266_port.c
- demos/stm32f103ve/applications/fal_cfg.h
- demos/stm32f405rg_spi_flash/drivers/drv_spi_flash.c
- These files are the main hardware boundary and vary by board, flash type, and build system.
6. Demo applications as integration layers
- The demos/ directory shows how to embed FlashDB in real projects.
- There are demos for:
- Linux host simulation
- ESP8266 / ESP32 with SPI flash
- STM32F103VE and STM32F405RG
- STM32F405RG SPI flash
- Each demo wires together platform startup, console output, flash configuration, and database examples.
7. Hardware support structure in MCU demos
- STM32 demos include board bring-up code under drivers/, CMSIS startup/system files, HAL drivers, and linker scripts.
- The ARM-based demos are therefore full firmware projects, not just sample C files.
- This means FlashDB sits above a substantial board-support layer when used on bare metal.
8. Configuration model
- Configuration is split between fdb_cfg.h and fal_cfg.h variants in demos and templates.
- inc/fdb_cfg_template.h is the library-side configuration template.
- port/fal/samples/porting/fal_cfg.h and demo-specific equivalents define flash devices, partitions, and database sizing.
- Architecture-wise, configuration is a cross-cutting layer that determines storage layout, wear behavior, and feature enablement.
9. Samples and usage patterns
- samples/ contains focused examples for:
- basic KVDB usage
- string values
- blob values
- TSDB usage
- These are small application-level references that sit above the core API and show expected data flow: application code calls FlashDB APIs, which call into FAL-backed storage.
10. Testing and verification
- tests/ contains unit/functional test cases for KVDB and TSDB.
- The top-level GitHub workflow under .github/workflows/main.yml provides CI automation.
- So the repo has both embedded demo validation and host/test validation.
11. Zephyr integration
- zephyr/module.yml indicates FlashDB can be consumed as a Zephyr module.
- This is another integration boundary, separate from the standalone demos and MCU board projects.
12. Documentation as architecture map
- docs/ holds the project documentation, API references, porting guides, and per-demo notes.
- The docs reinforce the repo structure: core API, configuration, porting, and platform examples are treated as distinct layers.
13. Typical data flow
- Application code issues KVDB or TSDB operations.
- FlashDB core validates, indexes, and manages records.
- FlashDB delegates physical storage access to FAL.
- FAL routes requests to the platform-specific flash port.
- The port performs erase/read/write on real flash hardware or a host simulation backend.
14. Key architectural takeaway
- The repository is built around a clean separation between:
- portable database logic
- flash/partition abstraction
- board- or OS-specific integration
- If you draw an architecture diagram, the central path should be application → FlashDB core → FAL → hardware flash, with demos/tests/docs orbiting around that core.
Main entry points: fal.c FAL Core · flashdb.h Public API · fdb.c DB Core · fdb_kvdb_tc.c Tests
Components 20
Core DB
Portable FlashDB database engine and public API
- Public API · Library entry point for consumers
inc/flashdb.h - DB Core · Shared database logic and record handling
src/fdb.c - KVDB · Persistent key-value storage for settings and small blobs
src/fdb_kvdb.c - TSDB · Append-oriented timestamped record storage
src/fdb_tsdb.c - Utils · Shared file and utility helpers
src/fdb_file.c - FDB Config · Library-side configuration template
inc/fdb_cfg_template.h
FAL
Flash abstraction and partition routing layer
- FAL API · Flash abstraction layer interface
port/fal/inc/fal.h - FAL Core · FAL runtime and partition management
port/fal/src/fal.c - Flash IO · Device read/write/erase dispatch
port/fal/src/fal_flash.c - Partitions · Partition table and mapping logic
port/fal/src/fal_partition.c - FAL Config · Flash devices, partitions, and storage sizing
port/fal/samples/porting/fal_cfg.h
Demos
Host and MCU integration projects showing deployment patterns
- Linux Demo · Host-side simulation and example app
demos/linux/applications/main.c - ESP Demo · ESP32 and ESP8266 SPI-flash integration projects
demos/esp32_spi_flash/main/main.c - STM32 Demo · Bare-metal STM32 integration with board support packages
demos/stm32f103ve/applications/main.c - SPI Flash Demo · STM32F405RG project using external SPI flash
demos/stm32f405rg_spi_flash/applications/main.c
Support
Documentation, samples, tests, CI, and Zephyr integration
- Samples · Focused KVDB and TSDB example programs
samples/tsdb_sample.c - Tests · KVDB and TSDB functional coverage
tests/fdb_kvdb_tc.c - Docs · API, configuration, porting, and demo guides
docs/README.md - Zephyr Module · Zephyr consumption entry point
zephyr/module.yml - CI · Repository workflow validation
.github/workflows/main.yml
Connections 26
- Public API → DB Core: exports · Public API exposes the core database engine
- DB Core → KVDB: implements · Shared engine powers KVDB operations
- DB Core → TSDB: implements · Shared engine powers TSDB operations
- DB Core → Utils: uses · Core logic relies on file and utility helpers
- KVDB → FAL API: reads/writes via · KVDB storage is delegated through FAL
- TSDB → FAL API: reads/writes via · TSDB storage is delegated through FAL
- FAL API → FAL Core: defines · API surface for the flash abstraction layer
- FAL Core → Partitions: routes · FAL core resolves partition-to-device mapping
- FAL Core → Flash IO: delegates · Core delegates physical flash operations
- Partitions → FAL Config: configured by · Partition layout comes from configuration
- Flash IO → FAL Config: configured by · Flash device definitions come from configuration
- Linux Demo → Public API: uses · Host demo exercises the library API
- Linux Demo → FAL Core: binds to · Host demo connects FlashDB to the FAL backend
- ESP Demo → Public API: uses · ESP projects exercise the library API
- ESP Demo → FAL Core: binds to · ESP projects connect through FAL to flash ports
- STM32 Demo → Public API: uses · STM32 firmware uses the library API
- STM32 Demo → FAL Core: binds to · STM32 firmware connects through FAL to board ports
- SPI Flash Demo → Public API: uses · External SPI-flash firmware uses the library API
- SPI Flash Demo → FAL Core: binds to · Firmware bridges FlashDB to hardware flash support
- Samples → Public API: shows · Examples demonstrate the public API
- Tests → KVDB: verifies · Tests cover KVDB behavior
- Tests → TSDB: verifies · Tests cover TSDB behavior
- Docs → Public API: documents · Documentation explains the core API and usage
- Docs → FAL Core: documents · Docs cover the flash abstraction and porting model
- Zephyr Module → Public API: integrates · Zephyr module consumes the library as a package
- CI → Tests: runs · Workflow provides automated verification