feat: unify app_utils/app_clock headers shared by the fleet

Merged from the three drifted hand-copies in TrackBackFwd, healthy-band-nrf
and zephyr_gateway_fwd:
- as_u8s(T&) overloads and deferrer (band/hub side)
- hexdump, add_overflow, constrain_value_in_range_static, to_mac_string
  (TrackBackFwd side)
- add_overflow now returns std::expected directly instead of the app_result
  alias; to_mac_string guarded by __cpp_lib_format for GCC 12 toolchains
- app_clock.hpp now() selects k_uptime_ticks / esp_timer_get_time via
  __ZEPHYR__ / ESP_PLATFORM; fixed doc comment (microseconds, not ms)
- dropped vestigial esp_err.h/esp_system.h/FreeRTOS.h includes

Dual build glue: ESP-IDF component (root CMakeLists) + Zephyr module (zephyr/).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-15 15:30:28 +08:00
co-authored by Claude Fable 5
commit c948c7565c
7 changed files with 444 additions and 0 deletions
+36
View File
@@ -0,0 +1,36 @@
# app_common
Shared header-only utilities for the TrackBackFwd / healthy-band-nrf /
zephyr_gateway_fwd fleet. Single source of truth for code that used to be
hand-copied (and had drifted) between the three repos.
## Contents
- `inc/app_utils.hpp` — byte/span casts (`as_bytes`, `as_u8s`), `overloads`,
`try_get`/`try_get_ref`, `deferrer`, `hexdump`, `add_overflow`,
`constrain_value_in_range_static`, `to_mac_string` (only when the toolchain
has `<format>`; guarded by `__cpp_lib_format`).
- `inc/app_clock.hpp` — monotonic microsecond `TrivialClock`. The only
OS-specific code in this repo: `now()` is `k_uptime_ticks()` on Zephyr and
`esp_timer_get_time()` on ESP-IDF, selected by `__ZEPHYR__` / `ESP_PLATFORM`.
- `inc/app_clock_instant.hpp``Instant`, Rust-style elapsed-time helper on
top of `clock_t`. Pure `std::chrono`, no OS dependency.
Everything requires C++23 (all consumers build with `-std=gnu++23` /
`CONFIG_STD_CPP2B`).
## Consuming
**ESP-IDF**: add as a git submodule under `components/app_common`. The root
`CMakeLists.txt` registers the component; add `app_common` to your `REQUIRES`.
**Zephyr**: add as a git submodule (e.g. `modules/app_common`) and append it to
`EXTRA_ZEPHYR_MODULES` in the application CMakeLists before
`find_package(Zephyr)`. The include directory is registered globally; targets
`app_common` / `app_utils` / `app_utils_clock` exist for explicit linking.
## Rules
- Nothing platform-specific beyond the `app_clock.hpp` seam. If a helper needs
ESP-IDF or Zephyr APIs, it belongs in the consuming repo, not here.
- Never copy these headers back into a consumer repo. Bump the submodule.