# BLE Messages (BleProto)

All BLE messages are serialized as `BleProto` protobuf, wrapped in the BLE packet format described in [02_ble_protocol.md](02_ble_protocol.md).

## Authentication & Configuration

### ReqGetconfig — Get Device Configuration (cmd=1)

Authenticate and retrieve device WiFi/IP info.

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code: 1 = GetWiFiConfig |
| `blePsd` | 2 | string | BLE password (default: "DWARF_12345678") |
| `clientId` | 3 | string | Client identifier |

### ResGetconfig — Configuration Response

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Status code (0=success) |
| `state` | 3 | int32 | Device state |
| `wifiMode` | 4 | int32 | WiFi mode (0=off, 1=AP, 2=STA) |
| `apMode` | 5 | int32 | AP mode |
| `autoStart` | 6 | int32 | Auto-start flag |
| `apCountryList` | 7 | int32 | AP country list |
| `ssid` | 8 | string | Current SSID |
| `psd` | 9 | string | WiFi password |
| `ip` | 10 | string | Device IP (for WebSocket) |
| `apCountry` | 11 | string | AP country code |

### ReqGetsysteminfo — Get System Info (cmd=7)

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code: 7 = GetDeviceInfo |
| `clientId` | 2 | string | Client identifier |

### ResGetsysteminfo — System Info Response

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Status code |
| `protocolVersion` | 3 | int32 | Protocol version |
| `macAddress` | 5 | string | MAC address |
| `device` | 4 | string | Device name |
| `dwarfOtaVersion` | 6 | string | OTA firmware version |

## WiFi Configuration

### ReqSta — Configure Station Mode (cmd=3)

Connect the device to an existing WiFi network.

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code: 3 = SetSTAMode |
| `autoStart` | 2 | int32 | Auto-start flag |
| `blePsd` | 3 | string | BLE password |
| `ssid` | 4 | string | Target SSID |
| `psd` | 5 | string | Target WiFi password |
| `clientId` | 6 | string | Client identifier |

### ResSta — Station Mode Response

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Status code |
| `ssid` | 3 | string | Connected SSID |
| `psd` | 4 | string | Password |
| `ip` | 5 | string | Obtained IP (for WebSocket) |

### ReqAp — Configure Access Point Mode (cmd=2)

Configure the device as a WiFi hotspot.

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code: 2 = SetApMode |
| `wifiType` | 2 | int32 | WiFi type |
| `autoStart` | 3 | int32 | Auto-start flag |
| `countryList` | 4 | int32 | Country list |
| `country` | 5 | string | Country code |
| `blePsd` | 6 | string | BLE password |
| `clientId` | 7 | string | Client identifier |
| `forceRestart` | 8 | bool | Force restart |

### ResAp — Access Point Response

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Status code |
| `mode` | 3 | int32 | Mode |
| `ssid` | 4 | string | AP SSID |
| `psd` | 5 | string | AP password |

## Utility Commands

### ReqSetblewifi — Set BLE/WiFi Name & Password (cmd=4)

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code: 4 = SetNamePwd |
| `mode` | 2 | int32 | Mode (0/1) |
| `blePsd` | 3 | string | BLE password |
| `value` | 4 | string | New value |
| `clientId` | 5 | string | Client identifier |

### ReqReset — Factory Reset (cmd=5)

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code: 5 = Reset |
| `clientId` | 2 | string | Client identifier |

### ResReset — Reset Response

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Status code |

### ReqGetwifilist — Scan WiFi Networks (cmd=6)

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code: 6 = GetWiFiList |
| `clientId` | 2 | string | Client identifier |

### ReqCheckFile — OTA File Check

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `filePath` | 2 | string | File path |
| `md5` | 3 | string | MD5 checksum |

### ResCheckFile — OTA Check Response

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Status code |

## Keepalive: DwarfPing / DwarfEcho

### DwarfPing — Heartbeat from App

| Field | # | Type | Description |
|-------|---|------|-------------|
| `vocaltype` | 1 | int32 | Type: 1=VT_PING |
| `timestamp` | 2 | int64 | Unix timestamp |
| `magic` | 3 | bytes | Session magic bytes |
| `vocals` | 4 | repeated DwarfPing | Nested pings |
| `mutes` | 5 | repeated NifAP | AP info list |

### DwarfEcho — Heartbeat Response from Device

| Field | # | Type | Description |
|-------|---|------|-------------|
| `vocaltype` | 1 | int32 | Type: 2=VT_ECHO |
| `timestamp` | 2 | int64 | Unix timestamp |
| `magic` | 3 | bytes | Session magic bytes |
| `tsPing` | 4 | int64 | Echo of ping timestamp |
| `macAddress` | 5 | bytes | Device MAC address |
| `model` | 6 | BleProto | Device model info |
| `sn` | 7 | string | Serial number |
| `name` | 8 | string | Device name |
| `psw` | 9 | string | Password |
| `fwVersion` | 10 | string | Firmware version |
| `wsScheme` | 11 | string | WebSocket scheme ("ws") |
| `session` | 12 | int32 | Session ID |
| `ap` | 13 | BleProto | AP info |
| `sta` | 14 | BleProto | STA info |

## Network Info Messages

### NifAP — Access Point Info

| Field | # | Type | Description |
|-------|---|------|-------------|
| `ifname` | 1 | string | Interface name |
| `mode` | 2 | int32 | AP mode |
| `countryCode` | 3 | string | Country code |
| `ssid` | 4 | string | SSID |
| `sec` | 5 | string | Security type |
| `psw` | 6 | string | Password |
| `ipv4` | 7 | bytes | IPv4 address |
| `ipv6` | 8 | bytes | IPv6 address |

### NifSTA — Station Info

| Field | # | Type | Description |
|-------|---|------|-------------|
| `ifname` | 1 | string | Interface name |
| `ssid` | 2 | string | Connected SSID |
| `psw` | 3 | string | Password |
| `rssi` | 4 | int32 | Signal strength |
| `ipv4` | 5 | bytes | IPv4 address |
| `ipv6` | 6 | bytes | IPv6 address |

## Common Messages

### ResCommon — Generic Response

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Status code |

### ResReceiveDataError — Receive Error

| Field | # | Type | Description |
|-------|---|------|-------------|
| `cmd` | 1 | int32 | Command code |
| `code` | 2 | int32 | Error code |

### VocalType — Enum

| Value | Name | Description |
|-------|------|-------------|
| 0 | VT_UNKNOWN | Unknown |
| 1 | VT_PING | Ping (app → device) |
| 2 | VT_ECHO | Echo (device → app) |