> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmelody.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Device Setup

> Read Melody device information, monitor live status, adjust settings, trigger service commands, and inspect debug data over the WiFi API.

This page describes how the **WiFi API** exposes device information, live status, configuration settings, service commands, and debug data for the **Melody hardware device**.

All examples here assume you are calling the WiFi-related endpoints on:

```text theme={null}
https://api.getmelody.io
```

with standard headers:

```http theme={null}
Authorization: Bearer <SESSION_TOKEN>
X-Device-Key: <DEVICE_KEY>
Content-Type: application/json
```

***

## Device Information *(Read)*

Static information about the connected Melody device.

| Field                   | Type     | Description                                            |
| ----------------------- | -------- | ------------------------------------------------------ |
| `firmwareVersion`       | `string` | CI/CD firmware name (e.g. `"v0.0.3-6-g4210228-dirty"`) |
| `deviceType`            | `string` | Device model (e.g. `"melody"`)                         |
| `hardwareRevision`      | `string` | Hardware revision identifier/number                    |
| `factoryActivationTime` | `uint32` | Unix timestamp of factory activation                   |

These values are typically returned by a **device info** or **status** endpoint and rarely change during normal operation (except firmware version after OTA).

***

## Device Status *(Read)*

Dynamic operational data from the Melody device.

| Field                | Type     | Range      | Description                                                                                 |
| -------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------- |
| `deviceTime`         | `int64`  | ms         | Current device time in milliseconds (power-on time if no internet time source is available) |
| `batteryLevel`       | `uint32` | 0–100      | Battery level (%)                                                                           |
| `batteryVoltage`     | `float`  | 10.0–15.0  | Battery voltage (V)                                                                         |
| `temperatureSensor1` | `float`  | °C         | PCB temperature near the charger section                                                    |
| `temperatureSensor2` | `float`  | °C         | PCB temperature near the motor section                                                      |
| `wifiConnected`      | `bool`   | —          | Whether the device is connected to a WiFi access point                                      |
| `wifiRssi`           | `int32`  | -100 to 10 | WiFi RSSI signal strength (dB)                                                              |
| `bleConnected`       | `bool`   | —          | Whether there is an active BLE client connection                                            |

Use these fields to show **battery state**, **thermal status**, and **connectivity health** in your UI.

***

## Device Settings *(Read/Write)*

Configurable parameters that control connectivity and naming.

| Field         | Type     | Description                                                                                  |
| ------------- | -------- | -------------------------------------------------------------------------------------------- |
| `deviceName`  | `string` | Human-readable device name (e.g. `"Melody Toy"`) shown in apps / BLE lists                   |
| `wifiEnabled` | `bool`   | Enable or disable WiFi connectivity                                                          |
| `bleEnabled`  | `bool`   | Enable or disable BLE connectivity                                                           |
| `travelMode`  | `bool`   | If enabled, device powers on after 3 seconds button hold. If disabled, powers on after 500ms |
| `introLabel`  | `string` | Custom string shown after "Hello!" label on the intro screen                                 |
| `clientName`  | `string` | Client name set by the client after connection (max 64 chars)                                |

When updating settings, make sure your UI clearly reflects any changes that could **disconnect** the current control channel (for example, disabling WiFi while using WiFi).

***

## Service Commands *(Write)*

Service commands trigger specific system-level actions on the device. Send them via `POST /device/maintenance/command` with a JSON body containing `command` and, where applicable, additional parameters.

> **Important:** Calibration and OTA may move the stroker or restart the device. Always require explicit user confirmation before triggering these commands.

| Command              | Type    | Description                                                                                |
| -------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `START_CALIBRATION`  | `bool`  | Start stroker calibration. Warn users to detach the device and confirm before execution.   |
| `START_OTA`          | `bool`  | Check for firmware updates. Requires user confirmation before applying an update.          |
| `START_OTP`          | `bool`  | Request an OTP token used for API authentication / secure pairing flows.                   |
| `POWER_DOWN`         | `bool`  | Shut down the device safely.                                                               |
| `SET_CURRENT_SCREEN` | `uint8` | Navigate the device display to the specified screen. Pass `screen_id` in the request body. |

**Example — navigate to WiFi screen:**

```json theme={null}
POST /device/maintenance/command
{
  "command": "SET_CURRENT_SCREEN",
  "screen_id": 6
}
```

***

## Current Screen *(Read)*

Read the screen currently shown on the device display.

```text theme={null}
GET /device/screen
```

**Response:**

```json theme={null}
{ "screen_id": 6 }
```

**Available screen IDs:**

> IDs `1` (Intro), `4` (Playback), `16` (Battery Warning), and `17` (Overheat Warning) are intentionally omitted — these screens are shown automatically by the device and cannot be navigated to directly.

| ID   | Name             |
| ---- | ---------------- |
| `2`  | Main             |
| `3`  | Manual           |
| `5`  | Settings         |
| `6`  | WiFi             |
| `7`  | BLE              |
| `8`  | Range Adjustment |
| `9`  | Speed Adjustment |
| `10` | Brightness       |
| `11` | Info             |
| `12` | Calibration      |
| `13` | Firmware Update  |
| `14` | OTP              |
| `15` | Reset Settings   |

***

## Firmware Update Info *(Read)*

Information about firmware update availability and state.

| Field                   | Type     | Description                                                 |
| ----------------------- | -------- | ----------------------------------------------------------- |
| `latestFirmwareVersion` | `string` | Latest available firmware version on the update server      |
| `firmwareStatus`        | `string` | One of: `up-to-date`, `update-available`, `update-required` |

You can use these fields to show firmware banners in your UI and decide when to surface **“Update available”** prompts.

***

## Debug Information *(Read)*

Debug data is exposed for diagnostics and should not normally be shown to end users.\
It is especially useful during development, QA, or support tooling.

| Field                     | Type     | Description                                               |
| ------------------------- | -------- | --------------------------------------------------------- |
| `freeHeapSize`            | `uint32` | Available heap memory in bytes                            |
| `externalFlashSize`       | `uint32` | External flash storage size in bytes                      |
| `deviceTokenRetrieveTime` | `uint32` | Unix timestamp when the device token was received         |
| `debugLoggingEnabled`     | `bool`   | Whether the device is currently emitting debug log frames |

***

## Debug Logging *(Write)*

You can instruct a connected device to start emitting real-time log messages over WebSocket. The server captures and stores these messages, which you can then view in the CMS.

See the full guide: [Debug Logging](/melody/wifi/debug_logging)

***

## Recommended Usage Patterns

* **Show user-facing status** from: `batteryLevel`, `batteryVoltage`, `temperatureSensor*`, `wifiConnected`, `bleConnected`.
* **Offer configuration UI** for: `deviceName`, `wifiEnabled`, `bleEnabled`.
* **Gate service commands behind confirmation dialogs** for: `startCalibration`, `startOta`, `powerDown`.
* **Use `setCurrentScreen`** to programmatically drive the device UI (e.g. open Settings or WiFi screen from your app).
* **Surface firmware prompts** based on: `firmwareStatus` and `latestFirmwareVersion`.
* **Use debug information** only in internal tools, logs, or support dashboards.
* **Enable debug logging** only during development or support — it is not persisted and does not survive reconnects.

For exact endpoint URLs, request/response schemas, and error codes, see the **WiFi API section in the Melody API Reference**.