probe/REMEDIATION_PROBE-SL-003.md

REMEDIATION: PROBE-SL-003 - Wake Sources Not Configured

Status: COMPLETED Priority: HIGH Platform: nRF52840 Probe Date: 2025-12-09

Problem

Wake sources (RTC timer, GPIO interrupts) were not explicitly configured, relying on defaults. This could cause unexpected wake events or missed wakes from System OFF mode.

Solution Implemented

1. Wake Source Configuration (power_manager.c)

Added explicit GPIO SENSE configuration for button wake from System OFF:

File: /root/cleargrow/probe/src/power_manager.c

New Functions:

• configure_wake_sources() - Configures GPIO 0.11 (button0) with SENSE_LOW for button press wake
• detect_wake_reason() - Reads RESETREAS register to determine wake cause, logs reason
• disable_unwanted_wake_sources() - Documents NFC wake (left enabled) and LPCOMP (disabled by default)

Wake Sources Configured:

1. Button0 (GPIO 0.11) - Primary wake source, press to wake from System OFF
2. NFC field detect - Enabled for service/maintenance mode
3. Power cycle - Always enabled (hardware)
4. RTC - NOT available on nRF52840 for System OFF wake (requires external RTC chip)

2. Integration Points

power_manager_init():

• Calls detect_wake_reason() on boot to log why device started
• Calls configure_wake_sources() to set up button wake
• Calls disable_unwanted_wake_sources() for documentation

enter_shipping_mode():

• Calls configure_wake_sources() immediately before nrf_power_system_off()
• Ensures wake sources are properly configured even if modified during runtime

3. Wake Reason Detection

The detect_wake_reason() function checks RESETREAS register bits:

Bit	Reason	Log Level
OFF + GPIO	Button wake from System OFF	INFO
OFF + NFC	NFC field wake	INFO
DOG	Watchdog reset	WARNING
RESETPIN	External reset pin	INFO
SREQ	Software reset	INFO
LOCKUP	CPU lockup (fault)	ERROR
(none)	Power-on reset	INFO

Important: RESETREAS register is explicitly cleared after reading (required by nRF52840 hardware).

4. Platform Limitations Documented

nRF52840 System OFF Wake Sources:

• ✓ GPIO with SENSE enabled (button press)
• ✓ NFC field detect (if NFC enabled)
• ✓ Power reset/power cycle (cannot be disabled)
• ✗ RTC/Timer (requires external RTC with GPIO interrupt)
• ✗ LPCOMP (not used in this design)

Why RTC can't wake from System OFF: The nRF52840's internal RTC cannot generate interrupts in System OFF mode. Only GPIO SENSE pins, NFC, and power cycle can wake the device. For periodic wake, either:

1. Use external RTC chip with interrupt pin connected to GPIO SENSE, OR
2. Use Thread SED mode with normal sleep instead of System OFF

5. Changes Made

Modified Files:

• /root/cleargrow/probe/src/power_manager.c - Added wake source configuration
  • Added #include <hal/nrf_gpio.h> for GPIO SENSE APIs
  • Added wake_reason_t enum
  • Added 3 new static functions (118 lines total)
  • Modified power_manager_init() to detect wake reason and configure sources
  • Modified enter_shipping_mode() to configure sources before System OFF

Build Status:

• ✓ Compiles successfully
• ✓ No errors in power_manager.c
• ⚠ Unrelated thread_node.c errors exist (separate issue)

Verification

Manual Testing Steps

1. Power-on wake:

   Power cycle device
   Expected log: "Wake reason: POWER_ON"
   

2. Button wake from System OFF:

   Enter SHIPPING mode: power_manager_set_state(POWER_STATE_SHIPPING)
   Press button0 (GPIO 0.11)
   Expected log: "Wake reason: Button press"
   

3. NFC wake from System OFF (if NFC enabled):

   Enter SHIPPING mode
   Present NFC reader
   Expected log: "Wake reason: NFC field"
   

4. Watchdog reset:

   Stop feeding watchdog
   Expected log: "Wake reason: WATCHDOG reset"
   

Expected Log Output

On boot:

[power_mgr] Wake reason: POWER_ON
[power_mgr] Wake source configured: Button (GPIO 0.11)
[power_mgr] Wake sources: Button and NFC enabled
[power_mgr] Battery ADC configured
[power_mgr] Power manager initialized (battery: 3700mV)

Before System OFF:

[power_mgr] Entering SHIPPING mode (ultra-low power)
[power_mgr] Device will power down - wake via button or power cycle
[power_mgr] Wake source configured: Button (GPIO 0.11)
[power_mgr] Wake sources: Button and NFC enabled

Acceptance Criteria

• GPIO wake configured for button
• Wake reason detected and logged after each wake
• Unwanted wake sources documented/disabled
• No spurious wakes (prevented by explicit SENSE_LOW on single pin)
• RTC wake limitation documented (not available on nRF52840 for System OFF)
• Code compiles without errors
• Wake source configuration called before System OFF

Notes

Design Decisions

1. NFC wake left enabled: Useful for service/maintenance mode - technician can wake device with NFC tap
2. Single button wake: Only button0 configured to prevent spurious wakes from other pins
3. SENSE_LOW chosen: Matches button circuit (active-low, pull-up when not pressed)
4. No RTC periodic wake: Would require external RTC chip; Thread SED mode used instead for normal operation

Future Improvements

1. Make wake button configurable via Kconfig
2. Add option to disable NFC wake if not needed
3. Consider external RTC for true periodic wake from System OFF
4. Add wake event counters for debugging

References

• Nordic nRF52840 Product Specification v1.8, Section 5.3.4 (System OFF mode)
• Zephyr GPIO API Documentation
• PROBE-SL-002 - Related task on power management strategy