> ## Documentation Index > Fetch the complete documentation index at: https://docs.bota.dev/llms.txt > Use this file to discover all available pages before exploring further. # Device Management > Register devices, configure settings, and remotely control Bota wearables Bota devices are managed through the API. You register devices, bind them to end users, configure connection and upload behavior, and send remote commands — all from your server. ## Device Lifecycle ```mermaid theme={null} stateDiagram-v2 [*] --> Registered: Register device Registered --> Bound: Bind to end user Bound --> Registered: Unbind Bound --> Active: Heartbeat received Active --> Bound: Idle timeout ``` 1. **Register** — Provision a device with its serial number. The device is created in an unbound state and the response returns its Bota device ID (`dev_*`). 2. **Bind** — Assign the device to an end user. This returns a `device_token` (`dtok_*`) used for device-side authentication (WiFi/4G uploads, heartbeats). 3. **Heartbeat** — The device periodically reports battery level, storage usage, and signal strength. 4. **Unbind** — Release the device from its current end user, revoking the device token. See the [Devices API reference](/api-reference/devices/create) for implementation details. Save the `dev_*` ID returned during registration with the physical serial number. If you only have a serial number later, use `GET /v1/devices?serial_number={SN}` to resolve a device visible to the authenticated project. ## Device ID and Reconnect Mobile reconnect and backend device lookup use different identifiers: * Bluetooth reconnect uses the physical serial number, plus SDK-cached BLE identity such as the peripheral ID or advertised MAC address. * Bota API calls use the Bota device ID (`dev_*`) returned by registration. For mobile apps, persist a local mapping of `serial_number -> dev_*` after pairing/registering the device. On app startup, reconnect to the physical device by serial number through the mobile SDK, then use the stored `dev_*` for API calls such as binding, commands, heartbeats, settings, WiFi grants, and OTA. If the mapping is missing, recover it with the project-scoped `serial_number` list filter. If device registration returns `409 Conflict`, query `GET /v1/devices?serial_number={SN}`. Reuse the returned `dev_*` ID when the result contains a device. An empty result means the device belongs elsewhere or is otherwise inaccessible; the API deliberately does not distinguish those cases. ## Device Settings Device behavior is configured through two setting groups: **connection** and **upload**. Settings are deep-merged — you only need to send the fields you want to change. ### Connection Settings Control which radios are enabled and the preferred upload path. | Setting | Description | Default | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | **Enabled connections** | Toggle WiFi and cellular radios. Bluetooth is always on. | Both enabled | | **Upload network preference** | Ordered priority list (`wifi`, `Bluetooth`, `cellular`). Device tries each in order. | `wifi → Bluetooth → cellular` | | **Power management** | Idle timeout before powering down WiFi/cellular radio. `-1` = never power down, `0` = power down immediately after work completes, positive values wait before power-down. Range: `-1`, `0`, or 10–2540 seconds. | 180s (3 min) | ### Upload Settings Control how and when recordings are uploaded. | Setting | Description | Default | | ------------------------ | ----------------------------------------------------------------------- | --------- | | **Streaming enabled** | Upload chunks while recording instead of waiting until complete | `false` | | **Streaming chunk size** | Chunk size for streaming uploads (64–1024 KB) | 256 KB | | **Daily data limit** | Max cellular data per day in MB. `0` = unlimited. | Unlimited | | **Allow roaming** | Allow cellular uploads when roaming | `false` | | **Pause on low battery** | Pause uploads when battery is low | `true` | | **Off-peak hours** | Schedule uploads during specific hours only (start/end time + timezone) | Disabled | ### Common Presets | Use Case | Connection | Upload | | ------------------ | ------------------------------------------- | -------------------------------- | | **Travel Mode** | WiFi only, no cellular | Roaming disabled | | **Battery Saver** | Short radio idle timeouts (30s) | Pause on low battery | | **Real-time** | All connections enabled, cellular preferred | Streaming enabled, no data limit | | **Cost-conscious** | WiFi + Bluetooth only | Off-peak uploads, daily data cap | See [Update Device](/api-reference/devices/update) for the full settings schema. ## Remote Commands Send commands to devices in the field. Commands are delivered when the device next checks in and expire after a configurable TTL. ### Supported Commands | Command | Description | | ----------------- | ------------------------------------------------ | | `start_recording` | Start a new recording with optional max duration | | `stop_recording` | Stop the current recording | ### Command Lifecycle ```mermaid theme={null} stateDiagram-v2 [*] --> pending: Command created pending --> delivered: Device received pending --> expired: TTL exceeded pending --> cancelled: Cancelled delivered --> executed: Device completed delivered --> failed: Device error ``` * **TTL** — Commands expire after a configurable timeout (default: 5 minutes, max: 1 hour). Expired commands are never executed. * **Cancellation** — Only pending commands can be cancelled. See [Create Command](/api-reference/devices/create-command) for the API reference. ## WiFi Configuration Device WiFi credentials are configured securely through a grant flow: 1. Your server requests a time-limited grant from the API 2. The grant blob is passed to the mobile app 3. The mobile app sends it to the device over BLE 4. The device connects to the configured WiFi network This ensures WiFi credentials are encrypted end-to-end and never stored in the Bota backend. See [WiFi Config Grant](/api-reference/devices/wifi-config-grant). ## Heartbeat Devices periodically report their status to the backend via heartbeat. This enables real-time monitoring, webhook alerts (`device.low_battery`, `device.offline`), and remote command delivery. ### How It Works The device sends a heartbeat every 60 seconds over the best available connection. Heartbeat uses a fixed priority: **BLE > WiFi > 4G**. | Connection | Behavior | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **BLE connected** | The mobile app reads device status over Bluetooth and relays it to the backend. The device's direct heartbeat (WiFi/4G) is **paused** to save battery. | | **BLE disconnected, WiFi available** | Device sends heartbeat directly over WiFi. | | **BLE disconnected, no WiFi** | Device sends heartbeat directly over 4G. | When Bluetooth is connected and relaying heartbeats, the device's WiFi and 4G radios can power down via idle timers — maximizing battery life. ### Heartbeat Payload Each heartbeat reports: | Field | Type | Description | | --------------------- | ------- | ----------------------------------------------- | | `battery_percent` | integer | Battery level (0–100) | | `storage_used_mb` | integer | Used storage in MB | | `storage_total_mb` | integer | Total storage in MB | | `pending_recordings` | integer | Recordings awaiting upload | | `device_state` | string | Current state: `idle`, `recording`, `uploading` | | `firmware_version` | string | Current firmware version | | `signal_strength_dbm` | integer | WiFi or cellular signal strength | | `connection_type` | array | Active connections (e.g., `["wifi", "ble"]`) | ### Command Delivery Remote commands are delivered via heartbeat responses. When a device checks in, the backend includes any pending commands: ```json theme={null} { "status": "ok", "server_time": "2025-01-15T10:30:00Z", "pending_commands": [ { "id": "cmd_abc123", "type": "start_recording", "params": { "max_duration_ms": 300000 } } ] } ``` The device processes the command and acknowledges it. See [Remote Commands](#remote-commands) for details. ### Power Management Interaction Each heartbeat resets the idle timer of whichever radio it uses. When heartbeats switch to a different radio (e.g., Bluetooth connects and the device pauses direct heartbeats), the unused radio's idle timer runs down and the radio powers off automatically. See [Connectivity](/guides/connectivity) for full details on radio power management and failover. ## Monitoring ### Device State Use the [Get Device State](/api-reference/devices/get-state) endpoint to retrieve the latest telemetry snapshot, or the recording's `media` array for individual recordings. The dashboard shows aggregate fleet health. ### Fleet Overview List all devices with an optional end-user filter. To find a device by serial number, use the exact, project-scoped `serial_number` filter. See [List Devices](/api-reference/devices/list). ## Related * [Devices API](/api-reference/devices/create) — Full API reference * [Cellular Mode](/guides/cellular-mode) — Autonomous 4G operation * [Streaming Upload](/guides/streaming-upload) — Upload while recording * [Hardware: Bota Pin](/hardware/pin) — Pin specifications * [Hardware: Bota Pin Pro](/hardware/pin-pro) — Pin Pro (multi-modal) specifications * [Hardware: Bota Note](/hardware/note) — Note specifications