Non-Blocking Patterns
Keep the main loop responsive and make timing behavior testable. Prefer C/C++
patterns that can be compiled for the exact board; use Python only for relevant
test or log analysis tooling.
Intake
Record board/core version, task periods, deadlines, maximum work duration,
input bounce, serial/network behavior, watchdog policy, interrupt constraints,
and the safety response for missed deadlines.
Process
- List each periodic or event-driven task with period, deadline, and worst-case
work. Identify any blocking library call.
- Replace long
delay() calls with unsigned wrap-safe elapsed checks such as
if (static_cast<unsigned long>(now - last) >= period). Use hardware timers
or RTOS tasks only when board and framework support is confirmed.
- Model multi-step work as an explicit state machine with bounded transitions;
do not hide waits inside a helper.
- Debounce inputs using a stable-state timer or event filter, not a blocking
pause. Bound serial parsing, network retries, and sensor conversion waits.
- Define watchdog feeding, output inhibit, timeout, and recovery behavior.
- Measure loop latency and task jitter under representative logging, radio,
storage, and actuator load.
Anti-rationalization
| Shortcut |
Response |
| "A shorter delay is fine." |
It is still blocking; show the deadline and replace it. |
| "The loop is fast on USB." |
Measure with the actual radio, storage, and actuator load. |
| "The enum makes it a state machine." |
Require timed transitions, explicit entry/exit, and timeout behavior. |
| "The watchdog can be fed everywhere." |
Define ownership and fail-safe behavior; do not mask a stuck task. |
"millis() never wraps." |
Use unsigned subtraction and test the wrap boundary. |
Verification
- No unbounded blocking call remains in the time-critical path without a
documented reason and timeout.
- Debounce, wraparound, timeout, and missed-deadline cases have tests.
- Exact-target compile proof and timing/serial evidence are separate.
- Outputs enter a safe state when a task, sensor, or communication path times
out.
Shared output contract
Use the shared Arduino skill contract:
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.
1---
2name: non-blocking-patterns
3description: Use when Arduino or embedded C++ code uses delay(), needs button debouncing, periodic work, cooperative scheduling, watchdog-safe timing, state machines, or latency/jitter control under sensor, network, or motor load.
4metadata:
5 triggers: "delay, millis, debounce, timing, scheduler, state machine, watchdog, jitter"
6 attribution: "Adapted from embedded C++ timing practice and the repository's existing code-generator patterns."
7---
8
9# Non-Blocking Patterns
10
11Keep the main loop responsive and make timing behavior testable. Prefer C/C++
12patterns that can be compiled for the exact board; use Python only for relevant
13test or log analysis tooling.
14
15## Intake
16
17Record board/core version, task periods, deadlines, maximum work duration,
18input bounce, serial/network behavior, watchdog policy, interrupt constraints,
19and the safety response for missed deadlines.
20
21## Process
22
231. List each periodic or event-driven task with period, deadline, and worst-case
24 work. Identify any blocking library call.
252. Replace long `delay()` calls with unsigned wrap-safe elapsed checks such as
26 `if (static_cast<unsigned long>(now - last) >= period)`. Use hardware timers
27 or RTOS tasks only when board and framework support is confirmed.
283. Model multi-step work as an explicit state machine with bounded transitions;
29 do not hide waits inside a helper.
304. Debounce inputs using a stable-state timer or event filter, not a blocking
31 pause. Bound serial parsing, network retries, and sensor conversion waits.
325. Define watchdog feeding, output inhibit, timeout, and recovery behavior.
336. Measure loop latency and task jitter under representative logging, radio,
34 storage, and actuator load.
35
36## Anti-rationalization
37
38| Shortcut | Response |
39|---|---|
40| "A shorter delay is fine." | It is still blocking; show the deadline and replace it. |
41| "The loop is fast on USB." | Measure with the actual radio, storage, and actuator load. |
42| "The enum makes it a state machine." | Require timed transitions, explicit entry/exit, and timeout behavior. |
43| "The watchdog can be fed everywhere." | Define ownership and fail-safe behavior; do not mask a stuck task. |
44| "`millis()` never wraps." | Use unsigned subtraction and test the wrap boundary. |
45
46## Verification
47
48- No unbounded blocking call remains in the time-critical path without a
49 documented reason and timeout.
50- Debounce, wraparound, timeout, and missed-deadline cases have tests.
51- Exact-target compile proof and timing/serial evidence are separate.
52- Outputs enter a safe state when a task, sensor, or communication path times
53 out.
54
55## Shared output contract
56
57Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
58state assumptions, required tools and versions, implementation steps,
59tests/evidence by proof stage, known limitations, and recovery/security notes.
wedsamuel1230