Firmware Bundles

A "bundle" represents a collection of firmware components (binary files) that will be installed on a device.

Endpoints

The Firmware Info object

  • bundleIdstring

    Unique ID that represents the installed bundle. Must begin with an alphanumeric character; dashes ('-'), underscores ('_') and periods ('.') may be used after the first character but must be followed by 1+ alphanumeric characters.

The Firmware Bundle object

  • creationTimestring| format is date-time

    Timestamp of bundle creation.

  • descriptionstring

    Description of the bundle

  • deviceClassstring

    device class that this bundle belongs to.

  • idstring

    Unique ID assigned at time of creation.

  • namestring

    Display name of bundle.

  • projectIdinteger

    Project that this bundle belongs to.

  • componentsarray

    List of components in this bundle.

The Firmware Bundle object

{
  "creationTime": "2020-01-02T19:52:57.572Z",
  "description": "This is the firmware for all light sensors",
  "deviceClass": "smart_light",
  "id": "5e0e4a19ff1bc0646141d221",
  "name": "light_bundle",
  "projectId": 1,
  "components": [
    {
      "componentId": "5dfc2035ff1bc0646141d1f9",
      "componentName": "component_one",
      "versionId": "5e0e49d8gg1bc0646141d220",
      "versionName": "2.0.0",
      "filename": "firmware_one.go",
      "checksum": "72023f800b694zz02b223c9971fc9febcbef8324",
      "url": "https://download.tinkermode.com/download/v1.eyJzIjoic29mdHdhcEFiLCJrIjoiMTI2MC81ZTBlNDlkOWZmMWJjMDY0NjE0MWQyMjAvMSIsImYiOiJSRUFETUUubWQifQ==.1577994891.d3f79feaee1e229a3d5789eac6d1a089973dbe7c482a15f73ad38a5e"
    },
    {
      "componentId": "5e0e49b4f8379d390de54175",
      "componentName": "component_two",
      "versionId": "5e0e49c5ff1bc0646141d21f",
      "versionName": "1.0.8",
      "filename": "firmware_two.go",
      "checksum": "72023f800b694ee02b223c9971fc9febcbef8324",
      "url": "https://download.tinkermode.com/download/v1.eyJzIjoic29mdFeFcmUiLCJrIjoiMTI2MC81ZTBlNDljNWZmMWJjMDY0NjE0MWQyMWYvMSIsImYiOiJSRUFETUUubWQifQ==.1577994891.ca8fb42459cdf9df17b0780ad60c7ddfe917b745399c430d3ae7f30a"
    }
  ]
}

Get firmware bundles

Endpoint
get /bundles
Description

Get a list of device firmware bundles. This endpoint operates in two modes. Firstly, devices can use this to perform Over-the-air (OTA) updates of their firmware. Secondly, authorized clients can use this to fetch a list of bundles that are available to a specific device class. The identify of the caller determines which of these two modes is used, as explained below.

Request is made with a device API key

The caller is expecting to perform an OTA update. The bundles associated with the device's project and device class are returned. By default, bundles from the "stable" channel are returned, unless the device has a channel override. No query parameters are needed for this request, and any supplied parameters will be ignored.

Request is made with a user session or project API key

The caller is expecting to fetch a list of available bundles for a device class, and the request must come with the projectId and deviceClass query parameters.

Request is made without any authorization header

The caller is expecting to perform an OTA update but has yet to be provisioned a device ID and API Key. This request must come with the projectId and deviceClass query parameters. By default, bundles from the "stable" channel are returned, unless the channel query parameter is used to override that. Request will succeed only if the project has been configured to allow public OTA updates.

In the case of OTA update, each of the returned bundles contains a list of firmware components to be downloaded. A component object contains a versionName field, a url field, and a checksum field. Based on the component version, you should decide whether an upgrade is necessary. To download a component, simply use the URL provided. The checksum is a SHA-1 digest of the component file. You may use it to verify the integrity of the downloaded file.

Query Parameters

  • projectId

    integer

    Return bundles of the specified project.

  • deviceClass

    string

    Return bundles of the specified device class.

  • channel

    string

    Return bundles of the specified channel.

Request Headers What's this?

  • Authorization

    Must contain either a device API key, a user session API key, or a project API key, unless the project allows public OTA firmware updates.

Response
  • 200Successful retrieval of all firmware bundles.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
  {
    "creationTime": "2020-01-02T19:52:57.572Z",
    "description": "This is the firmware for all light sensors",
    "deviceClass": "smart_light",
    "id": "5e0e4a19ff1bc0646141d221",
    "name": "light_bundle",
    "projectId": 1,
    "components": [
      {
        "componentId": "5dfc2035ff1bc0646141d1f9",
        "componentName": "component_one",
        "versionId": "5e0e49d8gg1bc0646141d220",
        "versionName": "2.0.0",
        "filename": "firmware_one.go",
        "checksum": "72023f800b694zz02b223c9971fc9febcbef8324",
        "url": "https://download.tinkermode.com/download/v1.eyJzIjoic29mdHdhcEFiLCJrIjoiMTI2MC81ZTBlNDlkOWZmMWJjMDY0NjE0MWQyMjAvMSIsImYiOiJSRUFETUUubWQifQ==.1577994891.d3f79feaee1e229a3d5789eac6d1a089973dbe7c482a15f73ad38a5e"
      },
      {
        "componentId": "5e0e49b4f8379d390de54175",
        "componentName": "component_two",
        "versionId": "5e0e49c5ff1bc0646141d21f",
        "versionName": "1.0.8",
        "filename": "firmware_two.go",
        "checksum": "72023f800b694ee02b223c9971fc9febcbef8324",
        "url": "https://download.tinkermode.com/download/v1.eyJzIjoic29mdFeFcmUiLCJrIjoiMTI2MC81ZTBlNDljNWZmMWJjMDY0NjE0MWQyMWYvMSIsImYiOiJSRUFETUUubWQifQ==.1577994891.ca8fb42459cdf9df17b0780ad60c7ddfe917b745399c430d3ae7f30a"
      }
    ]
  }
]