probe/PARENT_LOSS_IMPLEMENTATION.md

Parent Loss Handling Implementation - PROBE-TN-002

Status: COMPLETE Date: 2025-12-09 Platform: Probe (nRF52840) File: /root/cleargrow/probe/src/thread_node.c

Summary

Implemented comprehensive Thread parent loss detection and recovery for the ClearGrow wireless sensor probe. The probe now gracefully handles loss of connection to the Thread border router with automatic reconnection using exponential backoff.

Features Implemented

1. Parent Loss Detection

• Trigger: OpenThread state change callback detects transition from CHILD/ROUTER to DETACHED
• Location: ot_state_changed() callback (lines 195-246)
• Action: Immediately calls parent_loss_handler() to begin reconnection

2. Reconnection State Machine

• Initial Retry Delay: 2 seconds
• Max Retry Delay: 2 minutes (exponential backoff with cap)
• Max Attempts: 10 attempts before entering low-power mode
• Backoff Algorithm: Doubles delay each attempt up to max

3. Data Buffering During Disconnection

• Queue Mechanism: When parent is lost, sensor data is queued instead of dropped
• Location: thread_node_send_sensors() (lines 1032-1049)
• Behavior: Single-sample buffer (overwrites on new data)
• Auto-Send: Buffered data automatically transmitted when connection restored

4. Low-Power Mode

• Trigger: After 10 failed reconnection attempts
• Retry Interval: 5 minutes (300 seconds)
• Behavior: Resets attempt counter and tries again with fresh backoff schedule
• Power Savings: Reduces wake frequency to conserve battery

5. Automatic Recovery

• Connection Detection: State callback monitors for successful reattachment
• State Reset: Clears parent loss flags, resets retry counter
• Buffered Data: Automatically sends any queued sensor readings
• Location: Lines 220-257 in ot_state_changed()

Code Structure

Constants (Lines 49-53)

#define PARENT_LOSS_RETRY_INITIAL_MS    2000      // 2 seconds
#define PARENT_LOSS_RETRY_MAX_MS        120000    // 2 minutes
#define PARENT_LOSS_MAX_ATTEMPTS        10        // Max attempts
#define PARENT_LOSS_LOWPOWER_RETRY_MS   300000    // 5 minutes

State Tracking (Lines 104-117)

static struct {
    uint32_t retry_delay_ms;
    uint32_t retry_count;
    bool parent_lost;
    bool in_lowpower_mode;
    int64_t last_connected_ms;
} s_parent_loss_state;

Core Functions

1. parent_loss_handler() (lines 788-827)

   • Manages retry attempts
   • Implements exponential backoff
   • Triggers low-power mode after max attempts

2. parent_loss_retry_work_handler() (lines 835-883)

   • Work queue handler for delayed retries
   • Checks if already reconnected
   • Enables Thread stack and waits for auto-reattachment

3. ot_state_changed() (lines 192-246)

   • Detects parent loss
   • Detects successful reconnection
   • Sends buffered data on recovery

API Extensions

Added diagnostic functions for monitoring parent loss state:

bool thread_node_is_parent_lost(void);              // Check if currently disconnected
uint32_t thread_node_get_reconnect_attempts(void);  // Get attempt count
bool thread_node_is_in_lowpower_mode(void);         // Check if in low-power retry mode
int64_t thread_node_get_time_since_connected(void); // Time since last connection

Location: Lines 1161-1202 in thread_node.c Declarations: Lines 80-83 in main.c

Behavior Flow

1. Parent Loss Detected

   • OpenThread reports role change to DETACHED
   • parent_loss_handler() called
   • First retry scheduled for 2 seconds

2. Reconnection Attempts (1-10)

   • Wake up, enable Thread stack
   • Wait for automatic parent discovery
   • Backoff delay: 2s → 4s → 8s → 16s → 32s → 64s → 120s (cap)
   • If still detached, schedule next retry

3. Low-Power Mode (after 10 attempts)

   • Stop aggressive retries
   • Wait 5 minutes between attempts
   • Reset counter to give fresh attempts
   • Continue indefinitely

4. Successful Reconnection

   • State changes to CHILD or ROUTER
   • Reset all parent loss state
   • Send buffered sensor data
   • Resume normal operation

Acceptance Criteria

• Parent loss detected via OpenThread state callback
• Reconnection attempted with exponential backoff
• Max retry limit enforced (10 attempts)
• Device enters low-power mode when giving up
• Periodic retry in low-power mode (5 minutes)
• Normal operation resumes when attached
• Sensor data buffered during disconnection
• Buffered data sent on reconnection

Testing Recommendations

1. Simulate Parent Loss

   • Disable Thread border router
   • Verify probe detects disconnection
   • Monitor retry attempts and backoff timing

2. Verify Reconnection

   • Re-enable border router after 5-6 retries
   • Confirm probe reattaches
   • Verify buffered data is transmitted

3. Test Low-Power Mode

   • Leave border router disabled for >10 attempts
   • Confirm probe enters low-power retry mode
   • Verify 5-minute retry interval

4. Power Consumption

   • Measure current draw during:
     • Normal operation
     • Active reconnection attempts
     • Low-power retry mode

Memory Impact

Flash: +2,024 bytes (parent loss state machine code) RAM: +24 bytes (parent loss state structure)

Build successful: 68.10% flash, 46.26% RAM

Related Tasks

• PROBE-DP-001: Data buffering during disconnection (basic implementation complete, could be enhanced with multi-sample buffer)
• PROBE-SL-002: Stuck-awake detection (stub functions added for compilation)

Log Examples

[INF] Thread state: Detached
[WRN] Parent lost! Starting reconnection procedure
[INF] Attempting reconnection (attempt 1/10) in 2000 ms
[DBG] Thread enabled, waiting for automatic parent discovery
[INF] Attempting reconnection (attempt 2/10) in 4000 ms
...
[WRN] Max reconnection attempts (10) reached, entering low-power mode
[INF] Low-power retry: resetting attempt counter
...
[INF] Thread state: Child
[INF] Parent reconnected successfully (attempt 7)
[INF] Reconnected - attempting to send buffered sensor data
[INF] Buffered data sent successfully (seq 42)

Files Modified

1. /root/cleargrow/probe/src/thread_node.c - Main implementation
2. /root/cleargrow/probe/src/main.c - API declarations
3. /root/cleargrow/probe/src/power_manager.c - Stub functions (for compilation)