# BLE Communication Protocol Specification

This document defines the Bluetooth Low Energy (BLE) communication protocol between the client application and the device.

---

## 1. BLE Connection Parameters

To establish a connection and communicate with the device, the following BLE parameters must be configured:

- **Service UUID**: `12345678-1234-1234-1234-1234567890ab`
- **Characteristic UUID**: `abcd1234-ab12-cd34-ef56-abcdef123456`
  _Note: The same characteristic is used for both read (polling status) and write (sending commands) operations._

### Device Discovery (Scanning)

### Connection Setup (CRITICAL)

1. **Request MTU Size**: Immediately after establishing a connection, the client application **must** request an MTU size of **`517` bytes**.
   - _Why:_ The JSON payloads exchanged can exceed the default 20-byte BLE MTU limit. Setting it to 517 ensures the payloads fit in a single packet.
2. **Discover Services**: Perform service and characteristic discovery (`discoverAllServicesAndCharacteristics()`) before initiating reads/writes.

---

## 2. Data Encoding & Transport

All messages written to or read from the characteristic must use **Base64 encoding**.

- **Write Operations (App ➡️ Device)**:
  1. Construct the JSON payload.
  2. Convert the JSON string to a UTF-8 byte stream.
  3. Encode the byte stream to a Base64 string.
  4. Write the Base64 string to the characteristic using **Write with Response**.
- **Read Operations (Device ➡️ App)**:
  1. Read the Base64 value from the characteristic.
  2. Decode the Base64 string back to UTF-8 text.
  3. Parse the decoded text as a JSON object.

---

## 3. Outbound Commands (Client to Device)

Commands are structured as JSON objects containing a `"name"` identifier and a `"data"` payload.

### 3.1. Wi-Fi Configuration (`wifi`)

Configures the Wi-Fi credentials so the device can connect to a local network.

- **Command Name**: `wifi`
- **Payload Format**:
  ```json
  {
    "name": "wifi",
    "data": {
      "ssid": "<SSID>",
      "password": "<PASSWORD>"
    }
  }
  ```
- **Example**:
  ```json
  {
    "name": "wifi",
    "data": {
      "ssid": "MyHomeNetwork",
      "password": "SecretPassword123"
    }
  }
  ```

## 4. Inbound Telemetry (Device to Client)

The device maintains its state and exposes it on the same characteristic. The client application should poll this characteristic at a periodic interval (e.g., every **1000ms**).

### Telemetry JSON Schema

```json
{
  "status": "<wifi_status>",
  "ssid": "<connected_ssid>",
  "ip": "<ip_address>",
  "battery_percent": <battery_percent>,
  "charging_status": "<charging_status>",
  "LittleFS_image_count": <image_count>,
  "Device_Size": "<device_size>",
  "slideshow_status": "<slideshow_status>",
  "enabled_images": "<enabled_images>"
}
```

### Parameter Explanations

| Field                  | Type     | Description                                                                                    |
| :--------------------- | :------- | :--------------------------------------------------------------------------------------------- |
| `status`               | `string` | Wi-Fi connection status. `"1"` represents connected; other values represent disconnected.      |
| `ssid`                 | `string` | The SSID of the Wi-Fi network the device is currently connected to (empty if disconnected).    |
| `ip`                   | `string` | The IP address assigned to the device (empty if disconnected).                                 |
| `battery_percent`      | `number` | Remaining battery percentage (integer between `0` and `100`).                                  |
| `charging_status`      | `string` | Charging indicator. `"1"` if plugged in/charging; `"0"` if on battery power.                   |
| `LittleFS_image_count` | `number` | Total count of image resources available in the device filesystem.                             |
| `Device_Size`          | `string` | Hardware screen dimension indicator (e.g. `"13.3"`).                                           |
| `slideshow_status`     | `string` | Slideshow mode indicator. `"1"` represents running/enabled; `"0"` represents stopped/disabled. |
| `enabled_images`       | `string` | List/metadata string of selected images enabled on the device.                                 |

### Example Telemetry Payload

```json
{
  "status": "1",
  "ssid": "Office_WiFi_5G",
  "ip": "192.168.1.144",
  "battery_percent": 98,
  "charging_status": "1",
  "LittleFS_image_count": 8,
  "Device_Size": "13.3",
  "slideshow_status": "1",
  "enabled_images": "A1,A3,A5"
}
```

---

## 5. Typical Flow Checklist

1. **Scan** .
2. **Connect** to the selected device.
3. **Request MTU to 517**.
4. **Discover** services and characteristics.
5. **Start polling** telemetry by reading the characteristic every 1 second.
6. Decode and parse telemetry JSON to update UI states.
7. **Write** commands (Base64 encoded JSON) as user performs actions (e.g., configures Wi-Fi or adjusts slideshow settings).
8. Handle disconnection event gracefully by resetting polling intervals and application states.