# 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).