Skip to main content
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

  1. Register — Provision a device with its serial number. The device is created in an unbound state.
  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 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.
SettingDescriptionDefault
Enabled connectionsToggle WiFi and cellular radios. BLE is always on.Both enabled
Upload network preferenceOrdered priority list (wifi, ble, cellular). Device tries each in order.wifi → ble → cellular
Power managementIdle 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.
SettingDescriptionDefault
Streaming enabledUpload chunks while recording instead of waiting until completefalse
Streaming chunk sizeChunk size for streaming uploads (64–1024 KB)256 KB
Daily data limitMax cellular data per day in MB. 0 = unlimited.Unlimited
Allow roamingAllow cellular uploads when roamingfalse
Pause on low batteryPause uploads when battery is lowtrue
Off-peak hoursSchedule uploads during specific hours only (start/end time + timezone)Disabled

​
Common Presets

Use CaseConnectionUpload
Travel ModeWiFi only, no cellularRoaming disabled
Battery SaverShort radio idle timeouts (30s)Pause on low battery
Real-timeAll connections enabled, cellular preferredStreaming enabled, no data limit
Cost-consciousWiFi + BLE onlyOff-peak uploads, daily data cap
See Update Device 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

CommandDescription
start_recordingStart a new recording with optional max duration
stop_recordingStop 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:
  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.

​
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.
ConnectionBehavior
BLE connectedThe 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 availableDevice sends heartbeat directly over WiFi.
BLE disconnected, no WiFiDevice sends heartbeat directly over 4G.
When BLE 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:
FieldTypeDescription
battery_percentintegerBattery level (0–100)
storage_used_mbintegerUsed storage in MB
storage_total_mbintegerTotal storage in MB
pending_recordingsintegerRecordings awaiting upload
device_statestringCurrent state: idle, recording, uploading
firmware_versionstringCurrent firmware version
signal_strength_dbmintegerWiFi or cellular signal strength
connection_typearrayActive 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 } }
  ]
}
The device processes the command and acknowledges it. See 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., 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.