Files

Jacquin Antoine be87e8a4ca 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

4.4 KiB

Raw Blame History

Architecture Overview

Dual-Channel Design

The DWARFLAB app communicates with DWARF telescopes via two distinct channels:

BLE (Bluetooth Low Energy) — Initial setup, authentication, WiFi configuration
WebSocket (TCP) — Main telescope control after WiFi connection

Both channels use Protocol Buffers v3 (proto3) for serialization, but with different transport framing.

┌──────────┐                     ┌──────────┐
│  App      │   BLE (setup/auth)  │  DWARF   │
│  (Android)│◄──────────────────►│  Device  │
│           │   GATT DAF2/DAF3    │          │
│           │                     │          │
│           │   WebSocket (ctrl)  │          │
│           │◄──────────────────►│          │
│           │  ws://IP:9900       │          │
└──────────┘                     └──────────┘

Protocol Stack

Layer	BLE	WebSocket
Transport	GATT (Bluetooth)	TCP (WiFi)
Port	—	9900 (primary), 4409/4410 (secondary)
Encoding	Protobuf + BLE header (9B + CRC16 + 0x0D)	Protobuf inside WsPacket envelope
Service UUID	`0000DAF2-...`	—
Write Char	`0000DAF3-...`	—
Notify Char	`0000DAF4-...`	—
Proto version	BleProto	WsPacket v2.3

Module Table

The protocol is organized into 19 modules, each with a base command ID:

Module ID	Name	Proto	Base cmd ID	Description
0	NONE	—	—	No module
1	CAMERA_TELE	CameraProto	10000	Telescope camera (51 commands)
2	CAMERA_WIDE	CameraProto	12000	Wide-angle camera (36 commands)
3	ASTRO	AstroProto	11000	Astronomy features (49 commands)
4	SYSTEM	SystemProto	13000	System settings (11 commands)
5	RGB_POWER	RGBProto	13500	RGB LED, power control (6 commands)
6	MOTOR	MotorControlProto	14000	Stepper motor control (6 commands)
7	TRACK	TrackProto	14800	Equatorial tracking, sentry (13 commands)
8	FOCUS	FocusProto	15000	Autofocus, manual focus (8 commands)
9	NOTIFY	NotifyProto	15200	Device notifications (104 commands)
10	PANORAMA	PanoramaProto	15500	Panorama shooting (14 commands)
11	ITIPS	ITipsProto	15700	In-app tips (1 command)
12	FACTORY_TEST	—	15900	Factory testing (0 commands)
13	SHOOTING_SCHEDULE	ScheduleProto	16100	Scheduled shooting (8 commands)
14	TASK_CENTER	TaskCenterProto	16400	Task management (7 commands)
15	PARAM	ParamProto	16700	Generic parameters (7 commands)
16	VOICE_ASSISTANT	VoiceAssistantProto	16800	Voice commands (1 command)
17	CAMERA_GUIDE	—	16900	Camera guide (0 commands)
18	DEVICE	DeviceProto	17000	Defog, cooling, shutdown (3 commands)

Message Types

Type ID	Name	Direction	Description
0	request	App → Device	Command request
1	response	Device → App	Command response
2	notification	Device → App	Spontaneous notification
3	reply	Device → App	Acknowledgement

Response Codes

0 = Success
>0 = Error (module/command specific)

Security

BLE password: 8-63 characters, no spaces. Default: DWARF_12345678
Same password is used for both BLE auth and WiFi credential
WebSocket: Unencrypted (ws://, not wss://)
Session magic bytes: DWfvuu], 4dwf, aRdWf, DWFq, dwFS, DwftA, DWFL

Cloud Infrastructure

Component	Value
Backend	`dwarflab-a7062.appspot.com` (Firebase/Google Cloud)
Firebase API Key	`9d5ebf662da7e6515bcb7a7ee28a5fba`
S3 Bucket	`dwarf-bucket-02-1251529954` (AWS TransferUtility)
Google Client ID	`974715938350-1aeid736pk07h0ru7v3tfmpic624nsr1.apps.googleusercontent.com`

DWARF mini Specifics

The DWARF mini (deviceId=4, codename "Bilbo") uses the same modules and protocol as other models, with these differences:

No Panorama Create support (isSupportPanoramaCreate = false)
Max device name length = 15 (vs 21 for DWARF 2, 19 for DWARF 3/4)
Dedicated EQ page: indexBilbo.html
Some features gated by protocol version (ProtocolVersion)

4.4 KiB Raw Blame History