Zephyr OS PWM Capture: Validate the Complete Result After Unit Conversion

A captured PWM waveform is not yet an application measurement. The capture must succeed, its counter values must be converted using the appropriate device timebase, and the application must accept the complete result. In Zephyr OS, checking only whether output variables changed can confuse a partial conversion with a valid period-and-pulse pair.

This discussion follows the Zephyr v4.4.0 single-capture helpers. It proposes a review method for sensor and control interfaces; it does not report executed hardware tests. A controller's capture capabilities, clock stability and electrical signal quality remain board-specific questions.

Separate acquisition from presentation units

The versioned PWM API header implements nanosecond capture as an ordered sequence: acquire local cycle counts, convert the period into the caller's output, then convert the pulse into its output. A conversion error returns immediately. Consequently, callers must not treat both output locations as an accepted pair after a nonzero result. The earlier output may already have changed.

Use temporary output variables and commit them to the application's measurement object only after success. Keep a validity flag and capture identity with the accepted pair. This avoids displaying a fresh period beside an old pulse width when an error occurs during processing. It also makes the failure policy explicit: retain a clearly marked previous measurement, or invalidate the display, rather than silently presenting mixed data.

The official PWM overview describes capture alongside waveform generation. That distinction matters when selecting hardware: a device that generates PWM does not thereby prove that the required capture mode is available. The tagged API remains the version-specific basis for the helper behavior discussed here.

Do not substitute the CPU clock

Captured cycles belong to the PWM device's timebase. A board's CPU frequency is not a safe replacement simply because both quantities are measured in hertz. Review the driver's cycles-per-second reporting and the relevant peripheral clock configuration before calculating duration independently.

If a product changes clocks during operation, identify whether the capture and conversion path has a stable, documented interpretation through that transition. Do not infer a universal atomic relationship from a convenience wrapper. A driver or system policy may need to prevent the transition while a measurement is being acquired and interpreted.

The useful diagnostic record therefore includes the selected device and channel, the requested capture flags, the API result and the operating clock state. This is more informative than logging a suspicious duty-cycle percentage alone.

Derive a ratio only from an accepted pair

Suppose, hypothetically, that an application displays fan-control feedback. Its previous accepted measurement is still available when a new request fails. The display should not divide the new period field by whichever pulse field remains in memory. Instead, the new request produces either a complete accepted pair or an explicit unavailable result.

After acceptance, check the period before division and validate the relationship between pulse and period for the selected signal interpretation. Retain units in variable names or types. Integer calculations should be arranged with their own overflow and rounding considerations; a successful capture API does not validate a later percentage formula.

Distinguish timeout, busy capture and acquisition errors in diagnostics. A timeout suggests that the requested observation did not complete within its waiting budget. It does not by itself prove an electrical disconnection or identify the edge that was missing.

Test the acceptance boundary deliberately

A proposed test can inject a conversion failure through a controlled driver test double and verify that no partial pair reaches consumers. Separately, use an appropriate signal source on a safe bench setup to evaluate the actual capture range and timeout policy. Those are different tests: one checks software publication of results, the other checks device behavior.

The resulting application contract is simple: consumers receive a complete measurement with known units and status. They never have to guess whether an output variable belongs to the latest successful capture.