Device Management

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 and the response returns its Bota device ID (dev_*).
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.

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 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

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 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:

{
  "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., Bluetooth 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 an optional end-user filter. To find a device by serial number, use the exact, project-scoped serial_number filter. See List Devices.

Devices API — Full API reference
Cellular Mode — Autonomous 4G operation
Streaming Upload — Upload while recording
Hardware: Bota Pin — Pin specifications
Hardware: Bota Pin Pro — Pin Pro (multi-modal) specifications
Hardware: Bota Note — Note specifications

​Device Lifecycle

​Device ID and Reconnect

​Device Settings

​Connection Settings

​Upload Settings

​Common Presets

​Remote Commands

​Supported Commands

​Command Lifecycle

​WiFi Configuration

​Heartbeat

​How It Works

​Heartbeat Payload

​Command Delivery

​Power Management Interaction

​Monitoring

​Device State

​Fleet Overview

​Related

Device Lifecycle

Device ID and Reconnect

Device Settings

Connection Settings

Upload Settings

Common Presets

Remote Commands

Supported Commands

Command Lifecycle

WiFi Configuration

Heartbeat

How It Works

Heartbeat Payload

Command Delivery

Power Management Interaction

Monitoring

Device State

Fleet Overview

Related