dwarf-go/analysis/API_REFERENCE.md

# DWARFLAB Telescope — API Reference (reverse-engineered)

Reverse-engineered from `DWARFLAB.apk` v3.4.0 (build 629), package `com.convergence.dwarflab`.
This document describes the protocol used by the official Android app to talk to
DWARF II (and the in-development "Bilbo"/DWARF III) smart telescopes.

> Goal: enable an open-source client implementation. All command IDs, the wire
> envelope, and the inner protobuf payloads were recovered from the APK; nothing
> here is guessed.

---

## 1. Architecture at a glance

```
┌─────────────┐   BLE (GATT)     ┌───────────┐
│  Phone app  │ ───────────────▶ │ Telescope │   1. discovery + Wi-Fi creds exchange
│             │ ◀── DwarfEcho ── │           │      (DwarfPing / DwarfEcho, see ble.proto)
└──────┬──────┘                  └─────┬─────┘
       │ joins telescope Wi-Fi         │
       │ (AP mode, or shared STA)      │
       │                               │
       │  WebSocket (binary)           │  RTSP (TCP)
       │  ws://<ip>:9900/?client_id=.. │  rtsp://<ip>/<cam>/stream0
       ▼                               ▼
┌───────────────────────────┐   ┌──────────────┐
│ Control plane             │   │ Live preview │
│ WsPacket (protobuf)       │   │ ijkplayer /  │
│ 323 commands, 17 modules  │   │ ExoPlayer    │
└───────────────────────────┘   └──────────────┘
```

Two distinct data planes:

| Plane | Transport | Port | Encoding | Purpose |
|-------|-----------|------|----------|---------|
| **Control** | WebSocket (binary frames) | **9900** | protobuf `WsPacket` envelope | All telescope commands & status |
| **Preview** | RTSP over TCP | 554 (std) | H.264/H.265 | Live camera viewfinder |
| **Discovery** | BLE GATT | — | protobuf (`ble.proto`) | Find telescope, get IP/SSID/PSK |

There is also a **cloud relay**: `https://app.dwarflabapp.com/app/uls/connect?d=…`
("ULS") used for remote access when the phone is not on the telescope's Wi-Fi.
Local LAN control (the focus of an OSS client) needs only BLE + WebSocket + RTSP.

---

## 2. Connection flow

### 2.1 Discovery & credentials (BLE)
The telescope advertises over BLE. The app sends a `DwarfPing` / `ReqGetconfig`
and receives a **`DwarfEcho`** (`ble.proto`) containing everything needed to
connect over IP:

```proto
message DwarfEcho {
  VocalType vocaltype = 1;
  uint64 timestamp = 2;
  bytes magic = 3;
  uint64 ts_ping = 4;
  bytes mac_address = 5;
  StationModel model = 6;     // telescope family + revision
  string sn = 7;              // serial number
  string name = 8;            // advertised name
  string psw = 9;             // device password
  string fw_version = 10;
  string ws_scheme = 11;      // "ws" or "wss"
  uint32 session = 12;
  NifAP ap = 13;              // AP network (ifname/ssid/psw/ipv4/ipv6)
  NifSTA sta = 14;            // STA network (ifname/ssid/psw/rssi/ipv4/ipv6)
}
```

`ble_psd` (BLE password) + `client_id` authenticate the BLE requests
(`ReqGetconfig`, `ReqSta`, `ReqAp`, `ReqSetblewifi`). Responses carry the
**`ip`** field (`ResGetconfig.ip` / `ResSta.ip`) that the app feeds into the
WebSocket URL.

### 2.2 WebSocket control channel
Once the phone is on the telescope's network:

```
ws://<telescope_ip>:9900/?client_id=<client_id>
```

- Plain `ws://` by default; `wss://` if `ws_scheme == "wss"`.
- `client_id` is a client-generated identifier (`y32…m58158c()`).
- Source: `v55.java` field `f43155b` / method `m55420t(ip)`.
- **device_id** field in the envelope selects which telescope (multi-device),
  defaults to `1` for the first/only connected scope.

### 2.3 RTSP preview
```
rtsp://<telescope_ip>:554/<channel>/stream0
```
- `<channel>`: `ch0` = Tele camera, `ch1` = Wide camera
- **IMPORTANT**: The camera MUST be opened via WebSocket (`CMD_CAMERA_TELE_OPEN_CAMERA` 10000 or `CMD_CAMERA_WIDE_OPEN_CAMERA` 12000) before the RTSP stream becomes available. Without opening the camera, the RTSP server accepts connections but never sends frames.
- Player options force `rtsp_transport = tcp` (see `RtspPlayerView.java:195`).
- Codec: MJPEG over RTSP (not H.264).
- Port 8092 (MJPEG HTTP `/mainstream` and `/secondstream`) exists but is **inactive** on the DWARF Mini — the Mini uses RTSP exclusively.

### 2.4 Visual odometry (image-based orientation)

The wide-angle RTSP frames can be used to estimate the telescope's pointing
rotation **without star identification or plate solving**, by comparing
consecutive frames with FFT phase correlation. This is implemented in
`dwarfctl` as the `orient` command (`internal/odometry/`).

**Principle:** for small rotations of a static mount, the scene undergoes an
almost pure 2-D translation in the image plane. Phase correlation recovers that
translation with sub-pixel accuracy, which maps directly to pan/tilt degrees via
the camera field of view. Accumulating frame-to-frame shifts gives cumulative
pointing orientation.

**Use cases on the DWARF Mini:**
- **Daytime airplane tracking** — the wide cam provides sky/horizon texture
- **Nighttime satellite tracking** — star fields serve as correlation texture

**Pipeline:**
1. Open the wide camera (`CMD_CAMERA_WIDE_OPEN_CAMERA` 12000) — or let `orient
   live` do it automatically
2. Grab frames via `ffmpeg -rtsp_transport tcp -i rtsp://<ip>/ch1/stream0`
3. Compare consecutive frames (`Estimate`) or integrate continuously (`Tracker`)

**FoV caveat:** the DWARF Mini's display FoV is 8.0°×6.5° (see
`DEVICE_MODELS.md`), but the firmware-reported live FoV can differ. The pixel
shift is always correct; only the degree conversion depends on the FoV
parameter. Calibrate by slewing a known motor angle and comparing.

---

## 3. Wire format — `WsPacket` envelope

Every WebSocket binary frame is **one serialized `WsPacket`** (`base.proto`):

```proto
message WsPacket {
  uint32 major_version = 1;  // = 2  (WS_MAJOR_VERSION_NUMBER)
  uint32 minor_version = 2;  // = 3  (WS_MINOR_VERSION_NUMBER)  → protocol v2.3
  uint32 device_id     = 3;  // telescope index, default 1
  uint32 module_id     = 4;  // derived from cmd (see §4)
  uint32 cmd           = 5;  // operation id (10000–17099)
  uint32 type          = 6;  // 0=request 1=response 2=notification 3=reply
  bytes  data          = 7;  // inner protobuf message, serialized
  string client_id     = 8;  // same client_id as the WS URL
}
```

Confirmed build code (`e49.java`, `C9312a.m36361a`):
```java
WsPacket.newBuilder()
  .setMajorVersion(2)
  .setMinorVersion(3)
  .setDeviceId(connectedDeviceId != null ? connectedDeviceId : 1)
  .setModuleId(wsCmd.getModuleId().ordinal())   // derived from cmd range
  .setCmd(wsCmd.getCmd())
  .setType(wsCmd.getMessageType().ordinal())    // request=0
  .setData(ByteString.copyFrom(innerProto.toByteArray()))
  .setClientId(clientId)
  .build();
```

`type` enum (`WsMessageType`): `request=0`, `response=1`, `notification=2`, `reply=3`.

### 3.1 Request/response matching
Responses are matched by **`cmd`**. The app registers a pending continuation
keyed by the expected response `cmd`; an incoming `WsPacket` whose `cmd` matches
is parsed (`WsRequestHandle.mo7785d` → `BaseProto.WsPacket.parseFrom`, then the
inner `data` is parsed into the expected proto class).

For most commands the **response uses the same `cmd`** as the request
(`WsMessageReq.getResponseCmd()` defaults to `getCmd()`, see `d49.m35708a`).

**IMPORTANT — discovered via live testing (not in the APK code):**
The telescope uses **`type=3` (REPLY)** for direct responses, not `type=1`
(RESPONSE). Additionally, not all commands get a reply:

| Response model | Commands (tested) | Implementation |
|---------------|-------------------|----------------|
| **type=3 reply (same cmd)** | photo (10002), photo wide (12022), focus auto (15000), focus step (15001), state (16405), sync-time (13000), set-location (13010) | request-response with timeout |
| **notification only (type=2)** | RGB on/off (13500/13501), camera open/close (10000/10001), camera params GET (10036) | fire-and-forget; verify via `state` |
| **fire-and-forget native** | motor slew (14006), motor stop (14002) | no ack expected |

Commands that only produce notifications still execute successfully — the
state change is visible in `GetDeviceState` (e.g. `rgb_state:{}` after RGB off).

### 3.2 Notifications
The telescope pushes `WsPacket` frames with `type=2` (notification) and `cmd` in
the **15200–15303** range (`CMD_NOTIFY_*`). An OSS client must listen for these
to reflect state changes (track results, burst/record progress, temperatures,
calibration state, SD-card info, power, etc.). See `Notify.proto` (81 messages)
and `CMD_TABLE.md` (NOTIFY module).

---

## 4. Command routing

`module_id` is **not** stored per-command — it is derived from `cmd` by range
checks in `WsCmd.getModuleId()`:

| cmd range | module_id (ordinal) | module | proto file |
|-----------|---------------------|--------|------------|
| 10000–10499 | 1 | CAMERA_TELE | `Camera.proto` |
| 11000–11499 | 3 | ASTRO | `Astro.proto` |
| 12000–12499 | 2 | CAMERA_WIDE | `Camera.proto` |
| 13000–13299 | 4 | SYSTEM | `System.proto` |
| 13500–13799 | 5 | RGB_POWER | (RGB led / power) |
| 14000–14499 | 6 | MOTOR | `MotorControl.proto` |
| 14800–14899 | 7 | TRACK | `Track.proto` |
| 15000–15199 | 8 | FOCUS | `Focus.proto` |
| 15200–15499 | 9 | NOTIFY | `Notify.proto` |
| 15500–15599 | 10 | PANORAMA | `Panorama.proto` |
| 15700–15799 | 11 | ITIPS | `ITips.proto` |
| 16100–16399 | 13 | SHOOTING_SCHEDULE | `Schedule.proto` |
| 16400–16599 | 14 | TASK_CENTER | `TaskCenter.proto` |
| 16700–16799 | 15 | PARAM | `Param.proto` |
| 16800–16899 | 16 | VOICE_ASSISTANT | `VoiceAssistant.proto` |
| 17000–17099 | 18 | DEVICE | `Device.proto` |

**Full table of all 323 commands → see [`CMD_TABLE.md`](CMD_TABLE.md).**

The mapping from command → inner protobuf message type lives in the
`data/websocket/<module>/` handlers (`*WsResponseHandle.java`) and the
`data/bean/p021ws/request/` request classes. To find the payload type for a
given cmd, grep the request package.

---

## 5. Proto definitions

Regenerated cleanly from the embedded `FileDescriptorProto` descriptors in the
APK — **17 files, 382 messages**. Located in `analysis/protos/`:

| File | msgs | Covers |
|------|------|--------|
| `Base.proto` | 6 | WsPacket envelope, ComResponse, CommonParam |
| `Camera.proto` | 55 | Both cameras: exp/gain/WB/ISP/RAW/record/burst/resolution |
| `Astro.proto` | 67 | Calibration, GOTO (DSO/solar), live-stacking, darks, EQ solving, AI enhance, mosaic, sky-finder |
| `MotorControl.proto` | 14 | RA/DEC motors: run/stop/runTo/joystick/reset/positions |
| `Track.proto` | 9 | Tracking, sentry mode, MOT, UFO (multi-object track) |
| `Focus.proto` | 9 | Auto-focus (normal + astro), manual continuous, user infinity |
| `Panorama.proto` | 18 | Grid/stitch/framing/upload/compress |
| `Notify.proto` | 81 | All async server-push events |
| `Schedule.proto` | 20 | Shooting plan sync/cancel/lock |
| `TaskCenter.proto` | 26 | Global task manager, state info, mode/tech switch |
| `System.proto` | 14 | Time/timezone, location, MTP, CPU mode, activation, low-temp protection |
| `Param.proto` | 8 | Generic param set (exposure/gain/WB/int/float/bool/auto) |
| `Device.proto` | 3 | Lens defog, auto-cooling, auto-shutdown |
| `Ble.proto` | 25 | BLE handshake (DwarfPing/DwarfEcho/config/AP/STA/wifi-scan) |
| `VoiceAssistant.proto` | 16 | On-device voice assistant tasking |
| `RGB.proto` | 6 | RGB LED ring / power indicator |
| `ITips.proto` | 5 | Tips content |

To regenerate: `python3 analysis/extract_protos.py <jadx proto dir> <out dir>`

---

## 6. Worked example — take a photo with the Tele camera

1. **(once)** BLE: connect, get `DwarfEcho` → extract `sta.ipv4`/`ap.ipv4`,
   `psw`, join Wi-Fi.
2. Open WebSocket `ws://<ip>:9900/?client_id=droid-oss-001`.
3. Open the Tele camera: send `WsPacket{cmd=10000, data=ReqOpenCamera}`,
   wait for `ComResponse{code=0}`.
4. Set exposure (optional): `cmd=10009` with `ReqSetExp{…}`.
5. Photograph: `cmd=10002` (`CMD_CAMERA_TELE_PHOTOGRAPH`).
6. Watch notifications `15273` (PHOTO_STATE) / `15274` (BURST_STATE) for result.

Common response type is `ComResponse{ int32 code = 1; }` — `code==0` means OK.

---

## 7. Parameter value maps (assets)

The APK ships ready-made enum maps that constrain valid values:

- **`assets/params_range.json`** — exposure index ↔ `"1/N"` label (0…full
  mapping, e.g. index 0 = "1/10000", step 3).
- **`assets/shoot_plan_config.json`** — per-device capability matrix. Defines
  DWARF II (id=1, fw 2.1.6): two cameras (`Tele` id=0, `Wide` implicit),
  their FoV (`fvWidth/fvHeight`), preview size (1280×720), and every supported
  param with `min/max/step/defaultValue/valueType` + Gear vs Continue modes.
  This file is the authoritative source for **what values each camera accepts**.
- **`assets/astronomy_data.db`** — SQLite of celestial objects (GOTO targets).
- **`assets/www/modules/eq/`** — Three.js 3D equatorial-alignment helper
  (polar-alignment UI). "Bilbo" = next-gen model codename (DWARF III).

---

## 8. Multi-device & activation notes

- `device_id` in `WsPacket` selects the active telescope when several are on the
  same network; default `1`.
- Some telescopes are **factory-activated** via `CMD_SYSTEM_*` (13005–13008):
  `ReqGetDeviceActivateInfo`, `ReqDeviceActivateWriteFile`, activation-notify,
  factory-test un-activate. An OSS client should generally leave activation
  alone.
- `CMD_SYSTEM_SET_MASTER` (13004) toggles master/slave mode
  (`ReqsetMasterLock{bool lock}`).
- MTP mode (`CMD_SYSTEM_SET_MTP_MODE`, 13002) switches the telescope between
  Mass-Storage (mount SD card over USB) and normal modes.

---

## 9. Suggested open-source client architecture

```
dwarf-oss/
├── proto/                 ← copy analysis/protos/*.proto here
├── ble/                   ← BLE scanner + DwarfPing/DwarfEcho handshake (ble.proto)
├── transport/
│   ├── ws_client.py       ← ws://<ip>:9900/?client_id=…, send/recv WsPacket
│   ├── envelope.py        ← WsPacket build/parse (Base.proto)
│   └── dispatcher.py      ← cmd → pending-request matching, NOTIFY fan-out
├── rtsp/                  ← GStreamer/ffmpeg/PyAV pull of rtsp://<ip>/<cam>/stream0
├── modules/
│   ├── camera.py          ← cmds 10000/12000 (Tele/Wide)
│   ├── motor.py           ← cmds 14000 (point/slew)
│   ├── astro.py           ← cmds 11000 (calib/goto/stacking/darks)
│   ├── focus.py           ← cmds 15000
│   ├── track.py           ← cmds 14800
│   └── task.py            ← cmds 16400 (one-click shooting)
└── cli.py                 ← `dwarf photo`, `dwarf goto M31`, `dwarf slew 1.2 0`
```

Key implementation tips:
- Send `major_version=2, minor_version=3` always.
- Reuse one persistent WebSocket; don't reconnect per command.
- Maintain a registry of `cmd → asyncio.Future` for request/response; a single
  inbound dispatcher handles both responses and notifications.
- Start with `CMD_GLOBAL_TASK_GET_DEVICE_STATE_INFO` (16405) after connect to
  snapshot the current state, then rely on NOTIFY pushes.
- For live view, a separate RTSP consumer is simpler than multiplexing over the
  WebSocket.

---

## 10. Tooling used / how to reproduce

```
tools/jadx/bin/jadx -d extracted/jadx DWARFLAB.apk     # decompile
python3 analysis/extract_protos.py extracted/.../proto analysis/protos
# WsCmd / WsModuleId / WsMessageType enums → analysis/CMD_TABLE.md
```

Key source locations inside `extracted/jadx/sources/`:
- `com/convergence/dwarflab/proto/` — 17 `*Proto.java` (descriptors).
- `com/convergence/dwarflab/data/bean/p021ws/WsCmd.java` — all command ids.
- `…/WsModuleId.java`, `…/WsMessageType.java` — enums.
- `…/request/WsMessageReq.java` — request interface (`d49.java` = sender).
- `com/convergence/dwarflab/data/websocket/<module>/` — per-module handlers.
- `p000/e49.java` — WsPacket builder (`C9312a.m36361a`).
- `p000/v55.java` — WebSocket connection manager (URL/port 9900).
- `p000/b49.java` — OkHttp WebSocket wrapper.