Zephyr Step/Dir Completion: A GPIO Error Can Consume the Command Without Advancing Position

A stepper controller reports that its commanded steps are complete, but the driver’s position is short of the requested target. Before blaming mechanical slip, inspect whether a failed GPIO operation consumed a step in the software countdown. Zephyr v4.2.0’s common step/direction implementation contains a concrete path where those two counters can diverge.

This article examines that shared implementation, not every Zephyr stepper driver. Its proposed regression uses a fake GPIO backend with no motor attached. The distinction is important: a software position counter does not measure shaft displacement, and an error return from a real GPIO controller does not necessarily prove that no electrical transition occurred.

Trace the failed step before interpreting completion

The pinned common step/direction source performs a step by setting direction, toggling the step signal, and, when dual-edge operation is disabled, toggling it again. It returns early if a GPIO operation reports failure. Only after those operations succeed does it increment or decrement actual_position.

In position mode, however, position_mode_task() discards the return from step_dir_stepper_perform_step(). It continues to the remaining-step update. That update moves a positive or negative command count toward zero, regardless of whether the preceding GPIO sequence succeeded.

When the remaining count is already zero on a later processing pass, the update path raises STEPPER_EVENT_STEPS_COMPLETED and stops the timing source. The shown path does not convert the ignored GPIO error into a failed command result or replenish the lost count. Completion notification therefore cannot, by itself, establish that every attempted step passed its GPIO operations.

Keep three different quantities in the evidence

The first quantity is the command countdown: how many scheduled step attempts remain under this implementation. The second is driver-reported position: the software value updated after successful GPIO operations. The third is physical position: what the motor and load actually did.

Those quantities can disagree for different reasons. An ignored direction-write failure can separate the first two in software. Mechanical stall, electrical timing, or an external driver’s behavior can separate successful software operations from physical movement. Do not combine all of these into a single “missed steps” diagnosis before establishing which boundary failed.

The pinned stepper interface exposes relative movement, reference position, actual-position retrieval, and completion events as distinct operations. Its event vocabulary is not a substitute for examining what a selected implementation actually counts.

For each diagnostic command, retain starting driver position, requested relative displacement, returned command status, later position, received events, and any lower-layer errors. A separate physical observation belongs alongside those records when available, not inside a renamed software counter.

Construct a deterministic failure fixture

Use an isolated fixture that supplies a fake GPIO controller and a controllable timing source to the selected common driver path. Begin at software position zero and request three positive steps. Configure the fake to reject the first direction-setting operation before changing any simulated pin state; allow subsequent GPIO operations to succeed.

Under the examined control flow, the first attempt consumes one remaining count but does not advance the software position. The next two attempts advance position to two while the countdown reaches zero. On the subsequent completion-processing pass, the completion event can be generated even though the original target was three.

These numbers describe a constructed source-level case, not an executed test or an observed motor fault. A runnable regression should record each timing invocation, each GPIO call and return, the simulated pin state, and both counters. Check that it reaches the specific completion branch, rather than merely assuming that a scheduled callback must eventually run.

Repeat with a negative relative command. Also inject failure at the first step toggle and, for the non-dual-edge configuration, at the second toggle. The latter case requires special care: one earlier simulated edge may already have occurred. A real device’s interpretation depends on edge polarity and its electrical interface; a generic retry cannot safely assume that the step did not happen.

Verify the selected backend, not just the shared filename

Confirm that the product’s driver actually delegates position-mode work to this implementation. Record the Zephyr tag, concrete device driver, timing source, GPIO provider, and dual-edge setting. A controller with its own motion engine may use a different path entirely.

The common source schedules further work through its timing-source abstraction. The fixture must respect whether that backend needs rescheduling; otherwise a test can stop before reaching the later zero-count completion check. Event delivery configuration also needs to be known so that absence of a received callback is not mistaken for absence of an internally generated event.

Those checks are supporting scope controls, not an invitation to redesign callback queues. The defect being investigated is the discarded step-operation result followed by countdown consumption. Keep that causal chain visible in the trace and avoid adding unrelated scheduling changes during reproduction.

Define a fault outcome before changing control flow

A product-level repair needs an explicit response to an uncertain pulse outcome. Depending on the qualified mechanism, that may require stopping further command execution, marking position uncertain, reporting a fault, and requiring controlled recovery. It should not simply continue declaring successful motion because the requested number of timer invocations occurred.

Blindly retrying a failed GPIO sequence can produce an extra physical step if an earlier transition already reached the driver. Conversely, decrementing neither counter while continuing indefinitely can create an unbounded command. Define the fault state and permitted recovery first, then review driver changes against that contract.

Comparing final driver position with the expected arithmetic target is a useful additional diagnostic for this path. It is not a physical position check, and it does not justify continuing hazardous motion when the comparison passes. Use independent feedback and appropriate motion protection where the product requires them.

Accept error handling with negative evidence

Keep the original fake-GPIO trace as a regression. After a reviewed correction, require the injected fault to produce the intended fault outcome, not ordinary successful completion. Verify that a clean command still completes, that stop and recovery remain bounded, and that a partial-edge case is reported as uncertain rather than automatically replayed.

No motor, driver patch, GPIO fault injection, or executable test was run for this article. The source review identifies a precise acceptance gap: exhausting a command countdown is weaker evidence than successful pulse generation, and both remain weaker than verified mechanical displacement.

Trend context

The archived Google Trends “embedded os” export covers worldwide web search, all categories, July 19–October 19, 2026. Its RISING related queries include “zephyr os” at +300% and “zephyr” at +40%. These parent-topic figures support Zephyr engineering coverage; they do not measure search growth for stepper errors or this title.