# Architecture Overview

## Dual-Channel Design

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

1. **BLE (Bluetooth Low Energy)** — Initial setup, authentication, WiFi configuration
2. **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`)