reverse-engineering.md (8380B)
1 # Reverse Engineering Guide 2 3 This guide is for contributors who want to add support for in-lite devices 4 they don't physically own. By capturing traffic from someone who _does_ have 5 the hardware (or from your own setup with a different device), you can 6 understand the cloud API and BLE mesh commands without needing every product 7 on your desk. 8 9 --- 10 11 ## Prerequisites 12 13 | Tool | Purpose | Install | 14 |------|---------|---------| 15 | [mitmproxy](https://mitmproxy.org/) | HTTP/S traffic interception | `brew install mitmproxy` or `pip install mitmproxy` | 16 | [Xcode](https://developer.apple.com/xcode/) | Includes PacketLogger | Mac App Store | 17 | Apple Bluetooth logging profile | Enables BLE capture from iOS | [Apple Bug Reporting → Profiles](https://developer.apple.com/bug-reporting/profiles-and-logs/?name=bluetooth) | 18 19 --- 20 21 ## Part 1: HTTP Traffic Capture (mitmproxy) 22 23 Use mitmproxy to intercept the in-lite app's cloud API calls. This reveals 24 endpoint URLs, request/response payloads, authentication flows, and device 25 metadata. 26 27 ### 1.1 Install mitmproxy 28 29 ```bash 30 # macOS (Homebrew) 31 brew install mitmproxy 32 33 # Or via pip 34 pip install mitmproxy 35 ``` 36 37 ### 1.2 Start the proxy 38 39 ```bash 40 mitmproxy --listen-port 8080 41 ``` 42 43 This starts an interactive terminal UI. Alternatively, use `mitmweb` for a 44 browser-based interface: 45 46 ```bash 47 mitmweb --listen-port 8080 48 ``` 49 50 ### 1.3 Find your Mac's local IP 51 52 ```bash 53 ipconfig getifaddr en0 54 ``` 55 56 Note the IP (e.g., `192.168.1.42`). Your phone will use this as its proxy. 57 58 ### 1.4 Configure your phone to use the proxy 59 60 #### iOS 61 62 1. Open **Settings → Wi-Fi** → tap the ⓘ next to your network 63 2. Scroll to **HTTP Proxy** → select **Manual** 64 3. Set: 65 - **Server:** your Mac's IP (e.g., `192.168.1.42`) 66 - **Port:** `8080` 67 - **Authentication:** off 68 69 #### Android 70 71 1. Open **Settings → Network & Internet → Wi-Fi** 72 2. Long-press your network → **Modify network** → **Advanced options** 73 3. Set **Proxy** to **Manual** 74 4. Enter your Mac's IP and port `8080` 75 76 ### 1.5 Install the mitmproxy CA certificate 77 78 With the proxy configured, open a browser on your phone and navigate to: 79 80 ``` 81 http://mitm.it 82 ``` 83 84 This page provides platform-specific certificate downloads. 85 86 #### iOS 87 88 1. Tap the Apple icon to download the profile 89 2. Go to **Settings → General → VPN & Device Management** → install the 90 downloaded profile 91 3. Go to **Settings → General → About → Certificate Trust Settings** → 92 enable full trust for the mitmproxy certificate 93 94 #### Android 95 96 1. Tap the Android icon to download the certificate 97 2. Go to **Settings → Security → Install a certificate → CA certificate** 98 3. Select the downloaded file 99 100 > [!NOTE] 101 > On Android 7+, user-installed CA certificates are not trusted by apps by 102 > default. You may need a rooted device or a repackaged app with 103 > `networkSecurityConfig` allowing user CAs. 104 105 ### 1.6 Capture in-lite app traffic 106 107 1. Open the in-lite app on your phone 108 2. Perform the actions you want to capture (login, discover devices, control 109 lights, etc.) 110 3. Watch requests appear in the mitmproxy UI 111 112 ### 1.7 Filter for relevant traffic 113 114 In the mitmproxy interactive view, press `f` to set a filter: 115 116 ``` 117 ~d api.inlite.coffeeit.nl 118 ``` 119 120 This shows only requests to the in-lite cloud API. 121 122 ### 1.8 Export captures 123 124 Press `E` in mitmproxy to export flows, or use the command-line: 125 126 ```bash 127 mitmdump --listen-port 8080 -w capture.mitm 128 ``` 129 130 Share `.mitm` files or copy relevant request/response bodies when filing 131 issues or PRs. 132 133 ### 1.9 Clean up 134 135 Remove the proxy settings from your phone and delete the CA certificate when 136 done: 137 138 - **iOS:** Settings → General → VPN & Device Management → remove mitmproxy 139 profile 140 - **Android:** Settings → Security → Trusted credentials → User → remove 141 mitmproxy 142 143 --- 144 145 ## Part 2: BLE Capture — iOS (Remote Logging) 146 147 Apple's PacketLogger can capture Bluetooth traffic from a connected iPhone. 148 This is useful for capturing how the in-lite app communicates with the hub 149 over BLE. 150 151 ### 2.1 Install the Bluetooth logging profile on iPhone 152 153 1. Visit [Apple's Profiles and Logs page](https://developer.apple.com/bug-reporting/profiles-and-logs/?name=bluetooth) 154 on your iPhone's Safari browser 155 2. Download and install the **Bluetooth** logging profile 156 3. Go to **Settings → General → VPN & Device Management** and confirm the 157 profile is installed 158 4. Restart your iPhone 159 160 > [!IMPORTANT] 161 > The profile expires periodically. Check the expiry date and reinstall if 162 > needed. 163 164 ### 2.2 Connect iPhone to Mac 165 166 1. Connect your iPhone to your Mac via USB cable 167 2. If prompted, tap **Trust** on the iPhone 168 3. Verify the connection in Finder (macOS Ventura+) or iTunes 169 170 ### 2.3 Open PacketLogger 171 172 1. Open Xcode 173 2. From the menu bar: **Xcode → Open Developer Tool → PacketLogger** 174 - If PacketLogger isn't listed, install the "Additional Tools for Xcode" 175 package from [Apple Developer Downloads](https://developer.apple.com/download/all/?q=Additional%20Tools) 176 177 ### 2.4 Select the iPhone as capture source 178 179 1. In PacketLogger, go to **File → New iOS Trace** (or **File → New Remote Trace**) 180 2. Select your connected iPhone from the device list 181 3. Click **Start** 182 183 ### 2.5 Capture BLE traffic 184 185 1. Open the in-lite app on your iPhone 186 2. Perform the actions you want to analyze (connect to hub, control lights) 187 3. PacketLogger will display all Bluetooth packets in real-time 188 189 ### 2.6 Filter for in-lite traffic 190 191 Use the filter bar to narrow results: 192 193 - Filter by **Type:** `ATT` or `GATT` to see attribute-level communication 194 - Search for the in-lite service UUID: `0000fef1-0000-1000-8000-00805f9b34fb` 195 - Filter by device name: `inlitebt` 196 197 ### 2.7 Save the capture 198 199 1. **File → Save** to save as `.pklg` file 200 2. Share this file in your PR or issue for others to analyze 201 202 ### 2.8 Clean up 203 204 Remove the Bluetooth logging profile from your iPhone when done: 205 206 - **Settings → General → VPN & Device Management** → tap the profile → 207 **Remove Profile** 208 - Restart your iPhone 209 210 --- 211 212 ## Part 3: BLE Capture — macOS (Native) 213 214 If the in-lite hub is within Bluetooth range of your Mac, you can capture BLE 215 traffic directly without an iPhone. 216 217 ### 3.1 Open PacketLogger 218 219 1. Open Xcode 220 2. **Xcode → Open Developer Tool → PacketLogger** 221 222 ### 3.2 Start a local capture 223 224 1. **File → New macOS Trace** (or simply **File → New Trace**) 225 2. Click **Start** — PacketLogger begins capturing all local Bluetooth 226 activity 227 228 ### 3.3 Trigger BLE activity 229 230 If you have a hub nearby, use the Home Assistant integration or the in-lite 231 app on a nearby phone to trigger commands. PacketLogger on the Mac captures 232 all BLE advertisements and GATT operations visible to the Mac's Bluetooth 233 adapter. 234 235 ### 3.4 Filter for in-lite hub 236 237 Use the filter bar: 238 239 - Service UUID: `0000fef1-0000-1000-8000-00805f9b34fb` 240 - Device name: `inlitebt` 241 - Characteristic UUIDs: 242 - Write/Notify: `c4edc000-9daf-11e3-8004-00025b000b00` 243 - Continuation: `c4edc000-9daf-11e3-8003-00025b000b00` 244 245 ### 3.5 Save and share 246 247 Save captures as `.pklg` files via **File → Save**. Attach them to your 248 GitHub issue or PR. 249 250 --- 251 252 ## Tips 253 254 ### What to look for in captures 255 256 - **GATT Write commands** to the characteristic UUIDs listed above — these 257 are mesh commands sent to the hub 258 - **Notify responses** from the hub on the same characteristics 259 - **Advertising data** — useful for identifying new hub models 260 - **HTTP responses** containing device lists, zone configurations, or 261 firmware version info 262 263 ### Sharing captures with maintainers 264 265 When opening an issue or PR with captured data: 266 267 1. Export and attach the raw capture file (`.mitm` for HTTP, `.pklg` for BLE) 268 2. Include a summary of what actions you performed during capture 269 3. Note your device model, app version, and iOS/macOS version 270 4. **Strip personal data** — remove or redact email addresses, tokens, and 271 garden names before sharing 272 273 ### Useful mitmproxy commands 274 275 | Key | Action | 276 |-----|--------| 277 | `f` | Set display filter | 278 | `e` | Edit a request/response | 279 | `E` | Export flows | 280 | `q` | Quit | 281 | `?` | Help | 282 283 ### PacketLogger column reference 284 285 | Column | Meaning | 286 |--------|---------| 287 | **Timestamp** | When the packet was captured | 288 | **Type** | Protocol layer (HCI, L2CAP, ATT, GATT, etc.) | 289 | **Channel** | L2CAP channel ID | 290 | **Data** | Raw packet bytes | 291 | **Summary** | Human-readable decode |