Zephyr OS ADC Sequences: Size the Buffer for Channel Sets and Repeated Samplings

An ADC buffer can contain more than one value per sampling, and a sampling sequence can contain more than one channel set. Before diagnosing implausible sensor readings, check that the producer and consumer agree on those two dimensions. Confusing channel order with application sensor order can produce believable values attached to the wrong signal.

This article uses the Zephyr v4.4.0 sequence API and shared ADC context implementation. The example is hypothetical. It addresses buffer interpretation and sequence progression, not analog accuracy, settling time or a measured sampling-rate claim.

Describe the buffer before allocating it

The tagged ADC sequence definition orders selected channels by increasing channel ID within each sampling. Consecutive samplings follow in the buffer. The normal sequence length is one initial sampling plus extra_samplings; buffer_size is expressed in bytes. The driver must reject inadequate capacity. Sample representation also depends on the selected configuration and driver requirements, so resolution is not a reason to assume tightly packed arbitrary-width values.

For example, suppose an application selects channels 1, 4 and 7, requests two extra samplings, and the particular driver uses two-byte sample containers for that configuration. A complete normally progressing sequence needs nine containers, or eighteen bytes. The first three belong to channels 1, 4 and 7, followed by the same ordering for each later sampling. This arithmetic is conditional on the stated container format, not a universal ADC storage rule.

Write the channel-to-sensor mapping explicitly beside the consumer. If a sensor is removed from the mask, recompute both capacity and indexing. Keeping a former three-column decoder after switching to two channels can mislabel every row after the first value without producing an obvious out-of-bounds access.

Repeating a sampling does not append another row

Callback decisions add another distinction. The repeat action replaces the most recent sampling's positions rather than advancing to a new row. In the versioned shared ADC context, repeat keeps the sampling index unchanged and asks the driver's buffer-pointer hook to reuse the current positions. Normal continuation advances the index until the requested sequence is complete.

A callback that rejects a transient reading can therefore cause more physical acquisition attempts than the number of rows ultimately retained. A consumer must not treat callback count as the number of stored rows. If the application needs every rejected observation for diagnostics, arrange a separate bounded record of those observations rather than expecting them in the final sequence buffer.

Any acceptance rule also needs an exit policy. An indefinitely repeated unacceptable sample can prevent the planned sequence from finishing. Decide how to report that condition using the application's supported control paths; do not turn repetition into an unbounded hidden retry loop.

Keep sampling interval separate from layout

Increasing the interval changes when acquisition is requested, not the number of channels in each row. Likewise, choosing additional samplings changes retained sequence capacity; it is not the same request as hardware oversampling or averaging. Keep those settings separate in configuration reviews and user interfaces.

The shared context contains handling for requests arriving while a sampling is still outstanding. That implementation detail is a reason to inspect the actual driver and its timer arrangement before claiming a precise schedule. A correctly sized buffer cannot establish that the requested timing was achieved.

Validate the decoder with identifiable inputs

A useful proposed bench test applies distinct, safe levels to each selected input and checks channel identity across several rows. Repeat after changing the channel mask. Separately exercise callback repetition with controlled software input and verify that the replacement does not advance the destination row.

For an early-finish callback, report only the accepted populated portion; do not present the unused tail of a preallocated buffer as new measurements. Preserve sequence status alongside the data. The goal is a clear contract between acquisition and decoding: which channel set was captured, how many rows are valid, and how each stored value maps back to the intended signal.