SupportLog inSign Up

Device Communication

Download device file

get

⚠️ ENTERPRISE FEATURE: Device Communication capabilities, including sending commands and managing firmware/logo files, are exclusive to Enterprise plans and require manual activation by the Qubitro team. This feature is not available by default and must be explicitly enabled for your organization.

To enable this feature: Contact Qubitro support at [email protected] or reach out to your account manager to discuss Enterprise plan options and feature activation.

Device-only endpoint: Downloads a file (firmware or logo) using a time-limited download key. This endpoint is called by devices after receiving a download_firmware or download_logo command.

How It Works:

  1. User sends download_firmware or download_logo command to device (via /communication/command endpoint)

  2. System generates a time-limited download key (30-minute expiry)

  3. Device receives MQTT message with download URL: https://api.qubitro.com/v2/device/download?key=xxx

  4. Device calls this endpoint with the key to download the file

  5. Key is validated and file is served (key expires after use or 30 minutes)

Authentication: This endpoint requires device authentication (not user API key):

  • Header: Authorization: Basic {device_token}

  • Device token is the device's MQTT password / HTTP token

  • Query parameter: key (download key received in command message)

Security:

  • Download key is one-time use or expires after 30 minutes (whichever comes first)

  • Key is tied to a specific device ID (cannot be used by other devices)

  • Device token validation ensures only the intended device can download

  • File is temporarily cached and deleted after download

Supported File Types:

Type
Extensions
Use Case

Firmware

.bin, .hex, .elf

OTA firmware updates

Logo

.png, .jpg, .bmp

Device display images (e-ink, LCD)

Response:

  • Content-Type: application/octet-stream

  • Content-Disposition: attachment; filename={file_name}

  • Content-Length: File size in bytes

  • Binary file data

Timeout: 15-minute timeout to support slow/cellular devices with large firmware files.

Note: This endpoint is designed for device-to-server communication, not for users. Users should download files via the Qubitro web portal or use the /files endpoint to list available files.

Authorizations
Query parameters
keystringRequired

Time-limited download key (received in MQTT command message)

Example: dk_abc123xyz
Responses
200

File downloaded successfully - Binary data with Content-Disposition header

application/octet-stream
Responsestring · binary
get
/v2/device/download
GET /v2/device/download?key=text HTTP/1.1
Host: api.qubitro.com
Accept: */*

binary

Send command to device

post

⚠️ ENTERPRISE FEATURE: Device Communication capabilities, including sending commands and managing firmware/logo files, are exclusive to Enterprise plans and require manual activation by the Qubitro team. This feature is not available by default and must be explicitly enabled for your organization.

To enable this feature: Contact Qubitro support at [email protected] or reach out to your account manager to discuss Enterprise plan options and feature activation.

Sends a downlink command to a device via MQTT with QoS 2 (exactly-once delivery). Commands are delivered to the device control topic and can trigger configuration updates, firmware downloads, reboots, or custom actions.

Supported Commands:

Command
Purpose
Required Data Fields
Example

configuration

Send full configuration to device

Any config object

{"sampling_rate": 60, "threshold": 30}

send_configuration

Request device to send current config

keys: array of config keys (optional)

{"keys": ["sampling_rate", "threshold"]}

download_firmware

OTA firmware update

file_name: firmware filename

{"file_name": "firmware_v2.1.0.bin"}

download_logo

Update device display logo

file_name: logo filename

{"file_name": "logo.png"}

reboot

Reboot device

None (empty object)

{}

reset

Factory reset device

None (empty object)

{}

Custom

Device-specific commands

Device-defined

Varies by device

Command Delivery Protocol:

  • Protocol: MQTT with QoS 2 (exactly-once delivery, no duplicates)

  • Topic: {device_id}/control/{command} (e.g., dev-123/control/configuration)

  • Response Topic: {device_id}/control/{command}/result (optional device acknowledgment)

  • Expiry: 30 minutes for download URLs (firmware/logo)

  • Retain: false (not stored on MQTT broker)

Allowed Commands: Devices can restrict which commands they accept via the allowed_commands field in device metadata:

  • Empty list: All commands allowed (default)

  • Defined list: Only listed commands allowed (semicolon-separated: "configuration;reboot;reset")

  • Unknown commands: Rejected with 403 Forbidden

File Download Flow (firmware/logo):

  1. Upload file to Qubitro storage (via Portal or API)

  2. Send download_firmware or download_logo command with file_name

  3. System generates time-limited download key (30 min expiry)

  4. MQTT message includes download URL: {"url": "https://api.qubitro.com/v2/device/download?key=xxx", "expires_at": "2024-01-15T11:00:00Z"}

  5. Device downloads file using provided URL and key

  6. Key is validated and expires after 30 minutes or first use

Prerequisites:

  • Device must support MQTT, Intemo WiFi, or Intemo Cellular (HTTP-only devices not supported)

  • For firmware/logo downloads: File must exist in project storage (upload via Portal first)

  • Must have send-commands scope permission

Example Request - Configuration Update:

{
"command": "configuration",
"data": {
"sampling_rate": 60,
"threshold_high": 30,
"threshold_low": 10,
"reporting_interval": 300
}
}

Example Request - Firmware Update:

{
"command": "download_firmware",
"data": {
"file_name": "firmware_v2.1.0.bin"
}
}

Success Response:

{
"success": true,
"message": "Command sent successfully",
"action": "send command"
}
Authorizations
AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters
project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7
device_idstringRequired

Device ID (UUID format)

Example: dev-abc123
Body
commandstringOptional

Command type: "configuration", "send_configuration", "download_firmware", "download_logo", "reboot", "reset", or custom commands

Example: configuration
Responses
200

Command sent successfully to MQTT broker - Device will receive via QoS 2

application/json
post
/v2/projects/{project_id}/devices/{device_id}/communication/command
POST /v2/projects/{project_id}/devices/{device_id}/communication/command HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "command": "configuration",
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "action": "delete device",
  "message": "Operation completed successfully",
  "success": true
}

List device files

get

⚠️ ENTERPRISE FEATURE: Device Communication capabilities, including sending commands and managing firmware/logo files, are exclusive to Enterprise plans and require manual activation by the Qubitro team. This feature is not available by default and must be explicitly enabled for your organization.

To enable this feature: Contact Qubitro support at [email protected] or reach out to your account manager to discuss Enterprise plan options and feature activation.

Retrieves a list of all firmware or logo files uploaded for device communication (OTA updates, display images). Files can be filtered by project or listed organization-wide.

What are Device Files? Files stored in Qubitro for device communication purposes:

  • Firmware files: Binary files for OTA (Over-The-Air) firmware updates

  • Logo/image files: Images for device displays (e-ink, LCD screens)

Supported File Types:

Type
Extensions
Use Case
Upload Method

firmware

.bin, .hex, .elf

OTA firmware updates

Qubitro Portal → Project → Files

logo

.png, .jpg, .bmp

Device display images

Qubitro Portal → Project → Files

Query Parameter:

  • type: Required - Filter by file type ("firmware" or "logo")

Alternative Route: This endpoint is also available at /v2/files?type={type} for listing files across all projects in your organization (without project_id filter).

File Information Returned:

  • name - File name (e.g., firmware_v2.1.0.bin)

  • description - Optional description set during upload

  • time - Upload timestamp (ISO 8601 format, UTC)

  • size - File size in bytes

Use Cases:

  • List available firmware before sending OTA update command

  • Verify file upload after uploading via Portal

  • Audit file inventory across projects

  • API integration to programmatically manage device files

Sending Files to Devices: After listing files, use the SendCommand endpoint with:

  • Command: download_firmware (for firmware files)

  • Command: download_logo (for logo files)

  • Data: {"file_name": "{name from this list}"}

Note: Files must be uploaded via the Qubitro web portal first. This API only lists existing files (upload via API not yet supported).

Authorizations
AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters
project_idstringRequired

Project ID (UUID format) - Filters files to this project only

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7
Query parameters
typestringRequired

File type filter: 'firmware' or 'logo'

Example: firmware
Responses
200

Array of file objects with name, description, size, and upload time

application/json
get
/v2/projects/{project_id}/files
GET /v2/projects/{project_id}/files?type=text HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "files": [
    {
      "description": "Production firmware",
      "name": "firmware_v2.1.0.bin",
      "size": 524288,
      "time": "2024-01-15T10:30:00Z"
    }
  ]
}
PreviousDashboardsNextOrganization

Last updated