From 8622f4cde93c6e2cb8dd040748b5e86244245a07 Mon Sep 17 00:00:00 2001
From: jessikitty <jess.rogerson.29@outlook.com>
Date: Wed, 1 Jul 2026 19:55:59 +1000
Subject: [PATCH] Add BLE sniffing guide

---
 sniffer/README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 sniffer/README.md

diff --git a/sniffer/README.md b/sniffer/README.md
new file mode 100644
index 0000000..b2d900c
--- /dev/null
+++ b/sniffer/README.md
@@ -0,0 +1,99 @@
+# 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`.