Firmware Downloads & Access Keys

TrackLab provides firmware binaries for NCU and TCU devices. Firmware can be downloaded via the REST API, either publicly or with access key authentication.

Download Endpoint

GET /api/v1/firmware/download?firmwareSlug=<slug>

Authentication Methods

Each firmware can be configured to require authentication or allow public downloads.

When tokenRequired is true

Devices must authenticate using one of these methods (in priority order):

Option 1: Bearer Header (recommended)

curl -H "Authorization: Bearer <your-access-key>" \
  "https://api.tracklabsolar.com/api/v1/firmware/download?firmwareSlug=ncu-x100-v2-5-0"

Option 2: Query Parameter

curl "https://api.tracklabsolar.com/api/v1/firmware/download?firmwareSlug=ncu-x100-v2-5-0&token=<your-access-key>"

When tokenRequired is false

No authentication needed:

curl "https://api.tracklabsolar.com/api/v1/firmware/download?firmwareSlug=ncu-x100-v2-5-0"

Response

On success, the endpoint streams the firmware binary with:

• Content-Disposition: attachment; filename="<slug>.bin"
• Content-Length header
• ETag for cache validation

Error Codes

Status	Meaning
200	Firmware binary streamed
400	Missing or invalid firmwareSlug
401	Token required but not provided
403	Invalid or expired access key
404	Firmware not found or disabled
429	Rate limit exceeded

Creating Access Keys

Access keys are managed per-company in the TrackLab admin UI:

1. Navigate to Firmware > Access Keys in the company dashboard
2. Click Create Key and provide a name and optional expiry
3. The secret key is shown once — copy it immediately
4. Assign the key to devices that need firmware access

MQTT Firmware Update Flow

When an admin assigns firmware to a device, TrackLab sends an MQTT command:

{
  "command": "update_firmware",
  "parameters": {
    "firmwareUrl": "https://api.tracklabsolar.com/api/v1/firmware/download?firmwareSlug=ncu-x100-v2-5-0",
    "firmwareHash": "sha256:abc123...",
    "tokenRequired": true
  }
}

Device-Side Integration

When your device receives the update_firmware command:

1. Check tokenRequired — if true, the device must attach its pre-provisioned access key
2. Download the firmware:
   • If tokenRequired is true: GET firmwareUrl with Authorization: Bearer <key> header
   • If tokenRequired is false: GET firmwareUrl directly
3. Verify firmwareHash — compute SHA-256 of the downloaded binary and compare
4. Install the firmware if hash matches

caution

Access keys are never included in the MQTT message. Devices must have their keys provisioned out-of-band before receiving firmware update commands.

Admin: Managing Token Requirements

Super admins can toggle whether each firmware requires authentication:

1. Navigate to SA > Firmware in the admin dashboard
2. Click Details on any firmware
3. Toggle Token required on or off
4. The download snippet below the toggle updates to show the correct auth method

When toggled off, the firmware becomes publicly downloadable (rate-limited by IP).