# BLE Packet Sniffing Guide — KAIYU Controller

The goal is to capture the raw BLE packets the KAIYU iOS app sends,
so we can reverse-engineer the exact command format.

---

## Method 1: iPhone BLE Packet Logging (Best for iOS app)

iOS has a built-in BLE sniffer via **Developer Mode**.

### Steps

1. **Enable Developer Mode** on your iPhone:
   Settings → Privacy & Security → Developer Mode → On

2. **Install Apple's Bluetooth logging profile:**
   On your iPhone, open Safari and go to:
   https://developer.apple.com/bug-reporting/profiles-and-logs/
   Download and install the **Bluetooth** profile.
   (Settings → General → VPN & Device Management → install)

3. **Reproduce the actions:**
   - Open the KAIYU app
   - Connect to your LED controller
   - Change colours, effects, brightness — note what you tap

4. **Export the log:**
   - Settings → Privacy & Security → Analytics & Improvements → Analytics Data
   - Find a file starting with `bluetooth-` — share/AirDrop it to your PC

5. **Analyse with Wireshark:**
   - Open the `.btsnoop` or `.pklg` file in Wireshark
   - Filter: `btatt` (Bluetooth ATT layer)
   - Look for **Write Request** / **Write Command** packets
   - The payload is your LED command!

---

## Method 2: Android HCI Snoop (Easier, needs an Android device)

If you have an Android phone handy, this is simpler.

1. Enable **Developer Options** (tap Build Number 7 times)
2. Enable **Bluetooth HCI Snoop Log**
3. Open the KAIYU app, connect, and operate the controller
4. Pull the log:
   ```
   adb pull /sdcard/btsnoop_hci.log
   ```
5. Open in Wireshark, filter `btatt`

---

## Method 3: nRF Sniffer (Hardware — most reliable)

Use a Nordic Semiconductor nRF52840 dongle + Wireshark plugin to sniff live.
See: https://www.nordicsemi.com/Products/Development-tools/nrf-sniffer-for-bluetooth-le

---

## Method 4: nRF Connect App (Quick test, no capture needed)

Install **nRF Connect** (iOS or Android) from Nordic Semiconductor.

1. Scan → connect to your LED controller
2. Browse services and characteristics
3. Find writable characteristics (look for Write or Write Without Response)
4. Manually write hex values to test — watch the lights!

Common values to try on the writable characteristic:
```
7e000400000000ffef  → Turn ON
7e000400000000 00ef → Turn OFF
7e000503ff000000ef  → Red
7e00050300ff0000ef  → Green
7e0005030000ff00ef  → Blue
7e000503ffffffff ef → White
```

---

## What to record

Once you have a capture, note:

| Field | Value |
|-------|-------|
| Device name | (what it advertises as) |
| Service UUID | (the parent service) |
| Write characteristic UUID | (where commands go) |
| Power ON command (hex) | |
| Power OFF command (hex) | |
| Red command (hex) | |
| Green command (hex) | |
| Blue command (hex) | |
| Brightness command (hex) | |

Add the UUIDs and confirmed command format to `controller/config.py` and `controller/protocol.py`.