5.2.1 api firmware

The api/firmware function uploads the firmware file for upgrade/downgrade.

Methods

  • PUT

Services and Privileges

  • Services: System API

  • Privileges: System Control


Request PUT

The request contains a file in multipart/form-data.

Table 1. Request Parameters
ParameterMandatoryExpected ValuesDefault ValueDescription

blob-fw

Yes

Valid firmware binary file

-

Firmware file


Example of a PUT Request

http://192.168.1.1/api/firmware

Response to PUT

The response is in the application/json format. The response contains the success and result keys. The result value contains various keys described in the table below.


Table 2. Response JSON Keys
KeyTypical Returned ValuesDescription

fileId

Random identifier (8 HEX characters)

Contains a random identifier of the uploaded firmware file. The identifier must be used to confirm the uploaded firmware using api/firmware/apply or to reject the uploaded firmware using api/firmware/reject.

version

String with version identification major.minor.patch.build.id

Contains version identification of the uploaded firmware file.

downgrade

true or false

This flag is true if the uploaded firmware has a lower version than the current firmware in the device.

note

String with escaped characters

Contains an upgrade message for the uploaded firmware (e.g. warning about major changes).

Example of a Response to PUT

{ "success" : true, "result" : { "fileId" : "7d6adf16", "version" : "2.32.4.41.2", "downgrade" : false, "note" : "EN:\r\nVER=2.20.0\r\nSome changes associated with the downgrade to a lower version result in a loss of original settings in a certain part of configuration.\r\n\r\n* All the cards installed in the **Directory \/ Access cards** menu are moved to the **Directory \/ Users** menu as new users upon firmware upgrade. Each user is automatically named as !Visitor #n, where n gives the user number in the list. This change is irreversible upon downgrade.\r\n* Service cards are now available in the **Hardware \/ Card reader** menu.\r\n* All the user access ... ... ... \u043F\u0440\u043E\u0444\u0438\u043B\u0435\u043C \u043F\u043E\u043B\u044C\u0437\u043E\u0432\u0430\u0442\u0435\u043B\u044F.\r\n\r\n" } }

The following specific error codes may be returned:

  • Error code 12

    • param = "blob-fw"

    • description = "invalid parameter value"

    • The uploaded firmware file does not match the requirements (invalid file, firmware for a different device…)

  • Error code 19

    • description = "file version is lower than the required minimum"

    • The uploaded firmware file has a lower version than the minimum version allowed for the device.


Note

The device does not reply to requests to upload another firmware version when the previous firmware file is present. Use api/firmware/reject to reject the previous firmware first and then upload another firmware version. The uploaded firmware file is automatically rejected in 5 minutes if not applied.