Add complete DWARFLAB protocol documentation

- Architecture overview, BLE and WebSocket protocols - All 19 modules with command IDs validated against smali source - BLE packet format with CRC-16/MODBUS pseudocode - Complete WsCmd index (~300 commands) - Connection flow with pseudocode examples - Methodology section explaining APK decompilation process
2026-06-13 00:21:19 +02:00
parent fe534ce77b
commit be87e8a4ca
14 changed files with 2373 additions and 0 deletions
--- a/05_ble_messages.md
+++ b/05_ble_messages.md
@ -0,0 +1,228 @@
+# BLE Messages (BleProto)
+
+All BLE messages are serialized as `BleProto` protobuf, wrapped in the BLE packet format described in [02_ble_protocol.md](02_ble_protocol.md).
+
+## Authentication & Configuration
+
+### ReqGetconfig — Get Device Configuration (cmd=1)
+
+Authenticate and retrieve device WiFi/IP info.
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code: 1 = GetWiFiConfig |
+| `blePsd` | 2 | string | BLE password (default: "DWARF_12345678") |
+| `clientId` | 3 | string | Client identifier |
+
+### ResGetconfig — Configuration Response
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Status code (0=success) |
+| `state` | 3 | int32 | Device state |
+| `wifiMode` | 4 | int32 | WiFi mode (0=off, 1=AP, 2=STA) |
+| `apMode` | 5 | int32 | AP mode |
+| `autoStart` | 6 | int32 | Auto-start flag |
+| `apCountryList` | 7 | int32 | AP country list |
+| `ssid` | 8 | string | Current SSID |
+| `psd` | 9 | string | WiFi password |
+| `ip` | 10 | string | Device IP (for WebSocket) |
+| `apCountry` | 11 | string | AP country code |
+
+### ReqGetsysteminfo — Get System Info (cmd=7)
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code: 7 = GetDeviceInfo |
+| `clientId` | 2 | string | Client identifier |
+
+### ResGetsysteminfo — System Info Response
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Status code |
+| `protocolVersion` | 3 | int32 | Protocol version |
+| `macAddress` | 5 | string | MAC address |
+| `device` | 4 | string | Device name |
+| `dwarfOtaVersion` | 6 | string | OTA firmware version |
+
+## WiFi Configuration
+
+### ReqSta — Configure Station Mode (cmd=3)
+
+Connect the device to an existing WiFi network.
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code: 3 = SetSTAMode |
+| `autoStart` | 2 | int32 | Auto-start flag |
+| `blePsd` | 3 | string | BLE password |
+| `ssid` | 4 | string | Target SSID |
+| `psd` | 5 | string | Target WiFi password |
+| `clientId` | 6 | string | Client identifier |
+
+### ResSta — Station Mode Response
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Status code |
+| `ssid` | 3 | string | Connected SSID |
+| `psd` | 4 | string | Password |
+| `ip` | 5 | string | Obtained IP (for WebSocket) |
+
+### ReqAp — Configure Access Point Mode (cmd=2)
+
+Configure the device as a WiFi hotspot.
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code: 2 = SetApMode |
+| `wifiType` | 2 | int32 | WiFi type |
+| `autoStart` | 3 | int32 | Auto-start flag |
+| `countryList` | 4 | int32 | Country list |
+| `country` | 5 | string | Country code |
+| `blePsd` | 6 | string | BLE password |
+| `clientId` | 7 | string | Client identifier |
+| `forceRestart` | 8 | bool | Force restart |
+
+### ResAp — Access Point Response
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Status code |
+| `mode` | 3 | int32 | Mode |
+| `ssid` | 4 | string | AP SSID |
+| `psd` | 5 | string | AP password |
+
+## Utility Commands
+
+### ReqSetblewifi — Set BLE/WiFi Name & Password (cmd=4)
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code: 4 = SetNamePwd |
+| `mode` | 2 | int32 | Mode (0/1) |
+| `blePsd` | 3 | string | BLE password |
+| `value` | 4 | string | New value |
+| `clientId` | 5 | string | Client identifier |
+
+### ReqReset — Factory Reset (cmd=5)
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code: 5 = Reset |
+| `clientId` | 2 | string | Client identifier |
+
+### ResReset — Reset Response
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Status code |
+
+### ReqGetwifilist — Scan WiFi Networks (cmd=6)
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code: 6 = GetWiFiList |
+| `clientId` | 2 | string | Client identifier |
+
+### ReqCheckFile — OTA File Check
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `filePath` | 2 | string | File path |
+| `md5` | 3 | string | MD5 checksum |
+
+### ResCheckFile — OTA Check Response
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Status code |
+
+## Keepalive: DwarfPing / DwarfEcho
+
+### DwarfPing — Heartbeat from App
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `vocaltype` | 1 | int32 | Type: 1=VT_PING |
+| `timestamp` | 2 | int64 | Unix timestamp |
+| `magic` | 3 | bytes | Session magic bytes |
+| `vocals` | 4 | repeated DwarfPing | Nested pings |
+| `mutes` | 5 | repeated NifAP | AP info list |
+
+### DwarfEcho — Heartbeat Response from Device
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `vocaltype` | 1 | int32 | Type: 2=VT_ECHO |
+| `timestamp` | 2 | int64 | Unix timestamp |
+| `magic` | 3 | bytes | Session magic bytes |
+| `tsPing` | 4 | int64 | Echo of ping timestamp |
+| `macAddress` | 5 | bytes | Device MAC address |
+| `model` | 6 | BleProto | Device model info |
+| `sn` | 7 | string | Serial number |
+| `name` | 8 | string | Device name |
+| `psw` | 9 | string | Password |
+| `fwVersion` | 10 | string | Firmware version |
+| `wsScheme` | 11 | string | WebSocket scheme ("ws") |
+| `session` | 12 | int32 | Session ID |
+| `ap` | 13 | BleProto | AP info |
+| `sta` | 14 | BleProto | STA info |
+
+## Network Info Messages
+
+### NifAP — Access Point Info
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `ifname` | 1 | string | Interface name |
+| `mode` | 2 | int32 | AP mode |
+| `countryCode` | 3 | string | Country code |
+| `ssid` | 4 | string | SSID |
+| `sec` | 5 | string | Security type |
+| `psw` | 6 | string | Password |
+| `ipv4` | 7 | bytes | IPv4 address |
+| `ipv6` | 8 | bytes | IPv6 address |
+
+### NifSTA — Station Info
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `ifname` | 1 | string | Interface name |
+| `ssid` | 2 | string | Connected SSID |
+| `psw` | 3 | string | Password |
+| `rssi` | 4 | int32 | Signal strength |
+| `ipv4` | 5 | bytes | IPv4 address |
+| `ipv6` | 6 | bytes | IPv6 address |
+
+## Common Messages
+
+### ResCommon — Generic Response
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Status code |
+
+### ResReceiveDataError — Receive Error
+
+| Field | # | Type | Description |
+|-------|---|------|-------------|
+| `cmd` | 1 | int32 | Command code |
+| `code` | 2 | int32 | Error code |
+
+### VocalType — Enum
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | VT_UNKNOWN | Unknown |
+| 1 | VT_PING | Ping (app → device) |
+| 2 | VT_ECHO | Echo (device → app) |