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

BasicAuth

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

401

Unauthorized - Invalid or missing device token, or expired/invalid download key

application/octet-stream

403

Forbidden - Download key does not match device ID (attempting to download another device's file)

application/octet-stream

404

File not found - File may have been deleted or moved

application/octet-stream

get

/v2/device/download

HTTPcURLJavaScriptPython

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

BearerAuth

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

application/json

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

400

Invalid request body - Check command type and required data fields

application/json

401

Unauthorized - Invalid or missing API key

application/json

403

Forbidden - Command not in device's allowed_commands list or missing 'send-commands' scope

application/json

404

Device not found or device does not support commands (HTTP-only devices)

application/json

post

/v2/projects/{project_id}/devices/{device_id}/communication/command

HTTPcURLJavaScriptPython

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

BearerAuth

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

400

Invalid parameters - type must be 'firmware' or 'logo'

application/json

401

Unauthorized - Invalid or missing API key

application/json

get

/v2/projects/{project_id}/files

HTTPcURLJavaScriptPython

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"
    }
  ]
}