WellNuo/docs/SENSORS_SYSTEM.md

# WellNuo Sensors System Documentation

## Overview

This document describes the architecture and user flows for managing BLE/WiFi sensors in the WellNuo app. Sensors monitor elderly people (beneficiaries) and send activity data via WiFi.

---

## Table of Contents

1. [Entities](#entities)
2. [Data Storage](#data-storage)
3. [Entity Relationships](#entity-relationships)
4. [User Flows](#user-flows)
5. [BLE Protocol](#ble-protocol)
6. [Legacy API Endpoints](#legacy-api-endpoints)
7. [UI Screens](#ui-screens)
8. [Batch Sensor Setup](#batch-sensor-setup)
9. [Error Handling](#error-handling)
10. [Open Questions](#open-questions)

---

## Entities

### User (Caregiver)
The person who uses the app to monitor beneficiaries.
- Can have multiple beneficiaries
- Stored in: **WellNuo API**

### Beneficiary
An elderly person being monitored.
- Has profile data (name, avatar, date of birth)
- Linked to exactly one Deployment
- One user can have **multiple beneficiaries** (e.g., 5)
- Stored in: **WellNuo API**

### Deployment
A "household" in Legacy API where the beneficiary lives.
- Contains address, timezone
- Contains array of devices
- One beneficiary = one deployment
- Stored in: **Legacy API**

### Device (WP Sensor)
Physical BLE/WiFi sensor installed in beneficiary's home.
- Measures activity, temperature, etc.
- Sends data via WiFi to Legacy API
- Up to **5 sensors per beneficiary**
- Stored in: **Legacy API**

---

## Data Storage

| Data | Storage | Notes |
|------|---------|-------|
| User profile | WellNuo API | Our database |
| Beneficiary profile | WellNuo API | Our database |
| Beneficiary.deploymentId | WellNuo API | Links to Legacy |
| Deployment | Legacy API | External service |
| Device | Legacy API | External service |
| Sensor readings | Legacy API | External service |

**Important:** We do NOT have access to Legacy API source code. We only use their API endpoints.

---

## Entity Relationships

```
User (WellNuo API)
 │
 ├── Beneficiary 1
 │    └── deploymentId: 22 ──► Deployment 22 (Legacy API)
 │                              ├── Device (WP_497)
 │                              ├── Device (WP_498)
 │                              ├── Device (WP_499)
 │                              ├── Device (WP_500)
 │                              └── Device (WP_501)
 │
 ├── Beneficiary 2
 │    └── deploymentId: 23 ──► Deployment 23 (Legacy API)
 │                              ├── Device (WP_510)
 │                              └── Device (WP_511)
 │
 ├── Beneficiary 3
 │    └── deploymentId: 24 ──► Deployment 24 (Legacy API)
 │                              └── (no devices yet)
 │
 └── ... up to N beneficiaries
```

### Key Points

1. Each beneficiary has their own deployment
2. Devices are attached to deployment, not directly to beneficiary
3. When adding sensors, user must first select which beneficiary
4. Sensors found via BLE scan could belong to ANY beneficiary's home

---

## User Flows

### Flow 1: View Sensors for a Beneficiary

```
1. User opens Beneficiaries list
2. User taps on a specific beneficiary (e.g., "Maria")
3. User navigates to Equipment tab
4. App fetches:
   a. GET /me/beneficiaries/{id} → get deploymentId
   b. POST Legacy API device_list_by_deployment → get devices
5. App displays sensor list with status (online/warning/offline)
```

### Flow 2: Add Sensors (Batch)

**Prerequisites:**
- User has selected a specific beneficiary
- User is physically at that beneficiary's location
- Sensors are powered on

```
1. User is on Equipment screen for "Maria"
2. User taps "Add Sensor"
3. App shows instructions
4. User taps "Scan for Sensors"
5. App performs BLE scan (10 seconds)
6. App filters devices with name starting with "WP_"
7. App shows list with checkboxes (all selected by default)
8. User can uncheck sensors they don't want to add
9. User taps "Add Selected (N)"
10. App shows WiFi selection screen
11. User selects WiFi network (from sensor's scan)
12. User enters WiFi password
13. User taps "Connect All"
14. App performs batch setup (see Batch Sensor Setup section)
15. App shows results screen
16. User taps "Done"
```

### Flow 3: Edit Sensor Location/Description

**TODO:** Not implemented yet. Needs UI.

```
1. User taps on a sensor in Equipment list
2. App shows Device Settings screen
3. User can edit:
   - location (text field, e.g., "Bedroom, near bed")
   - description (text field)
4. User taps "Save"
5. App calls Legacy API device_form to update
```

### Flow 4: Detach Sensor

```
1. User taps detach button on a sensor
2. App shows confirmation dialog
3. User confirms
4. App calls Legacy API device_form with deployment_id=0
5. Sensor is unlinked from this beneficiary
6. Sensor can now be attached to another beneficiary
```

---

## BLE Protocol

### Service UUID
```
4fafc201-1fb5-459e-8fcc-c5c9c331914b
```

### Characteristic UUID
```
beb5483e-36e1-4688-b7f5-ea07361b26a8
```

### Device Name Format
```
WP_{wellId}_{mac6chars}

Example: WP_497_81a14c
- wellId: 497
- mac last 6 chars: 81a14c
```

### Commands

| Command | Format | Description |
|---------|--------|-------------|
| PIN Unlock | `pin\|7856` | Unlock device for configuration |
| Get WiFi List | `w` | Request available WiFi networks |
| Set WiFi | `W\|SSID,PASSWORD` | Configure WiFi connection |
| Get WiFi Status | `a` | Get current WiFi connection |
| Reboot | `s` | Restart the sensor |
| Disconnect | `D` | Disconnect BLE |

### WiFi List Response Format
```
SSID1,-55;SSID2,-70;SSID3,-80
```
Where -55, -70, -80 are RSSI values in dBm.

### Timeouts
- Scan: 10 seconds
- Command response: 5 seconds

### WiFi Status Response (command `a`)

When connected via BLE, you can query current WiFi status:

**Command:** `a`

**Response format:**
```
{ssid},{rssi},{connected}

Example: Home_Network,-62,1
- ssid: "Home_Network"
- rssi: -62 dBm
- connected: 1 (true) or 0 (false)
```

**Use cases:**
- Show which WiFi network the sensor is connected to
- Display WiFi signal strength
- Diagnose connectivity issues

---

## Legacy API Endpoints

Base URL: `https://eluxnetworks.net/function/well-api/api`

Authentication: Form-encoded POST with `user_name` and `token`

### device_list_by_deployment

Get all devices for a deployment.

**Request:**
```
function=device_list_by_deployment
user_name={username}
token={token}
deployment_id={id}
first=0
last=100
```

**Response:**
```json
{
  "result_list": [
    [deviceId, wellId, mac, lastSeenTimestamp, location, description],
    [1, 497, "142B2F81A14C", 1705426800, "Bedroom", "Main sensor"],
    [2, 498, "142B2F82B25D", 1705426700, "", ""]
  ]
}
```

### device_form

Create or update a device.

**Request:**
```
function=device_form
user_name={username}
token={token}
well_id={wellId}
device_mac={mac}
location={location}
description={description}
deployment_id={deploymentId}
```

### request_devices

Get online devices (with fresh=true filter).

**Request:**
```
function=request_devices
user_name={username}
token={token}
deployment_id={id}
group_id=All
location=All
fresh=true
```

---

## UI Screens

### Equipment Screen
**Path:** `/(tabs)/beneficiaries/:id/equipment`

**Features:**
- Summary card (total/online/warning/offline counts)
- List of connected sensors
- BLE scan button for nearby sensors
- Detach sensor button

**Current limitations:**
- No editing of location/description

### Add Sensor Screen
**Path:** `/(tabs)/beneficiaries/:id/add-sensor`

**Features:**
- Instructions (4 steps)
- Scan button
- List of found devices with RSSI

**TODO:** Add checkbox selection for batch setup

### Setup WiFi Screen
**Path:** `/(tabs)/beneficiaries/:id/setup-wifi`

**Features:**
- WiFi network list (from sensor)
- Password input
- Connect button

**TODO:** Support batch setup (multiple sensors, one WiFi config)

### Device Settings Screen
**Path:** `/(tabs)/beneficiaries/:id/device-settings/:deviceId`

**Features:**
- View Well ID, MAC, Deployment ID
- Current WiFi status
- Change WiFi button
- Reboot button

**TODO:** Add location/description editing

---

## Batch Sensor Setup

### Overview

When adding multiple sensors (up to 5), the app should:
1. Allow selecting multiple sensors from BLE scan
2. Configure WiFi once for all sensors
3. Process sensors sequentially with progress UI
4. Handle errors gracefully

### Sensor States During Setup

```
pending      — waiting in queue
connecting   — BLE connection in progress
unlocking    — sending PIN command
setting_wifi — configuring WiFi
attaching    — calling Legacy API to link to deployment
rebooting    — restarting sensor
success      — completed successfully
error        — failed (with error message)
skipped      — user chose to skip after error
```

### Progress UI

```
Connecting sensors to WiFi "Home_Network"...

WP_497_81a14c
  ✓ Connected
  ✓ Unlocked
  ✓ WiFi configured
  ✓ Attached to Maria
  ● Rebooting...

WP_498_82b25d
  ✓ Connected
  ✓ Unlocked
  ● Setting WiFi...

WP_499_83c36e
  ○ Waiting...

WP_500_84d47f
  ✗ Error: Could not connect
    [Retry] [Skip]
```

### Results Screen

```
Setup Complete

Successfully connected:
  ✓ WP_497_81a14c
  ✓ WP_498_82b25d
  ✓ WP_499_83c36e

Failed:
  ✗ WP_500_84d47f — Connection timeout
    [Retry This Sensor]

[Done]
```

---

## Error Handling

### Possible Errors

| Error | Cause | User Message | Actions |
|-------|-------|--------------|---------|
| BLE Connect Failed | Sensor too far, off, or busy | "Could not connect. Move closer or check if sensor is on." | Retry, Skip |
| PIN Unlock Failed | Wrong PIN (unlikely) | "Could not unlock sensor." | Retry, Skip |
| WiFi Set Failed | Command timeout | "Could not configure WiFi." | Retry, Skip |
| API Attach Failed | No internet, server down | "Could not register sensor. Check internet." | Retry, Skip |
| Timeout | Sensor not responding | "Sensor not responding." | Retry, Skip |

### Error Recovery Options

When an error occurs on sensor N:

1. **Pause** the batch process
2. **Show** error with options:
   - `[Retry]` — try this sensor again
   - `[Skip]` — move to next sensor
   - `[Cancel All]` — abort entire process
3. **Continue** based on user choice

### All Sensors Failed

```
Setup Failed

Could not connect any sensors.

Possible reasons:
• Sensors are too far away
• Sensors are not powered on
• Bluetooth is disabled

[Try Again] [Cancel]
```

### Logging

For debugging, log all operations:

```
[BLE] Starting batch setup for 5 sensors
[BLE] [1/5] WP_497 — connecting...
[BLE] [1/5] WP_497 — connected (took 1.2s)
[BLE] [1/5] WP_497 — sending PIN...
[BLE] [1/5] WP_497 — unlocked
[BLE] [1/5] WP_497 — setting WiFi "Home"...
[BLE] [1/5] WP_497 — WiFi configured
[API] [1/5] WP_497 — attaching to deployment 22...
[API] [1/5] WP_497 — attached (device_id: 1)
[BLE] [1/5] WP_497 — rebooting...
[BLE] [1/5] WP_497 — SUCCESS (total: 8.5s)

[BLE] [2/5] WP_498 — connecting...
[BLE] [2/5] WP_498 — ERROR: connection timeout after 5s
```

---

## Sensor Activity & Status

### Status Calculation

Sensor status is calculated based on `lastSeen` timestamp from Legacy API:

| Time since last signal | Status | Color | Meaning |
|------------------------|--------|-------|---------|
| < 5 minutes | online | Green | Sensor is working normally |
| 5-60 minutes | warning | Yellow | Possible issue, check sensor |
| > 60 minutes | offline | Red | Sensor is not sending data |

### Activity Display in UI

**Equipment Screen shows for each sensor:**
- Sensor name (WP_497_81a14c)
- Status badge (Online/Warning/Offline)
- Last activity time ("5 min ago", "2 hours ago")
- Location label (if set)

### Detailed WiFi Status (via BLE)

When user opens Device Settings for an ONLINE sensor, app can:

1. Connect to sensor via BLE
2. Send command `a` (Get WiFi Status)
3. Display:
   - WiFi network name
   - Signal strength (RSSI in dBm or as Excellent/Good/Fair/Weak)
   - Connection status

**WiFi Signal Strength Interpretation:**

| RSSI | Quality |
|------|---------|
| -50 or better | Excellent |
| -50 to -60 | Good |
| -60 to -70 | Fair |
| -70 or worse | Weak |

This helps diagnose connectivity issues — if sensor goes offline, user can check if WiFi signal is weak.

---

## Open Questions

### Q1: Multiple Beneficiaries Context

**Question:** User has 5 beneficiaries. When scanning BLE, sensors from different locations might appear. How to handle?

**Decision:** Trust the user. They select beneficiary first, then add sensors. If they make a mistake, they can detach and reattach to correct beneficiary. No confirmation needed.

### Q2: WiFi Configuration Timing

**Question:** When should user set sensor location label?

**Options:**
- A) During initial setup (add step after WiFi)
- B) Later, in Device Settings screen
- C) Both (optional during setup, editable later)

### Q3: Background Processing

**Question:** If user closes app during batch setup, what happens?

**Options:**
- A) Continue in background (complex)
- B) Cancel everything (simple, but frustrating)
- C) Pause and resume when app reopens

### Q4: Sensor Already Attached

**Question:** What if scanned sensor is already attached to ANOTHER beneficiary (different deployment)?

**Options:**
- A) Show error: "This sensor is already in use"
- B) Offer to move it: "Move to Maria's home?"
- C) Just attach it (will detach from previous)

---

## File References

| File | Description |
|------|-------------|
| `services/ble/BLEManager.ts` | BLE operations |
| `services/ble/types.ts` | BLE types |
| `services/ble/MockBLEManager.ts` | Mock for simulator |
| `contexts/BLEContext.tsx` | BLE React context |
| `services/api.ts` | API methods |
| `types/index.ts` | WPSensor type (lines 47-59) |
| `app/(tabs)/beneficiaries/[id]/equipment.tsx` | Equipment screen |
| `app/(tabs)/beneficiaries/[id]/add-sensor.tsx` | Add sensor screen |
| `app/(tabs)/beneficiaries/[id]/setup-wifi.tsx` | WiFi setup screen |
| `app/(tabs)/beneficiaries/[id]/device-settings/[deviceId].tsx` | Device settings |

---

## Revision History

| Date | Author | Changes |
|------|--------|---------|
| 2026-01-19 | Claude | Initial documentation |