# Hardware Meeting — v2.8 Fleet Mitigation & v2.9 Architecture
**Date:** 2026-05-18  
**Participants:** Fábio Cunha (FW Lead), [HW Engineer]  
**Objective:** Align on (A) what we can do RIGHT NOW with the 40 existing v2.8 boards, and (B) what schematic changes are required for v2.9 to prevent these problems permanently.

---

## PART A — The 40 Existing v2.8 Devices

> These boards are bought and assembled. We cannot change the hardware. Everything here is about firmware workarounds and operational procedures.

### A.1 — Problem: Devices Are Un-brickable Without Opening the Case

**Root Cause:**  
The 3.3V regulator `EN` is hardwired to `VSYS` (Always-On). The reed switch is on the IO Expander (P5), so it cannot pull `EN` LOW or trigger a hardware reset. If firmware crashes, the device stays powered with no way to force a reboot externally.

**Firmware Workaround (already implemented in branch):**  
We built a 3-layer software recovery chain:

| Layer | Mechanism | Trigger |
|-------|-----------|---------|
| 1. Clean Reboot | `esp_restart()` | 5-second magnet hold |
| 2. Hardware Watchdog | ESP32-S3 TWDT forces reset | 10-second hold (firmware is deadlocked) |
| 3. Safe Mode | Boot into USB-flashable infinite loop | Magnet still held at boot time |

**✅ This works.** Tested and validated. The technician holds a magnet for 15 seconds → device reboots into Safe Mode → USB cable connects → `idf.py flash` works.

**⚠️ Limitation:** This relies on the reed switch polling task being alive. If a crash corrupts FreeRTOS itself (scheduler destroyed), the TWDT may not fire. This is an extremely rare edge case, but it exists.

**🔴 Question for Afonso:**
> Can we bodge-wire any of the 40 existing boards to add a physical reset path? For example, solder a wire from the reed switch pad to `CHIP_PU` through a small RC delay circuit? Or is the board layout too tight?

---

### A.2 — Problem: Flashing Requires Tweezers

**Root Cause:**  
No BOOT or RESET buttons on the PCB. To enter Download Mode, you must short CON header pins with tweezers:
- Hold Pin 5 (`IO0_LCD_RST`) → GND (Pin 6)
- Momentarily short Pin 2 (`EN`) → GND (Pin 6)

**Workaround:**  
The UART method with a USB-to-UART adapter + auto-reset circuit (DTR/RTS on `EN` and `IO0`) works reliably. This is the recommended method for factory production runs.

**🔴 Question for Afonso:**
> For the 40 boards in production — should we buy UART adapters with auto-reset for the hotel technicians? Or do we rely entirely on the 15-second magnet recovery (FW-based)?

---

### A.3 — Problem: FSM Gets Stuck in SLEEP State (15 Devices Affected)

**Root Cause:**  
In `fsm.c`, when `esp_light_sleep_start()` fails (PIR motion during sleep entry), the FSM never posts `FSM_EVENT_WAKEUP`. The device stays in SLEEP state but is physically awake — no telemetry, no logs, appears dead.

**Impact:** 6 confirmed stuck, 9 suspected. These devices drain battery silently.

**Fix:** 1-line code change (add `fsm_post_event(FSM_EVENT_WAKEUP)` to the failure branch). This is **FW-205** — ready to implement immediately.

**🟡 Discussion point:**
> This is a firmware bug, not hardware. But it has fleet impact. We need to decide: do we OTA this fix to the 40 deployed devices, or wait for the next full firmware release?

---

### A.4 — Problem: PIR Sensor Noise Causes "Insomnia" (Battery Drain)

**Root Cause:**  
GPIO44 PIR sensor triggers false positives every 3–5 seconds, preventing the device from entering sleep. Battery drains over 5+ days without any cloud notification. Eventually causes brownout → RTC corruption (year 2089 bug).

**Current Status:** FW-198 is in TESTING.

**🔴 Question for Afonso:**
> Is the PIR noise a hardware sensitivity issue (component tolerances, layout crosstalk, missing filtering capacitor)? Or is it purely a firmware debounce problem? Do we need a hardware filter (e.g., RC on the PIR output) for v2.9?

---

## PART B — v2.9 Schematic Changes Required

> These are the 4 architectural changes we need to discuss for the next PCB spin.

### B.1 — Reed Switch → Dedicated RTC GPIO

| Aspect | v2.7 | v2.8 | v2.9 Target |
|--------|------|------|-------------|
| **Pin** | GPIO43 (TX0) | IO Expander P5 | Dedicated RTC GPIO |
| **Deep Sleep Wake** | Yes (with UART conflict) | No | Yes (EXT1, no conflicts) |
| **Hardware Reset** | Could cut power | No | Via supervisor IC |

**Action:** Move reed switch from PCAL9538A P5 to a non-strapping RTC GPIO.  
**Constraint:** Must NOT be GPIO0, GPIO3, GPIO45, GPIO46 (strapping pins).

**🔴 Decision needed:**
> Which RTC GPIO is available? Need Afonso to check the current pin allocation and suggest the best candidate.

---

### B.2 — Hardware Hard-Reset (Supervisor IC)

**Goal:** 10+ second magnet hold → pulls `CHIP_PU` LOW → unconditional hardware reset, regardless of firmware state.

**Options to discuss:**

| Option | IC | Cost | Package | Iq | JLCPCB? |
|--------|-----|------|---------|-----|---------|
| A | LTC2950 | ~$2.50 | DFN-6 | 6µA | ❓ Check |
| B | MAX16054 | ~$1.80 | SOT-23-6 | 1.5µA | ❓ Check |
| C | TPS3420 | ~$0.80 | SOT-23-5 | 0.5µA | ❓ Check |
| D | Passive RC + MOSFET | ~$0.15 | Discretes | <1µA | ✅ |

**🔴 Decisions needed:**
> 1. IC vs passive RC — what does Afonso recommend for timing precision vs cost?
> 2. What's the target hold duration? (Currently proposed: 10 seconds)
> 3. Budget per unit for this sub-circuit?

---

### B.3 — Soft-Latch Power Circuit (Replace Always-On)

**Current v2.8:** `EN` hardwired to `VSYS` → board is always on.  
**v2.9 target:** Soft-latch with P-MOSFET + N-MOSFET. Reed switch toggles latch ON, firmware holds it via a GPIO. Firmware can cut all power for true Zero-Power shutdown.

```
                    ┌─────────┐
  VSYS ───┤ P-FET ├───> 3.3V Regulator EN
                    └────┬────┘
                         │
              POWER_HOLD GPIO ──── N-FET ──── GND
                         │
              Reed Switch ──── trigger path
```

**🔴 Decisions needed:**
> 1. Which GPIO for POWER_HOLD? Must be available immediately at boot (before I2C).
> 2. What about USB charging? If USB is plugged in with battery removed, should the regulator still turn on? (Probably yes — need a bypass Schottky from USB 5V.)
> 3. Sleep current target for the latch circuit in OFF state? (<1µA?)

---

### B.4 — BOOT + RESET Tactile Buttons

**Action:** Add two SMD tactile switches:
- **RESET:** `CHIP_PU` → GND (100nF debounce cap)
- **BOOT:** GPIO0 → GND (100nF debounce cap)

**🔴 Questions for Afonso:**
> 1. Board space available for two 3×6mm or 4×4mm switches?
> 2. Should they be accessible through the enclosure (cutouts) or internal-only for development?
> 3. Any concerns about GPIO0 being shared with `LCD_RST`?

---

## PART C — Action Items Checklist

After this meeting, we should have clear answers on:

- [ ] **RTC GPIO selection** — which pin for the reed switch in v2.9
- [ ] **Supervisor IC vs RC** — chosen approach for the hard-reset circuit
- [ ] **POWER_HOLD GPIO selection** — which pin for soft-latch control
- [ ] **PIR noise verdict** — hardware filter needed for v2.9, or firmware-only?
- [ ] **Bodge-wire feasibility** — can we add hardware reset to any of the 40 existing v2.8 boards?
- [ ] **OTA strategy** — push FSM sleep fix (FW-205) to deployed fleet now or wait?
- [ ] **Button placement** — BOOT/RESET button locations on PCB layout
- [ ] **BOM budget** — per-unit cost increase acceptable for v2.9 additions
- [ ] **Timeline** — when can v2.9 schematic rev be ready for review?

---

## Reference Documents

- [v2.9 Mitigation Plan](./v2.9_mitigation_plan.md)
- [v2.8 Hardware Analysis & Fixes](./v2.8_hardware_analysis_and_fixes.md) — covers brick recovery and the GPIO0 bodge-wire fix
- **Jira HW issues:** HW-52, HW-55, HW-56, HW-57, HW-58
- **Jira FW issues:** FW-200 → FW-207