first commit

README.md

@@ -0,0 +1,75 @@
+# DWARFLAB Protocol Documentation
+
+Reverse-engineered communication protocol for **DWARF series smart astronomical telescopes** (DWARF 2, DWARF 3, DWARF mini, DWARF 4, DWARF DRAGON), extracted from DWARFLAB APK v3.4.0 (build 629).
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| Protocol | Protocol Buffers v3 (proto3) |
+| BLE Service | `0000DAF2-0000-1000-8000-00805f9b34fb` |
+| BLE Write | `0000DAF3-0000-1000-8000-00805f9b34fb` |
+| BLE Notify | `0000DAF4-0000-1000-8000-00805F9B34FB` |
+| WebSocket | `ws://<device_ip>:9900/?client_id=<id>` |
+| Proto version | 2.3 (major=2, minor=3) |
+| Default password | `DWARF_12345678` |
+
+## Device Models
+
+| Model | deviceId | Codename | Notes |
+|-------|----------|----------|-------|
+| Unknown | 0 | — | — |
+| DWARF 2 | 1 | — | Max name 21 chars |
+| DWARF 3 | 2 | — | Max name 19 chars |
+| *gap* | 3 | — | *unused* |
+| DWARF mini | 4 | Bilbo | Max name 15 chars, no Panorama Create, `indexBilbo.html` |
+| DWARF 4 | 5 | — | Max name 19 chars |
+| DWARF DRAGON | 6 | — | — |
+
+## Documentation Structure
+
+| File | Content |
+|------|---------|
+| [00_methodology.md](00_methodology.md) | How this was obtained: APK decompilation, smali analysis, verification |
+| [01_architecture.md](01_architecture.md) | Architecture overview, dual-channel design, module table |
+| [02_ble_protocol.md](02_ble_protocol.md) | BLE GATT, packet format, CRC, commands, auth flow |
+| [03_websocket_protocol.md](03_websocket_protocol.md) | WebSocket connection, WsPacket format, keepalive |
+| [04_base_messages.md](04_base_messages.md) | WsPacket, CommonParam, ComResponse, version enums |
+| [05_ble_messages.md](05_ble_messages.md) | BleProto messages: auth, WiFi config, ping/echo |
+| [06_camera_commands.md](06_camera_commands.md) | CameraProto: TELE (51 cmds) & WIDE (36 cmds) |
+| [07_astro_commands.md](07_astro_commands.md) | AstroProto: goto, live stacking, dark frames, calibration |
+| [08_motor_focus_track_commands.md](08_motor_focus_track_commands.md) | MotorControl, Focus, Track: motors, AF, tracking, sentry |
+| [09_device_rgb_commands.md](09_device_rgb_commands.md) | DeviceProto & RGBProto: defog, cooling, LED, power |
+| [10_system_param_voice_commands.md](10_system_param_voice_commands.md) | System, Param, ITips, VoiceAssistant |
+| [11_task_notify_panorama_schedule_commands.md](11_task_notify_panorama_schedule_commands.md) | TaskCenter, Notify, Panorama, Schedule |
+| [12_command_index.md](12_command_index.md) | Complete WsCmd numeric index for all 19 modules |
+| [13_connection_flow.md](13_connection_flow.md) | Step-by-step connection flow, packet diagrams, pseudocode |
+
+## Communication Architecture
+
+```
+┌──────────┐                     ┌──────────┐
+│  App      │   BLE (setup/auth)  │  DWARF   │
+│  (Android)│◄───────────────────►│  Device  │
+│           │   GATT DAF2/DAF3    │          │
+│           │                     │          │
+│           │   WebSocket (ctrl)  │          │
+│           │◄──────────────────►│          │
+│           │  ws://IP:9900       │          │
+└──────────┘                     └──────────┘
+```
+
+1. **BLE** — Discovery, authentication, WiFi configuration
+2. **WebSocket** — All telescope control, notifications, keepalive
+
+## Security Notes
+
+- BLE password: 8-63 chars, no spaces, default `DWARF_12345678`
+- Same password used for both BLE auth and WiFi
+- WebSocket is unencrypted (`ws://`, not `wss://`)
+- Session magic bytes: `DWfvuu]`, `4dwf`, `aRdWf`, `DWFq`, `dwFS`, `DwftA`, `DWFL`
+
+## Source
+
+Extracted from decompiled APK (`com.convergence.dwarflab`, v3.4.0, build 629).
+Key smali files: `cg1.smali` (UUIDs), `WsCmd.smali` (commands), `WsModuleId.smali` (modules), `l80.smali` (BLE packet), `v55.smali` (WS URL), `DeviceType.smali` (models).