dsh-embedded-workbench 0.7.1

package/skills/embedded-firmware-dev/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: embedded-firmware-dev
+description: "Use when writing or reviewing embedded C firmware, FreeRTOS tasks, ISR handlers, NVM/flash storage, or sensor driver state machines. NOT for documentation-only RTOS references, conceptual RTOS discussions, or bare-metal projects without an RTOS or sensor subsystem."
+---
+
+<HARD-GATE>
+This is a domain implementation skill. If you are planning, designing, or entering plan mode — load `Skill("embedded-workbench")` first to activate the workflow gates (Plan Verification Gate, Approval Gate, Closure Gate). Domain skills carry implementation guidance, not workflow enforcement.
+</HARD-GATE>
+
+# Embedded Firmware Development
+
+## FreeRTOS
+
+- Give each task a clear ownership boundary. Shared resources need a deliberate synchronization strategy.
+- Prefer task notifications for one-to-one wakeups, queues for data transfer, event groups for combined state, mutexes for mutual exclusion, semaphores for one-way signaling.
+- Use a mutex (not binary semaphore) when mutual exclusion matters and priority inheritance is needed.
+- Make every blocking wait explicit: use a timeout unless an infinite wait is deliberate.
+- Keep timer callbacks short and non-blocking — use them to schedule work, not do it.
+- Avoid holding locks across flash, storage, or long operations.
+- Size task stacks from worst-case call chains. Recheck high-water marks after adding buffers or deeper call trees.
+- Use ISR-safe APIs for interrupt-to-task handoff. Keep ISR state capture minimal.
+- Avoid priority inversion: don't hold shared locks across blocking I/O or long processing.
+- If a task can be paused/restarted/signaled from multiple places, define resume, timeout, and recovery paths explicitly.
+- For cross-task pointer ownership: make lifetime and invalidation rules obvious.
+- Prefer the smallest critical section that protects the state transition. Don't wrap whole operations in locks when narrower ordering suffices.
+- For objects handed between threads: define whether the receiver owns, borrows, or copies before crossing the boundary.
+
+## Interrupts / ISR
+
+- Keep the interrupt path short, deterministic, and bounded. Capture minimum state, clear the source, defer expensive work.
+- Do not block, sleep, allocate heap, or call non-ISR-safe APIs from an ISR.
+- Prefer top-half/bottom-half split when the handler needs more than quick state capture and wakeup.
+- Make shared-state ownership explicit. Use minimum synchronization for the data being shared.
+- If an ISR wakes a task, use the ISR-safe RTOS primitive and preserve yield-from-ISR behavior.
+- Define clear read/clear/re-enable ordering to avoid losing edges or creating re-trigger loops.
+- Avoid logging and complex branching in the hot interrupt path.
+- If code runs from both task and ISR context, separate wrappers so the ISR-safe path stays obvious.
+
+## Async Lifecycle Cleanup
+
+- Any async flag (pending, in-progress, busy, data-ready) that can be set during normal operation must be explicitly cleared in every stop, init, reset, power-off, and error-recovery path. A stale flag silently blocks the next operation.
+- When adding a new async operation, audit all lifecycle entry points and ensure each path resets flags to known-safe.
+- Cleanup must happen before any new operation is attempted, not after.
+
+```c
+// CORRECT: every async flag cleared in stop path. No stale state survives restart.
+uint8_t comm_stop_sample(void) {
+    g_comm.data_ready         = false;
+    g_comm.state              = COMM_STATE_IDLE;
+    g_comm.activating         = false;
+    g_comm.command_fail_count = 0;
+    g_comm.protocol_locked    = false;
+    g_comm.communication_lost = false;
+    g_comm.warmup_start_time  = 0;
+    comm_command_complete();                     // Release any pending I/O
+    memset(&g_comm_data, 0, sizeof(g_comm_data));// Reset cached data
+    comm_process_faults(false);                  // Clear fault detection state
+    return COMM_OK;
+}
+
+// BAD: half the flags survive — next start inherits stale state
+void comm_stop_bad(void) {
+    g_comm.state = COMM_STATE_IDLE;              // Only state changed
+    // Missing: data_ready, protocol_locked, communication_lost, fail_count...
+    // Next start: data_ready==true blocks first sample; fail_count persists
+}
+
+// CALLER GUARD: clear stale flags at power-off boundaries before re-init
+void comm_handler(void) {
+    if (!power_get_status() && g_comm.command_pending) {
+        comm_command_complete();                 // Clear before deinit
+    }
+    if (power_get_status()) {
+        comm_state_process();
+    }
+}
+```
+
+## One-Shot Event Consumption
+
+- When a low-level driver produces a transient event that multiple higher-level consumers need, use an atomic check-and-clear (consume) API rather than shared flags each consumer clears manually.
+- Manual clearing by multiple consumers creates races: consumer A clears before B reads, or B reads a flag already set again by the next cycle.
+- The consume primitive returns whether the event occurred and atomically clears the latch — every interested consumer observes the event exactly once per occurrence.
+
+```c
+// Atomic check-and-clear: every consumer sees the event exactly once
+static volatile uint32_t event_latch;
+
+uint32_t event_consume(uint32_t mask) {
+    uint32_t primask = __get_PRIMASK();
+    __disable_irq();
+    uint32_t pending = event_latch & mask;
+    event_latch &= ~mask;               // Clear consumed bits atomically
+    if (!primask) __enable_irq();
+    return pending;                     // Non-zero = event occurred this cycle
+}
+
+// Each consumer independently observes — no races between consumers
+void ui_consume(void) {
+    if (event_consume(EVT_SENSOR_READY)) update_display();
+}
+void log_consume(void) {
+    if (event_consume(EVT_SENSOR_READY)) write_log();
+}
+```
+
+## Storage / Persistence
+
+- Separate object corruption from schema change. Rebuild the whole store only when versioned layout rules require it.
+- Prefer recoverable write paths: write primary → read back and verify → write backup → read back and verify.
+- During delete, reset, or migration, preserve at least one valid recoverable copy.
+- Prefer targeted repair and re-sync over destructive reinitialization.
+- Treat startup repair, steady-state writes, emergency writes, and factory reset as separate paths with explicit guarantees.
+
+## Boundary Analysis
+
+- When thresholds trip at edges, inspect debounce latency, sample timing, and ring-vs-bounded assumptions before tuning constants.
+- When behavior diverges by mode, compare all branches side by side instead of debugging only the failing branch.
+- When a defect appears on only one trigger path, diff which state each caller resets, preserves, or derives.
+- For transient inconsistencies, inspect raw state, derived state, and cached state separately — stale data in any layer masquerades as a timing problem.
+- When a system undergoes mode switch, direction reversal, or re-initialization, allow a bounded tolerance window for the first post-transition deviation. Treating it with steady-state thresholds produces false error accumulation.
+
+## Deep Reference
+
+This skill's `references/` directory contains in-depth material. Load when you need more than the core rules:
+
+| Reference | Topic | Load When |
+|-----------|-------|-----------|
+| `architecture-principles.md` | 12 architecture design principles | Designing module boundaries, state ownership, or GUI architecture |
+| `embedded-patterns.md` | GIF timer safety, async lifecycle, state latches | Debugging timer crashes, stale flags, or state corruption |
+| `lvgl-pitfalls.md` | LVGL layout, alignment, alpha, and mask traps | Debugging LVGL rendering artifacts or HardFault in draw paths |
+
+See also: `Skill("state-machine-design")` for state transition rules, `Skill("debug-methodology")` for debugging process, `Skill("hardfault-triage")` for stack overflow and ISR crash triage.

package/skills/embedded-firmware-dev/references/architecture-principles.md

@@ -0,0 +1,204 @@
+# Embedded Architecture Principles
+
+Design principles extracted from real embedded firmware architecture. Framework-agnostic, applicable across projects.
+
+## 1. Three-Layer Ownership
+
+```text
+BSP (drivers)  →  Components (business logic)  →  GUI (presentation)
+```
+
+Dependencies flow downward. Lower layers never call upward.
+
+| Layer | Owns | Never Owns |
+| ------- | ------ | ------------ |
+| BSP | Hardware registers, timing, raw sensor data | Business decisions, display logic |
+| Components | State machines, policy decisions, data transformation | Pixel rendering, layout |
+| GUI | Widget lifecycle, screen layout, user interaction | Hardware control, policy logic |
+
+**Violation symptoms**: A GUI page directly setting PWM duty. A sensor driver computing display-ready values. A backlight module checking DND state.
+
+**Fix**: Move the decision to the layer that owns the truth. Pass decisions downward as commands, upward as events.
+
+## 2. Single Source of Truth
+
+Every piece of runtime state has **exactly one** owning module.
+
+```text
+Source of Truth     →  Derived State      →  Cached State
+(primary, canonical)   (computed from truth)  (snapshot for performance)
+```
+
+- **Source of truth**: The module that produces or receives the value first. Only this module writes it.
+- **Derived state**: Computed from source of truth. Recalculated when source changes, not cached indefinitely.
+- **Cached state**: Snapshot of derived state for performance. Must be invalidated when source changes.
+
+**Rule**: If two modules both "own" a value, the architecture is wrong. Pick one owner. Other modules read or subscribe.
+
+## 3. Pull Over Push
+
+Prefer **pull mode** (sync on read) over **push mode** (periodic background write).
+
+```text
+Push (fragile):   Background task → write cache → consumer reads cache
+Pull (robust):    Consumer reads → check source freshness → sync if stale → return
+```
+
+**Why**: In embedded systems, "sensor has data" and "cache is refreshed" are concurrent events. A push-based cache updater may not fire before the first consumer reads, producing stale or zero values.
+
+**When push is OK**: High-frequency data where read-time sync is too expensive. But always pair with a freshness timestamp and stale-data fallback.
+
+## 4. Atomic Event Consumption
+
+For transient hardware events that multiple consumers need, use **check-and-clear**:
+
+```c
+bool consume_event() {
+    bool occurred = event_latch;
+    event_latch = false;  // Atomic clear
+    return occurred;
+}
+```
+
+Multiple consumers each call `consume_event()`. Each event is delivered to every interested consumer exactly once per occurrence.
+
+**Anti-pattern**: A shared `bool event_happened` flag that Consumer A clears before Consumer B reads it. Or Consumer B reads a flag already set again by the next cycle.
+
+## 5. Bidirectional State Transitions
+
+Every state that has a forward path **must** have a reverse guard:
+
+```text
+Forward:  Idle → Active    (when start condition met)
+Reverse:  Active → Idle    (when start condition lost)
+```
+
+**Rule**: If a target state's preconditions can become false while already in that state, define a reverse transition. One-way latches will eventually leak incorrect state.
+
+**Check**: For every state variable, ask: "What makes it go back?" If there's no answer, you have a latent bug.
+
+## 6. Lifecycle Completeness
+
+Every async flag (pending, in-progress, busy, data-ready) must be cleared in **every** lifecycle path:
+
+```text
+init() → stop() → reset() → recover() → power_off()
+  ✓        ✓         ✓          ✓           ✓
+```
+
+Missing one path = stale flag = next operation silently blocked with no error.
+
+**Rule**: Cleanup must happen **before** any new operation starts, not after. Otherwise a brief window exists where the old flag aborts the new attempt.
+
+## 7. Grace Windows for Transients
+
+Mode switches, direction reversals, and re-initialization produce transient sensor perturbations. These are **not** genuine errors.
+
+**Pattern**: Allow a bounded tolerance window (1-2 samples) after any mode transition before applying strict error thresholds.
+
+**Without grace window**: First post-switch sample exceeds threshold → false error accumulation → unnecessary fault escalation.
+
+**With grace window**: First 1-2 samples after transition are compared with relaxed thresholds. Steady-state samples use normal thresholds.
+
+## 8. Single Computation Point for Display Strategies
+
+When multiple UI pages need to decide "show value vs. show loading vs. show error":
+
+```text
+Anti-pattern:          Fixed:
+Page A: if (x && !y)   compute_strategy(state, fault) → strategy
+Page B: if (!y && x)   Page A: render(strategy)
+Page C: if (x || z)    Page B: render(strategy)
+```
+
+One function owns the decision. Pages only render the result. This prevents:
+
+- Subtle inconsistencies between pages
+- New conditions added to some pages but not others
+- Impossible-to-test combinatorial behavior
+
+## 9. Minimal Root-Cause Fix
+
+When you find the root cause, the fix is usually **1-2 lines at the data source**.
+
+**Self-check**: If you're changing 5+ call sites to handle a problem, the fix is in the wrong place. Ask: what single state change would make all those call sites correct without modification?
+
+**Example**: A cached value goes stale. Fix: invalidate the cache at the source when the primary value changes (1 line). Anti-pattern: add freshness checks at every consumer (5+ sites).
+
+## 10. Module Boundary Respect
+
+When debugging — before touching any code, map the ownership:
+
+1. Which module owns the truth?
+2. Which module derives policy from it?
+3. Which modules only consume?
+
+**Rule**: Fix the module that owns the truth. Don't patch consumers.
+
+**Example**: A display page showing stale sensor data. The sensor component owns the measurement truth. The display strategy computation owns the loading/error/ready decision. Fix: recompute display strategy when sensor state changes. Don't add per-page staleness checks.
+
+## 11. Layout and Logic Separation
+
+GUI pages must separate **what to show** from **how to show it**.
+
+```c
+// Anti-pattern (mixed):
+page_poll() {
+    value = sensor_read();
+    if (value > threshold) {
+        lv_label_set_text(label, "High");
+        lv_obj_set_style_bg_color(screen, red, 0);
+    }
+}
+
+// Fixed (separated):
+display_model_t model = compute_display_model(sensor_read());
+page_render(model);  // Only sets widgets, no logic
+```
+
+**Rules**:
+
+- Widget creation and styling (`Setup()`) lives in one function. Business logic lives in another.
+- State polling and decision-making return a **display model** struct. The render function consumes it mechanically.
+- No `if (business_condition)` inside a `lv_obj_set_*()` call. Conditions are resolved before rendering.
+- A render function should be callable with any valid display model and produce correct output without knowing how the model was computed.
+
+**Why**: Mixed layout and logic means changing a widget position risks breaking business rules, and changing a threshold risks breaking layout. Separation makes each side testable independently.
+
+## 12. UI Decoupling from Lower Layers
+
+GUI pages must not directly call component or BSP APIs. All data flows through a **presentation interface**.
+
+```c
+// Anti-pattern (coupled) — Page_Sensor.c:
+raw = bsp_i2c_read(0x52, 0x00);  // GUI calling BSP directly
+co2 = raw * 0.01;                 // GUI doing data transformation
+if (co2 > 2000) { ... }           // GUI owning business thresholds
+
+// Fixed (decoupled) — Page_Sensor.c:
+data = env_monitor_get_display_data(SENSOR_CO2);
+render_display_model(data);
+```
+
+**Presentation interface design**:
+
+- Returns pre-processed, display-ready values (no raw ADC counts, no protocol-level flags)
+- Hides whether the data source is local (I2C sensor) or remote (inter-processor protocol from another device)
+- Provides a **display strategy** enum (Ready / Loading / Error / NotApplicable) — the page consumes the strategy, doesn't compute it
+- Single entry point per data domain: `xxx_get_display_data()` rather than 5 different getters
+
+**Benefits**:
+
+- Sensor protocol changes don't touch GUI code
+- Pages work identically whether data comes from local sensor or remote device
+- Pages can be tested with mock display data without hardware
+- New pages for the same data domain reuse the same presentation interface
+
+**Migration path** (when inheriting a coupled codebase):
+
+1. Identify all component/BSP calls in GUI files
+2. Group them by data domain (sensor, motor, fault, etc.)
+3. For each domain, create a thin `xxx_get_display_data()` wrapper
+4. Move data transformation logic from GUI into the wrapper
+5. Replace direct calls in pages with the wrapper
+6. Once all pages use the wrapper, refactor the wrapper's internals freely

package/skills/embedded-firmware-dev/references/embedded-patterns.md

@@ -0,0 +1,95 @@
+# Embedded Engineering Patterns
+
+Recurring patterns from real firmware debugging sessions. Generic and reusable across projects.
+
+## GIF / Animation Timer Lifecycle Safety
+
+Animated UI elements (GIFs, sprite sheets, frame animations) use hardware timers with callbacks. Improper lifecycle management causes HardFault (INVSTATE, corrupted callback pointers).
+
+### Pattern: Generation Counter Guard
+
+**Problem**: A timer callback fires after the animated object has been deleted. The callback's user_data pointer references freed memory.
+
+**Fix**: Maintain a module-level `generation` counter. Increment on each `Create`/`Delete` cycle. The timer callback captures the generation at creation time and compares it to the current value before accessing any object.
+
+```c
+timer_cb:
+  if (captured_generation != global_generation) {
+    // Object was deleted and recreated; safely delete this stale timer
+    lv_timer_del(timer);
+    return;
+  }
+  // Safe to use objects
+```
+
+### Pattern: Cleanup Ordering
+
+**Problem**: Calling `lv_obj_clean()` before deleting the animation timer allows the timer to fire on already-cleaned children.
+
+**Fix**: Always delete the animation timer **first**, then clean the parent object. In page exit functions:
+
+```c
+void page_exit() {
+    anim_timer_del();    // 1. Kill the timer
+    lv_obj_clean(page);  // 2. Then clean objects
+}
+```
+
+### Pattern: Null-After-Free for Static Pointers
+
+**Problem**: A static LVGL object pointer (e.g., `static lv_obj_t *icon`) retains its value after `lv_obj_clean()` frees the underlying object. On re-entry, `lv_img_set_src(icon, ...)` dereferences freed memory.
+
+**Fix**: Set static LVGL pointers to NULL immediately after `lv_obj_clean()` or `lv_obj_del()`. In `Setup()`, guard against NULL before using any cached pointer.
+
+## One-Directional State Latch Anti-Pattern
+
+### Problem
+
+A state variable transitions `A → B` when condition X becomes true, but never transitions back to `A` even when X becomes false again. The one-way latch silently leaks incorrect state to downstream consumers.
+
+### Detection
+
+- State is set in one code path but never reset in any other path
+- The state transition lacks a reverse guard condition
+- A `step()` or `update()` function advances state without checking whether preconditions still hold
+
+### Fix: Bidirectional Guard
+
+Add a reverse check at the top of the state update function, before the forward transition:
+
+```c
+void state_update() {
+    // Reverse guard: if preconditions are lost, go back
+    if (state == Ready && error_is_active()) {
+        state = Recovering;
+    }
+    // Forward transition
+    if (state == Recovering && init_complete()) {
+        state = Ready;
+    }
+}
+```
+
+Key principle: **If a target state's preconditions can become false while already in that state, define a reverse transition.**
+
+## Async Flag Lifecycle Audit Checklist
+
+When adding a new async operation (pending, in-progress, busy, data-ready flag):
+
+- [ ] `init()` — Reset flag to known-safe
+- [ ] `start()` — Set flag before triggering async work
+- [ ] `stop()` — Reset flag
+- [ ] `reset()` — Reset flag
+- [ ] `recover()` — Reset flag
+- [ ] `power_off()` — Reset flag
+- [ ] Callback/timeout handler — Reset flag on completion
+
+**Rule**: The cleanup must happen **before** any new operation is attempted, not after. Otherwise a stale flag can abort the new attempt in a brief race window.
+
+## Derived State Invariant
+
+**Pattern**: When resetting a primary state, also reset all derived/cached values that were computed from it. Otherwise cached values from the old state can satisfy preconditions for a transition that should be blocked.
+
+**Example**: Resetting `display_state` to `WarmingUp` but leaving `cached_value = 42.0` (a valid measurement from the previous Ready state). A downstream check `if (cached_value > 0) → Ready` fires before the warmup timer starts, causing a one-frame Ready leak.
+
+**Fix**: In every reset function, clear derived values alongside the primary state. Use a single reset entry point that handles both.

package/skills/embedded-firmware-dev/references/lvgl-pitfalls.md

@@ -0,0 +1,68 @@
+# LVGL Common Pitfalls
+
+Non-obvious traps when working with LVGL on embedded targets.
+
+## RGB565A8 Custom Decoder Layout
+
+**Pitfall**: Assuming a custom PNG decoder outputs interleaved RGBA pixels.
+
+**Reality**: On 16-bit color depth targets, the decoder separates color and alpha into distinct planes — RGB565 (2 bytes/pixel) for color and A8 (1 byte/pixel) for alpha. Reading as interleaved RGBA produces garbled output.
+
+**Check**: Verify the decoder's output format matches what the draw pipeline expects before writing draw callbacks.
+
+## Alignment Flag Mixing
+
+**Pitfall**: Combining multiple LVGL alignment flags produces unexpected positioning.
+
+**Reality**: LVGL alignment flags are not freely bitwise-combinable. ORing two horizontal flags or two vertical flags produces undefined behavior that depends on internal evaluation order.
+
+**Fix**: Use exactly one horizontal flag ORed with exactly one vertical flag. For non-standard positioning, use `lv_obj_set_pos()` with explicit coordinates after layout.
+
+## Object Cleanup Order and Stale Pointers
+
+**Pitfall**: `lv_obj_clean(parent)` recursively frees children but does not NULL any static pointers that reference those children.
+
+**Fix Pattern**:
+
+```c
+anim_timer_del();      // 1. Kill async operations
+icon = NULL;           // 2. NULL all static pointers
+label = NULL;
+lv_obj_clean(parent);  // 3. Clean the parent last
+```
+
+On page re-entry, always guard with NULL checks before using any cached LVGL object pointer.
+
+## Menu Scroll with Fixed Elements
+
+**Pitfall**: A scrollable menu with header/footer inside the scroll container scrolls those elements along with the content.
+
+**Fix**: Move fixed elements outside the scrollable container:
+
+```text
+Page (flex column)
+├── Header (fixed, outside scroll)
+├── Scroll container (flex grow)
+│   └── Items (scrollable)
+└── Footer (fixed, outside scroll)
+```
+
+## Draw Mask Lifecycle
+
+**Pitfall**: Creating an LVGL draw mask and not removing it before the next draw pass causes unrelated elements to be incorrectly masked.
+
+**Fix**: Always pair mask creation with removal:
+
+```c
+int16_t mask_id = lv_draw_mask_angle_init(&param);
+// ... draw ...
+lv_draw_mask_remove_id(mask_id);
+```
+
+For masks in animation callbacks, store the mask_id and ensure cleanup in the animation's end handler or page exit.
+
+## Alpha Cache Staleness on Overlay Removal
+
+**Pitfall**: Removing a gap/clear overlay from a chart leaves ghost artifacts because the alpha blending cache retains intermediate values.
+
+**Fix**: After removing an overlay, call `lv_obj_invalidate()` on the parent to force a full redraw. For chart widgets, invalidate the entire chart rather than individual series.