Skip to content

Firmwares

List Available Firmware Versions

GET/Firmwares

Get a list of available firmware versions for a certain lock.

Scope

read:firmwares

Parameters

Tip

The returned list can be filtered using OData query parameters.

Name Type Location Description
manufacturerId string query The manufacturer ID as reported by the target lock's lock type.
fwType string query The firmware type as reported by the target lock.
compatibleFromVersion string query Optional. The firmware version that is currently installed on the target lock, as reported by the lock. If omitted, all firmware versions will be returned, no matter whether they can be installed on top of the version currently installed on the target lock or not.
includePreRelease string query Optional. If true, the operation will also report pre-release firmware versions. If false, only officially released versions are returned. Defaults to false.

Warning

The use of non-production firmware packages (includePreRelease=true) is highly discouraged and limited to development scenarios only. Using non-production firmware may break locks. The use of non-production firmware may be incompatible with future locks.

Info

In case a firmware package which is incompatible with the version currently on the lock is attempted to be installed, the installation will fail and the lock continues to run with the old firmware version.

Response

200 OK
[
  {
    "id": "1",
    "manufacturerId": "1",
    "fwType": "1",
    "versionCode": "4",
    "compatibleFromVersion": "3",
    "downgradeableToVersion": "3",
    "releaseLevel": "300",
    "preReleaseCaption": "",
    "versionName": "1.5.0",
    "buildString": "20190115.abcdefg",
    "releaseDate": "2019-02-01T10:00:00.000Z",
    "releaseNotes": "Release notes for this release."
  },
  {
    "id": "2",
    "manufacturerId": "1",
    "fwType": "1",
    "versionCode": "5",
    "compatibleFromVersion": "3",
    "downgradeableToVersion": "4",
    "releaseLevel": "300",
    "preReleaseCaption": "",
    "versionName": "1.6.0",
    "buildString": "20190525.abcdefg",
    "releaseDate": "2019-06-01T10:00:00.000Z",
    "releaseNotes": "Release notes for this release."
  }
]

The release level (releaseLevel) property specifies the production-readiness of a firmware version. Higher values are closer to production. A typical representation is:

  • 100: Alpha
  • 200: Beta
  • 300: Production

Warning

The use of non-production firmware packages is highly discouraged and limited to development scenarios only. Using non-production firmware may break locks. The use of non-production firmware may be incompatible with future locks.

Get Firmware Version by ID

GET/Firmwares/{id}

Get a specific firmware version.

Scope

read:firmwares

Parameters

Name Type Location Description
id string path The firmware version's ID.

Response

200 OK
{
  "id": "1",
  "manufacturerId": "1",
  "fwType": "1",
  "versionCode": "4",
  "compatibleFromVersion": "3",
  "downgradeableToVersion": "3",
  "releaseLevel": "300",
  "preReleaseCaption": "",
  "versionName": "A",
  "buildString": "123abc",
  "releaseDate": "2019-02-01T10:00:00.000Z",
  "releaseNotes": "Release notes for this release."
}

Build Firmware Package

POST/Firmwares/{id}/Package

Build a firmware package for a given lock. The resulting firmware package can be fed into the Mobile SDK's firmware upgrade function to update the respective lock. The firmware package will be signed and encrypted for the specified lock and can not be reused for other locks.

See the Tapkey Mobile SDK's firmware upgrade functionality for more information on how to update a lock's firmware. More specific, CommandExecutionFacade#upgradeFirmware() on Android and TKMCommandExecutionFacade::upgradeFirmwarePackage() on iOS can be used for this purpose.

Scope

read:firmwares

Parameters

Name Type Location Description
id string path The firmware version's ID.
tlcpLockId string query The TLCP lock ID of the lock. Must be a URL-safe Base64-encoded string.

Response

200 OK
{
  "firmwareInfoId": "1",
  "chunkSize": "123",
  "fileDescriptor": "MDEwMTAw…",
  "firmwareData": "ExMTExMT…"
}