893778143a
- Add root README.md and AGENTS.md for hardware repo - Fix cross-repo and internal broken links - Document hardware/common/scripts - Populate v2.9 placeholder READMEs - Update replica-omnisciente central brain pointer
172 lines
7.9 KiB
Markdown
172 lines
7.9 KiB
Markdown
# 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
|