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.
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
- Register — Provision a device with its serial number. The device is created in an unbound state.
- Bind — Assign the device to an end user. This returns a
device_token (dtok_*) used for device-side authentication (WiFi/4G uploads, heartbeats).
- Heartbeat — The device periodically reports battery level, storage usage, and signal strength.
- Unbind — Release the device from its current end user, revoking the device token.
See the Devices API reference for implementation details.
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. BLE is always on. | Both enabled |
| Upload network preference | Ordered priority list (wifi, ble, cellular). Device tries each in order. | wifi → ble → cellular |
| Power management | Idle timeout before powering down WiFi/cellular radio. 0 = always on. Range: 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 + BLE only | Off-peak uploads, daily data cap |
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
- 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 for the API reference.
WiFi Configuration
Device WiFi credentials are configured securely through a grant flow:
- Your server requests a time-limited grant from the API
- The grant blob is passed to the mobile app
- The mobile app sends it to the device over BLE
- 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.
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 BLE 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. |
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:
{
"status": "ok",
"server_time": "2025-01-15T10:30:00Z",
"pending_commands": [
{ "id": "cmd_abc123", "type": "start_recording", "params": { "max_duration_ms": 300000 } }
]
}
Power Management Interaction
Each heartbeat resets the idle timer of whichever radio it uses. When heartbeats switch to a different radio (e.g., BLE connects and the device pauses direct heartbeats), the unused radio’s idle timer runs down and the radio powers off automatically.
See Connectivity for full details on radio power management and failover.
Monitoring
Device State
Use the Get Device 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 optional filters by status or end user. See List Devices.
