WellNuo/PRD-SENSORS.md

PRD: Sensors Management System

Context

WellNuo app for elderly care. BLE/WiFi sensors monitor beneficiaries (elderly people) at home. Each user can have multiple beneficiaries. Each beneficiary has one deployment (household) with up to 5 sensors.

Architecture:

• User → Beneficiary (WellNuo API) → deploymentId → Deployment (Legacy API) → Devices
• BLE for sensor setup, WiFi for data transmission
• Legacy API at https://eluxnetworks.net/function/well-api/api (external, read-only code access)

Documentation: docs/SENSORS_SYSTEM.md Feature Spec: specs/wellnuo/FEATURE-SENSORS-SYSTEM.md

---

Tasks

Phase 1: API Layer

• TASK-1.1: Add updateDeviceMetadata method to api.ts

  File: services/api.ts

  Add method to update device location and description via Legacy API.

  async updateDeviceMetadata(
    wellId: number,
    mac: string,
    deploymentId: number,
    location: string,
    description: string
  ): Promise<boolean>
  

  Implementation:

  1. Get Legacy API credentials via getLegacyCredentials()
  2. Build form data with: function=device_form, user_name, token, well_id, device_mac, location, description, deployment_id
  3. POST to https://eluxnetworks.net/function/well-api/api
  4. Return true on success, false on error

  Reference: docs/SENSORS_SYSTEM.md lines 266-280 for API format.

---

Phase 2: Device Settings UI

• TASK-2.1: Add location/description editing to Device Settings screen

  File: app/(tabs)/beneficiaries/[id]/device-settings/[deviceId].tsx

  Add editable fields for sensor location and description:

  1. Add state variables: location, description, isSaving
  2. Add two TextInput fields below device info section
  3. Add "Save" button that calls api.updateDeviceMetadata()
  4. Show loading indicator during save
  5. Show success/error toast after save
  6. Pre-fill fields with current values from device data

  UI requirements:

  • TextInput for location (placeholder: "e.g., Bedroom, near bed")
  • TextInput for description (placeholder: "e.g., Main activity sensor")
  • Button: "Save Changes" (disabled when no changes or saving)
  • Toast: "Settings saved" on success

---

Phase 3: Equipment Screen Improvements

• TASK-3.1: Show placeholder for empty location in Equipment screen

  File: app/(tabs)/beneficiaries/[id]/equipment.tsx

  Find the sensor list rendering (around line 454) and update:

  Before:

  {sensor.location && (
    <Text style={styles.deviceLocation}>{sensor.location}</Text>
  )}
  

  After:

  <Text style={[styles.deviceLocation, !sensor.location && styles.deviceLocationEmpty]}>
    {sensor.location || 'Tap to set location'}
  </Text>
  

  Add style deviceLocationEmpty with opacity: 0.5, fontStyle: 'italic'

• TASK-3.2: Add quick navigation to Device Settings from Equipment screen

  File: app/(tabs)/beneficiaries/[id]/equipment.tsx

  Make the location text tappable to navigate to Device Settings:

  1. Wrap location Text in TouchableOpacity
  2. onPress: navigate to /beneficiaries/${id}/device-settings/${device.id}
  3. Import useRouter from expo-router if not already imported

---

Phase 4: Batch Sensor Setup - Selection UI

• TASK-4.1: Add checkbox selection to Add Sensor screen

  File: app/(tabs)/beneficiaries/[id]/add-sensor.tsx

  After BLE scan, show checkboxes for selecting multiple sensors:

  1. Add state: selectedDevices: Set<string> (device IDs)
  2. After scan, select ALL devices by default
  3. Render each device with checkbox (use Checkbox from react-native or custom)
  4. Add "Select All" / "Deselect All" toggle at top
  5. Show count: "3 of 5 selected"
  6. Change button from "Connect" to "Setup Selected (N)"
  7. Pass selected devices to Setup WiFi screen via route params

  UI layout:

  [ ] Select All
  
  [x] WP_497_81a14c  -55 dBm  ✓
  [x] WP_498_82b25d  -62 dBm  ✓
  [ ] WP_499_83c36e  -78 dBm
  
  [Setup Selected (2)]
  

• TASK-4.2: Update navigation to pass selected devices

  File: app/(tabs)/beneficiaries/[id]/add-sensor.tsx

  When navigating to setup-wifi screen, pass selected devices:

  router.push({
    pathname: `/(tabs)/beneficiaries/${id}/setup-wifi`,
    params: {
      devices: JSON.stringify(selectedDevicesArray),
      beneficiaryId: id
    }
  });
  

---

Phase 5: Batch Sensor Setup - WiFi Configuration

• TASK-5.1: Refactor Setup WiFi screen for batch processing

  File: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx

  Update to handle multiple devices:

  1. Parse devices from route params (JSON array of WPDevice objects)
  2. Get WiFi list from FIRST device only (all sensors at same location = same WiFi)
  3. After user enters password, process ALL devices sequentially
  4. Add state for batch progress tracking

  New state:

  interface DeviceSetupState {
    deviceId: string;
    deviceName: string;
    status: 'pending' | 'connecting' | 'unlocking' | 'setting_wifi' | 'attaching' | 'rebooting' | 'success' | 'error';
    error?: string;
  }
  const [setupStates, setSetupStates] = useState<DeviceSetupState[]>([]);
  

• TASK-5.2: Implement batch setup processing logic

  File: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx

  Create processBatchSetup function:

  async function processBatchSetup(ssid: string, password: string) {
    for (const device of devices) {
      updateStatus(device.id, 'connecting');
  
      // 1. Connect BLE
      const connected = await bleManager.connectDevice(device.id);
      if (!connected) {
        updateStatus(device.id, 'error', 'Could not connect');
        continue; // Skip to next device
      }
  
      // 2. Unlock with PIN
      updateStatus(device.id, 'unlocking');
      await bleManager.sendCommand(device.id, 'pin|7856');
  
      // 3. Set WiFi
      updateStatus(device.id, 'setting_wifi');
      await bleManager.setWiFi(device.id, ssid, password);
  
      // 4. Attach to deployment via Legacy API
      updateStatus(device.id, 'attaching');
      await api.attachDeviceToDeployment(device.wellId, device.mac, deploymentId);
  
      // 5. Reboot
      updateStatus(device.id, 'rebooting');
      await bleManager.rebootDevice(device.id);
  
      updateStatus(device.id, 'success');
    }
  }
  

• TASK-5.3: Add progress UI for batch setup

  File: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx

  Show progress for each device:

  Connecting to "Home_Network"...
  
  WP_497_81a14c
    ✓ Connected
    ✓ Unlocked
    ✓ WiFi configured
    ● Attaching to Maria...
  
  WP_498_82b25d
    ✓ Connected
    ○ Waiting...
  
  WP_499_83c36e
    ○ Pending
  

  Use icons: ✓ (success), ● (in progress), ○ (pending), ✗ (error)

---

Phase 6: Error Handling

• TASK-6.1: Add error handling UI with retry/skip options

  File: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx

  When a device fails:

  1. Pause batch processing
  2. Show error message with device name
  3. Show three buttons: [Retry] [Skip] [Cancel All]
  4. On Retry: try this device again
  5. On Skip: mark as skipped, continue to next device
  6. On Cancel All: abort entire process, show results

  {currentError && (
    <View style={styles.errorContainer}>
      <Text style={styles.errorTitle}>
        Failed: {currentError.deviceName}
      </Text>
      <Text style={styles.errorMessage}>
        {currentError.message}
      </Text>
      <View style={styles.errorButtons}>
        <Button title="Retry" onPress={handleRetry} />
        <Button title="Skip" onPress={handleSkip} />
        <Button title="Cancel All" onPress={handleCancelAll} />
      </View>
    </View>
  )}
  

• TASK-6.2: Add results screen after batch setup

  File: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx

  After all devices processed, show summary:

  Setup Complete
  
  Successfully connected:
    ✓ WP_497_81a14c
    ✓ WP_498_82b25d
  
  Failed:
    ✗ WP_499_83c36e - Connection timeout
      [Retry This Sensor]
  
  Skipped:
    ⊘ WP_500_84d47f
  
  [Done]
  

  "Done" button navigates back to Equipment screen.

---

Phase 7: API Method for Device Attachment

• TASK-7.1: Add attachDeviceToDeployment method to api.ts

  File: services/api.ts

  Add method to register a new device with Legacy API:

  async attachDeviceToDeployment(
    wellId: number,
    mac: string,
    deploymentId: number,
    location?: string,
    description?: string
  ): Promise<{ success: boolean; deviceId?: number; error?: string }>
  

  Implementation:

  1. Call Legacy API device_form with deployment_id set
  2. Return device ID from response on success
  3. Return error message on failure

  This is used during batch setup to link each sensor to the beneficiary's deployment.

---

Verification Checklist

After all tasks complete, verify:

• Can view sensors list for any beneficiary
• Can scan and find WP_* sensors via BLE
• Can select multiple sensors with checkboxes
• Can configure WiFi for all selected sensors
• Progress UI shows status for each device
• Errors show retry/skip options
• Results screen shows success/failure summary
• Can edit sensor location in Device Settings
• Location placeholder shows in Equipment screen
• Can tap location to go to Device Settings
• Mock BLE works in iOS Simulator

---

Notes for AI Agent

1. Read documentation first: docs/SENSORS_SYSTEM.md has full context
2. Check existing code: Files may already have partial implementations
3. BLE Manager: Use services/ble/BLEManager.ts for real device, MockBLEManager.ts for simulator
4. Legacy API auth: Use getLegacyCredentials() method in api.ts
5. Error handling: Always wrap BLE operations in try/catch
6. TypeScript: Project uses strict TypeScript, ensure proper types
7. Testing: Use iOS Simulator with Mock BLE for testing