Wi-Fi Target Wake Time Agreements: Handle Teardown and Schedule Changes Without Stalling Traffic
When a TWT agreement ends or changes, retire every application timer and queue dependency tied to the old agreement. Reconcile the current driver state, then use the product’s supported ordinary-send path or a newly confirmed schedule. Do not leave records waiting forever for a wake notification belonging to an agreement that no longer exists.
This guide pins Zephyr 3.7.0’s Wi-Fi management API and implementation. It defines an integration procedure for a driver that actually implements TWT setup, teardown and usable state evidence. It does not certify a board, firmware or AP, and it excludes broadcast-TWT-specific behavior. General DTIM/current comparisons and the initial “requested versus negotiated” power-save checklist are outside scope.
Represent an agreement as an owned lifetime
The 3.7.0 wifi_twt_params structure separates operation, dialog token, flow ID, setup parameters and teardown controls. The dialog token maps requests to responses; the flow ID connects setup with teardown. teardown_all broadens the teardown scope. Flow IDs occupy a small reusable namespace, so a flow number alone cannot identify a permanent agreement across reconnects. Zephyr 3.7.0 TWT parameters and flow information
Keep interface/association lifetime, operation generation, dialog token, negotiated flow ID, accepted parameters and dependent application work in one serialized owner. A scheduled application release should reference that agreement generation. When the generation is retired, cancel the release or reclassify its records before another agreement reuses the flow ID.
| Local state | Permitted interpretation | Queue action |
|---|---|---|
| No confirmed agreement | No usable TWT schedule established | Use qualified ordinary-send policy or report unavailable service |
| Setup pending | Request outstanding, parameters not yet adopted | Retain bounded work without assuming the requested wake time |
| Confirmed agreement | Current accepted flow and schedule known | Schedule only work that can meet its own deadline |
| Teardown/change pending or uncertain | Old schedule is no longer safe to rely on | Invalidate old scheduling dependencies and reconcile |
Decode the response fields correctly
WIFI_TWT_RESP_RECEIVED means a response arrived; it does not mean the AP accepted the request. The separate setup command can report ACCEPT, ALTERNATE, DICTATE or REJECT. Adopt only parameters supported by the driver’s completed negotiation contract and the application’s requirements. A proposed alternate schedule must not be silently treated as the originally requested one. Zephyr 3.7.0 setup commands and response status
The same header distinguishes teardown success from failure. A zero-initialized status field is not completion evidence: process it only as part of the matching documented response or verified readback. Preserve synchronous request failure, no response, explicit rejection and completed teardown as different outcomes.
The management implementation forwards teardown directly to the driver’s set_twt operation. Setup follows additional interface, peer-capability and IP checks controlled by CONFIG_WIFI_MGMT_TWT_CHECK_IP. The generic wrapper returns the driver’s result; it does not itself create a universal asynchronous completion guarantee for every driver. Check the actual driver’s command/event contract before waiting for a callback. Zephyr 3.7.0 wifi_set_twt()
Do not assign interface-wide wake events to every flow
Zephyr 3.7.0 exposes NET_EVENT_WIFI_TWT with TWT parameters and a separate NET_EVENT_WIFI_TWT_SLEEP_STATE. The latter helper sends an integer sleep/awake state for the interface, without a flow ID or dialog token. It cannot by itself prove that a particular old flow still exists or that every queued record may complete. Zephyr 3.7.0 TWT event helpers
Use current flow readback through NET_REQUEST_WIFI_PS_CONFIG where the driver implements it; the returned configuration includes a flow list. If readback is unsupported, require another documented completion and synchronization mechanism from the integration. Do not invent one from periodic wake events. An interface-level awake indication is a scheduling hint within its documented scope, not an application delivery acknowledgement.
Handle replacement and uncertainty deliberately
- Serialize agreement operations. Admit one owned transition for the affected flow set. Record the requested and actual teardown scope. Prevent one worker from issuing teardown-all while another assumes its flow remains active.
- Invalidate dependent timers first. Stop old-generation application releases from scheduling more work. Retain record identities, deadlines and bounded payload ownership; a teardown request does not cancel records already handed to the network stack.
- Resolve the transition. Check the synchronous result and the driver’s supported event/readback path. On timeout or ambiguous status, mark the schedule unknown and reconcile instead of assuming success or repeatedly issuing overlapping commands.
- Select the fallback explicitly. If ordinary connected transmission is supported, release still-useful records through that qualified path. This does not mean forcing the radio permanently awake or assuming immediate delivery. If service cannot be established, expire or retain records according to the declared bounded policy and report the outage.
- Install a replacement only after confirmation. Use the accepted parameters and a new local generation. Re-evaluate queued deadlines; a later wake schedule may make previously admissible work obsolete.
Local generations reject old application tasks, but they cannot manufacture missing identity in a delayed firmware event. If a recycled token/flow event is indistinguishable from current work, use supported event draining, quiescence and state readback before reuse. Without such a boundary, hold the transition as uncertain. Reassociation retires the old association’s agreement ledger even when a future flow reuses its numeric ID.
Qualify teardown while traffic is waiting
Test local single-flow teardown, teardown-all, AP-initiated teardown where exposed, replacement with changed intervals, synchronous command failure, missing completion, disconnect during setup and delayed old work after reconnect. For each case, place numbered records before, during and after the transition. Verify that no record waits indefinitely on the retired schedule and that expired records are not reported as timely delivery.
In a hypothetical logger, flow three schedules a queued sample for the next service period. The AP ends that agreement before the release. A later interface-wide AWAKE event must not revive the old timer. The owner reconciles the flow list, chooses its qualified ordinary-send path for the still-valid sample and records whether the endpoint actually received it.
No Zephyr build, driver event or radio experiment was executed here. The exact API fields and wrapper branches were inspected; the lifecycle is a proposed integration contract. Release only after the chosen driver supplies sufficient completion evidence and the queued-traffic campaign passes. TWT can influence scheduling without becoming an unbounded dependency that stalls the application.
