Firmwares¶

GET/api/v1/Firmwares

GET/api/v1/Firmwares/{id}

POST/api/v1/Firmwares/{id}/Package

List Available Firmware Versions¶

GET/api/v1/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/api/v1/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/api/v1/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…"
}