The platform allows users to control firmware and configuration updates on their devices through a folder system.

There are two types of folders–firmware and configuration–which hold files of the matching type. Folders (not files) are assigned to individual devices, one of each kind of folder maximum.

How Updates Work

Each folder can have one and only one of its contained files marked as 'active.' Every time the device connects to the server (over TCP), it reports the name of the firmware and configuration that it is running. The system compares this name to the active file in the device's assigned firmware and configuration folders. If there is a mismatch, the device will be told to update to the active file.

With this system, many devices can be updated with a single change in the selection of the active file.

See Our API Documentation for More Information

The complete list of methods used to manage firmware and configuration is available in our API documentation.

This tutorial shows you how to:

Create a configuration folder.
Upload a configuration file to that folder.
Set a file as 'active.'
Link a configuration folder to one or more devices.

Create a Configuration Folder

[POST] https://management-api-us-east-1-production.hub.bitbrew.com/v1/tenants/{tenantId}/configurationFolders

Parameters: tenant ID
Request type: application/json

When creating a firmware folder, the only information you need to submit is the name of the folder.

Request Example - JSON

{
    "name": "test-configs"
}

Since your newly created folder is empty, there is no active file.

Response Example - JSON

{
  "name": "test-configs",
  "modifiedAt": "2018-10-10T17:48:52.702Z",
  "numberOfContainedFiles": 0,
  "activeFileName": null
}

Upload a Configuration File to a Folder

[POST] https://management-api-us-east-1-production.hub.bitbrew.com/v1/tenants/{tenantId}/configurationFolders/{folderName}/files

Parameters: tenant ID, configuration folder name
Request type: application/json

File Names Must Match What the Device Will Report!

When you upload a file to a folder, you must ensure that the external name exactly matches the string that the device will report when it is running that firmware or configuration. Any mismatch, even in capitalization, will cause the system to see the device as out of date and command it to update.

Request Example - Form Data

-----CONTENTS
Content-Disposition: form-data; name="name"; filename="009234A1"
Content-Type: contenttype
Content-Transfer-Encoding: base64file contents here (base64-encoded bytes)
-----CONTENTS

Set a Configuration File as Active

[PUT] https://management-api-us-east-1-production.hub.bitbrew.com/v1/tenants/{tenantId}/configurationFolders/{folderName}

Parameters: tenant ID, configuration folder name
Request type: application/json

The name of the active file is a setting of the folder, so setting a file as active is accomplished by updating the folder attribute.

Request Example - JSON

{
  "activeFileName": "009234A1"
}

Assign a Configuration Folder to a Device

[POST] https://management-api-us-east-1-production.hub.bitbrew.com/v1/tenants/{tenantId}/configurationFolders/{folderName}/devices

Parameters: tenant ID, configuration folder name
Request type: application/json

To assign a folder to a set of devices, you must submit a list of device IDs to be linked to the folder. The request body is outlined below.

Request Example - JSON

{
  "deviceIds": ["6051181915", 6051181918"]
}

Explanation of Fields

deviceIds (array[strings], required) – The serial numbers (printed on the back of each Danlaw device) to be linked to the folder.

Firmware Management Works the Same Way

Firmware file management works the exact same as configuration, except that the endpoints say firmware instead of configuration.