xmBase · Σ

Foundation layer for the XMotion family — logging and common types.
The substrate every other component plugs into.

---

xmBase is the foundation of the XMotion product family. It provides the low-level utilities shared across components:

• Telemetry API — the stateless XMotion instrumentation surface (ADR 0004): four verbs (event/metric/scope/signal) + health, callable from a 1 kHz control loop; all machinery lives in the optional xmTelemetry SDK, bound at runtime.
• Logging — one API with telemetry: the XM_* macros (XM_INFO, XM_WARN_STREAM, …) ARE the telemetry event() verb (the former XLOG_* spelling is gone — clean break). They are backed by a built-in, dependency-free console binding (synchronous, thread-safe, XM_LOG_LEVEL env config); when an application binds the xmTelemetry SDK, the same call sites gain RT-safe capture, flight recording, and export — with zero code changes.
• Common types — the shared geometry/primitive type vocabulary (xmbase/types/, namespace xmotion) spoken by both the driver layer (xmDriver) and the motion layer (xmNavigation).

Driver/control interfaces are intentionally not here — they belong to their owning component (xmDriver's HAL). Keeping xmBase free of upper-layer specifics is a load-bearing design rule.

It builds either standalone or embedded as a module in another project, and ships its own CI + Debian packaging so downstream components can consume released artifacts rather than source.

Part of the XMotion family — see the umbrella. Sibling components include xmNavigation (motion algorithms) and xmDriver (host hardware drivers).

Layout

Headers live under include/xmbase/; the compiled logging sources under src/. Everything builds into one CMake target, xmotion::xmBase.

Path	Description
include/xmbase/telemetry/	the instrumentation API: logging macros (XM_*, soft-RT via the event() verb), metric/scope/signal verbs, context spine, binding seam
include/xmbase/types/	header-only common types: base_types.hpp, geometry_types.hpp
src/	the compiled telemetry bindings (console default + unbound fallback)

Build

mkdir build &&cd build
cmake ..
make -j

Key options: BUILD_TESTING (build tests, default OFF), ENABLE_LOGGING (default ON),

Telemetry & logging

API documentation lives in docs/telemetry/: guide (how to instrument: logging, metrics, traces, signals, health) · reference (every symbol + contract). Runnable reference examples: the examples tour — hot loop, trace pipeline, worker-pool context discipline, device health, a complete custom binding, logging, types. The module design documents live with the xmTelemetry SDK (privately maintained — available for production integrations).

One front-end (format strings use fmt {} syntax, not printf):

#include"xmbase/telemetry/telemetry.hpp"// the one instrumentation headerXM_INFO("motor speed: {} RPM", speed);
XM_WARN_STREAM("temp " << t << " C");

A dedicated hard-RT path (the lock-free ring that will become the xmTelemetry SDK's capture channel) exists as private implementation under src/logging/ and is CI-tested; it re-emerges through the SDK so that XM_* itself is RT-safe. See docs/logging.md.

Environment configuration

• XM_LOG_LEVEL: 0–6 (0: TRACE, 1: DEBUG, 2: INFO, 3: WARN, 4: ERROR, 5: FATAL, 6: OFF)

License

Apache-2.0 — see LICENSE and NOTICE. First-party code only; bundled third-party components retain their own licenses.