token-based high-precision measurement

Author: zekageri

CHANGELOG.md

@@ -9,11 +9,13 @@ All notable changes to this project will be documented in this file.
 - Optional average smoothing in `CpuUsageSample` via `smoothedAverage`, with configurable `smoothingMode` (`None`, `RollingMean`, `Ewma`), rolling window size, and EWMA alpha.
 - `getLastSmoothedAverage()` helper for quickly reading the latest trend/baseline value when smoothing is enabled.
 - `CpuMonitorConfig::usePSRAMBuffers` toggle to prefer PSRAM-backed internal history and callback container/snapshot storage through `ESPBufferManager`, with automatic fallback to normal heap.
+- Token-based measurement API via `startMeasure()` / `stopMeasure(token)` with precise timing fields (`durationUs`, `durationMs`, `durationSec`) and optional per-window CPU usage in `CpuMeasure`.
 
 ### Changed
 - Removed the library-provided global `cpuMonitor`; create and manage your own `ESPCpuMonitor` instance (only one active monitor at a time) and updated examples/docs accordingly.
 - Made `ESPCpuMonitor` non-copyable/movable to prevent accidental double-free of FreeRTOS handles.
 - `toJson()` now exports `avgSmoothed` when smoothing is enabled and a smoothed sample is available.
+- Baseline calibration now tracks idle rates per microsecond so code-path measurements can estimate CPU usage across arbitrary measurement durations.
 
 ## [1.0.1] - 2025-12-03
 ### Fixed

README.md

@@ -14,6 +14,7 @@ ESPCpuMonitor is a tiny C++17 helper that estimates per-core CPU usage on ESP32
 - Optional smoothing helpers for average CPU usage (`RollingMean` or `EWMA`) so you can track baseline/trend load without forcing smoothing globally (disabled by default, fixed-size buffer when enabled).
 - Thread-safe per-sample callbacks for logging, telemetry, or UI updates; swap `enablePerCore` off to collapse cores to an overall average.
 - Manual `sampleNow()` path for users who already have their own schedulers (set `sampleIntervalMs` to `0`).
+- Token-based manual measurement API (`startMeasure()` / `stopMeasure(token)`) with precise microsecond durations and optional per-window CPU usage.
 - Optional CPU temperature readings (current + running average) using the ESP-IDF temperature sensor driver, gracefully disabled when unsupported.
 - Optional ArduinoJson export helper to stream samples over HTTP/MQTT/WebSockets alongside the rest of ESPToolKit.
 
@@ -75,6 +76,25 @@ When you set `sampleIntervalMs` to `0`, call `sampleNow()` on your monitor insta
 If temperature is enabled, `getLastTemperature(current, average)` returns the latest reading and running mean (returns `false` when unsupported or not ready).
 When your feature shuts down (task exit, OTA handoff, mode switch), call `cpuMonitor.deinit()` to release idle hooks and timer resources.
 
+Measure a specific code path:
+
+```cpp
+CpuMeasureToken token = cpuMonitor.startMeasure();
+// do work...
+CpuMeasure result = cpuMonitor.stopMeasure(token);
+
+if (result.valid) {
+    // precise timings
+    double ms = result.durationMs;
+    double sec = result.durationSec;
+
+    // CPU usage for this window (available after calibration)
+    if (result.hasCpuData) {
+        float avg = result.averageUsage;
+    }
+}
+```
+
 ## Gotchas
 - CPU usage numbers are floats in percent so you can see tiny changes; `1.0` means ~1% busy, not 100%. Feel free to round (`%.0f%%`) in your logs/UI if you prefer whole numbers.
 - Allow the calibration window (`calibrationSamples`) to finish before trusting numbers; keep the device as idle as possible during that phase.
@@ -91,6 +111,7 @@ When your feature shuts down (task exit, OTA handoff, mode switch), call `cpuMon
 - `bool getLastSample(CpuUsageSample &out) const` / `float getLastAverage() const` / `float getLastSmoothedAverage() const` – read the latest sample; average/smoothed values return `-1.0f` until ready (or when smoothing is disabled).
 - `bool getLastTemperature(float &currentC, float &averageC) const` – latest temperature and running average; returns `false` if disabled, unsupported, or not yet sampled.
 - `std::vector<CpuUsageSample> history() const` – copy of the ring buffer (size capped by `historySize`, `0` disables storage).
+- `CpuMeasureToken startMeasure() const` / `CpuMeasure stopMeasure(const CpuMeasureToken &token) const` – token-based code-path timing using `esp_timer_get_time()`. Requires `init()`. `stopMeasure()` returns `valid=false` for invalid/stale tokens. `hasCpuData` becomes true once baseline calibration is available.
 - `bool sampleNow(CpuUsageSample &out)` – immediate sampling, useful when periodic timer is disabled.
 - `void onSample(CpuSampleCallback cb)` – subscribe to every stored sample.
 - `void toJson(const CpuUsageSample&, JsonDocument &doc)` – ArduinoJson export helper (compiled only when ArduinoJson is available).
@@ -107,6 +128,7 @@ When your feature shuts down (task exit, OTA handoff, mode switch), call `cpuMon
 - `smoothingAlpha` (default `0.2`) – EWMA alpha (used when `smoothingMode = Ewma`, clamped to `(0.0, 1.0]`).
 
 `CpuUsageSample` contains `timestampUs`, `perCore[portNUM_PROCESSORS]`, `average` (%), `smoothedAverage` (%/NaN when smoothing is disabled), `temperatureC`, and `temperatureAvgC` (NaN when unsupported).
+`CpuMeasure` contains `startedUs`, `endedUs`, `durationUs`, convenience `durationMs`/`durationSec`, start/end core IDs, `idleDelta[]`, and per-window usage (`perCoreUsage[]` + `averageUsage`).
 
 ## Restrictions
 - ESP32 + FreeRTOS (Arduino-ESP32 or ESP-IDF) with `esp_freertos_hooks.h` available.

src/esp_cpu_monitor/cpu_monitor.cpp

@@ -40,6 +40,16 @@ static bool isValidSmoothingMode(CpuSmoothingMode mode) {
 	       mode == CpuSmoothingMode::Ewma;
 }
 
+static float clampUsagePercent(float usage) {
+	if (usage < 0.0f) {
+		return 0.0f;
+	}
+	if (usage > 100.0f) {
+		return 100.0f;
+	}
+	return usage;
+}
+
 void ESPCpuMonitor::resetState(const CpuMonitorConfig &cfg) {
 	config_ = cfg;
 	if (!isValidSmoothingMode(config_.smoothingMode)) {
@@ -56,6 +66,8 @@ void ESPCpuMonitor::resetState(const CpuMonitorConfig &cfg) {
 	}
 	calibrationSamplesNeeded_ = config_.calibrationSamples == 0 ? 1 : config_.calibrationSamples;
 	calibrationSamplesDone_ = 0;
+	calibrationWindowUs_ = 0;
+	calibrationLastSampleUs_ = static_cast<uint64_t>(esp_timer_get_time());
 	hasSample_ = false;
 	calibrated_ = false;
 	history_ = CpuMonitorDeque<CpuUsageSample>(
@@ -76,6 +88,8 @@ void ESPCpuMonitor::resetState(const CpuMonitorConfig &cfg) {
 	for (int i = 0; i < portNUM_PROCESSORS; ++i) {
 		prevIdle_[i] = 0;
 		idleBaseline_[i] = 0.0f;
+		idleBaselineRatePerUs_[i] = 0.0f;
+		calibrationIdleTotal_[i] = 0;
 		lastSample_.perCore[i] = 0.0f;
 		s_idleCount[i] = 0;
 	}
@@ -104,6 +118,10 @@ bool ESPCpuMonitor::init(const CpuMonitorConfig &cfg) {
 	}
 
 	resetState(cfg);
+	measureEpoch_++;
+	if (measureEpoch_ == 0) {
+		measureEpoch_ = 1;
+	}
 
 	if (!mutex_) {
 		mutex_ = xSemaphoreCreateMutex();
@@ -280,6 +298,84 @@ std::vector<CpuUsageSample> ESPCpuMonitor::history() const {
 	return out;
 }
 
+CpuMeasureToken ESPCpuMonitor::startMeasure() const {
+	CpuMeasureToken token{};
+	if (!isInitialized()) {
+		return token;
+	}
+
+	token.valid = true;
+	token.startedUs = static_cast<uint64_t>(esp_timer_get_time());
+	token.startedCore = xPortGetCoreID();
+	for (int i = 0; i < portNUM_PROCESSORS; ++i) {
+		token.idleStart[i] = s_idleCount[i];
+	}
+
+	lock();
+	token.ownerMarker = this;
+	token.epoch = measureEpoch_;
+	token.hasCpuData = calibrated_;
+	for (int i = 0; i < portNUM_PROCESSORS; ++i) {
+		token.idleBaselineRatePerUs[i] = idleBaselineRatePerUs_[i];
+	}
+	unlock();
+
+	return token;
+}
+
+CpuMeasure ESPCpuMonitor::stopMeasure(const CpuMeasureToken &token) const {
+	CpuMeasure result{};
+	if (!isInitialized()) {
+		return result;
+	}
+	if (!token.valid || token.ownerMarker != this) {
+		return result;
+	}
+
+	lock();
+	const uint32_t currentEpoch = measureEpoch_;
+	unlock();
+	if (token.epoch != currentEpoch) {
+		return result;
+	}
+
+	result.valid = true;
+	result.startedUs = token.startedUs;
+	result.endedUs = static_cast<uint64_t>(esp_timer_get_time());
+	result.durationUs = result.endedUs >= result.startedUs ? result.endedUs - result.startedUs : 0;
+	result.durationMs = static_cast<double>(result.durationUs) / 1000.0;
+	result.durationSec = static_cast<double>(result.durationUs) / 1000000.0;
+	result.startedCore = token.startedCore;
+	result.endedCore = xPortGetCoreID();
+
+	for (int i = 0; i < portNUM_PROCESSORS; ++i) {
+		const uint64_t currentIdle = s_idleCount[i];
+		result.idleDelta[i] = currentIdle - token.idleStart[i];
+	}
+
+	if (!token.hasCpuData || result.durationUs == 0) {
+		return result;
+	}
+
+	const float durationUs = static_cast<float>(result.durationUs);
+	float usageSum = 0.0f;
+	for (int i = 0; i < portNUM_PROCESSORS; ++i) {
+		const float baselineRate = token.idleBaselineRatePerUs[i];
+		const float expectedIdle = baselineRate * durationUs;
+		if (expectedIdle <= 0.0f) {
+			return result;
+		}
+		const float idleRatio = static_cast<float>(result.idleDelta[i]) / expectedIdle;
+		const float usage = clampUsagePercent(100.0f * (1.0f - idleRatio));
+		result.perCoreUsage[i] = usage;
+		usageSum += usage;
+	}
+
+	result.hasCpuData = true;
+	result.averageUsage = usageSum / static_cast<float>(portNUM_PROCESSORS);
+	return result;
+}
+
 bool ESPCpuMonitor::sampleNow(CpuUsageSample &out) {
 	if (!isInitialized()) {
 		ESP_LOGE(TAG, "Call init() before sampleNow()");
@@ -364,21 +460,30 @@ bool ESPCpuMonitor::computeSampleLocked(CpuUsageSample &out) {
 	float perCoreUsage[portNUM_PROCESSORS] = {};
 	float avg = 0.0f;
 	uint64_t nowUs = esp_timer_get_time();
+	uint64_t deltaUs = 0;
+	if (nowUs > calibrationLastSampleUs_) {
+		deltaUs = nowUs - calibrationLastSampleUs_;
+	}
+	calibrationLastSampleUs_ = nowUs;
+	const float deltaUsFloat = static_cast<float>(deltaUs);
 
 	for (int i = 0; i < portNUM_PROCESSORS; ++i) {
 		uint64_t currentIdle = s_idleCount[i];
 		uint64_t deltaIdle = currentIdle - prevIdle_[i];
 
 		if (!calibrated_) {
 			idleBaseline_[i] += static_cast<float>(deltaIdle);
+			calibrationIdleTotal_[i] += deltaIdle;
 		} else {
 			float baseline = idleBaseline_[i] <= 0.0f ? 1.0f : idleBaseline_[i];
-			float idleRatio = baseline > 0.0f ? static_cast<float>(deltaIdle) / baseline : 0.0f;
-			float usage = 100.0f * (1.0f - idleRatio);
-			if (usage < 0.0f)
-				usage = 0.0f;
-			if (usage > 100.0f)
-				usage = 100.0f;
+			if (idleBaselineRatePerUs_[i] > 0.0f && deltaUs > 0) {
+				const float expectedIdle = idleBaselineRatePerUs_[i] * deltaUsFloat;
+				if (expectedIdle > 0.0f) {
+					baseline = expectedIdle;
+				}
+			}
+			const float idleRatio = baseline > 0.0f ? static_cast<float>(deltaIdle) / baseline : 0.0f;
+			const float usage = clampUsagePercent(100.0f * (1.0f - idleRatio));
 			perCoreUsage[i] = usage;
 			avg += usage;
 		}
@@ -387,13 +492,25 @@ bool ESPCpuMonitor::computeSampleLocked(CpuUsageSample &out) {
 	}
 
 	if (!calibrated_) {
+		calibrationWindowUs_ += deltaUs;
 		calibrationSamplesDone_++;
 		if (calibrationSamplesDone_ >= calibrationSamplesNeeded_) {
+			const float calibrationWindowUs = static_cast<float>(calibrationWindowUs_);
+			const float fallbackWindowUs =
+			    static_cast<float>(config_.sampleIntervalMs) * 1000.0f;
 			for (int i = 0; i < portNUM_PROCESSORS; ++i) {
 				idleBaseline_[i] /= static_cast<float>(calibrationSamplesNeeded_);
 				if (idleBaseline_[i] < 1.0f) {
 					idleBaseline_[i] = 1.0f;
 				}
+				if (calibrationWindowUs > 0.0f) {
+					idleBaselineRatePerUs_[i] =
+					    static_cast<float>(calibrationIdleTotal_[i]) / calibrationWindowUs;
+				} else if (fallbackWindowUs > 0.0f) {
+					idleBaselineRatePerUs_[i] = idleBaseline_[i] / fallbackWindowUs;
+				} else {
+					idleBaselineRatePerUs_[i] = 0.0f;
+				}
 			}
 			calibrated_ = true;
 			ESP_LOGI(

src/esp_cpu_monitor/cpu_monitor.h

@@ -111,6 +111,39 @@ struct CpuUsageSample {
 	float temperatureAvgC = std::numeric_limits<float>::quiet_NaN();
 };
 
+struct CpuMeasureToken {
+	bool valid = false;
+	uint64_t startedUs = 0;
+	int startedCore = -1;
+	uint64_t idleStart[portNUM_PROCESSORS]{};
+	float idleBaselineRatePerUs[portNUM_PROCESSORS]{};
+	const void *ownerMarker = nullptr;
+	uint32_t epoch = 0;
+	bool hasCpuData = false;
+};
+
+struct CpuMeasure {
+	CpuMeasure() {
+		for (int i = 0; i < portNUM_PROCESSORS; ++i) {
+			perCoreUsage[i] = std::numeric_limits<float>::quiet_NaN();
+		}
+		averageUsage = std::numeric_limits<float>::quiet_NaN();
+	}
+
+	bool valid = false;
+	bool hasCpuData = false;
+	uint64_t startedUs = 0;
+	uint64_t endedUs = 0;
+	uint64_t durationUs = 0;
+	double durationMs = 0.0;
+	double durationSec = 0.0;
+	int startedCore = -1;
+	int endedCore = -1;
+	uint64_t idleDelta[portNUM_PROCESSORS]{};
+	float perCoreUsage[portNUM_PROCESSORS]{};
+	float averageUsage = std::numeric_limits<float>::quiet_NaN();
+};
+
 using CpuSampleCallback = std::function<void(const CpuUsageSample &)>;
 
 class ESPCpuMonitor {
@@ -136,6 +169,9 @@ class ESPCpuMonitor {
 	bool getLastTemperature(float &currentC, float &averageC) const;
 	std::vector<CpuUsageSample> history() const;
 
+	CpuMeasureToken startMeasure() const;
+	CpuMeasure stopMeasure(const CpuMeasureToken &token) const;
+
 	// Trigger sampling immediately (useful when sampleIntervalMs == 0)
 	bool sampleNow(CpuUsageSample &out);
 
@@ -170,6 +206,11 @@ class ESPCpuMonitor {
 	CpuMonitorConfig config_{};
 	uint64_t prevIdle_[portNUM_PROCESSORS];
 	float idleBaseline_[portNUM_PROCESSORS];
+	float idleBaselineRatePerUs_[portNUM_PROCESSORS];
+	uint64_t calibrationIdleTotal_[portNUM_PROCESSORS];
+	uint64_t calibrationWindowUs_ = 0;
+	uint64_t calibrationLastSampleUs_ = 0;
+	uint32_t measureEpoch_ = 0;
 	CpuUsageSample lastSample_{};
 	bool hasSample_ = false;
 	bool calibrated_ = false;