The host uses this command to send a firmware image file, signed by MagTek, to the device as the first step in updating firmware. If the battery charge is five percent or less, a response is returned indicating that the command has not been executed. See Response Example for Command 0xD801.
If the battery charge is 5% or lower, the device will not allow the Load Firmware File command to execute and returns a response indicating the command was not executed.
The sequence of events is as follows:
1
Host obtains firmware image
The host is assumed to have access to a binary file containing a firmware image signed by MagTek, which contains a complete instance of Firmware File Type.
2
The host composes a command request using the binary file as the Payload, and sends it to the device in the format described below.
3
The device sends a response to the host to acknowledge it has received the request. The device will not allow the Load Firmware File command to execute if the battery charge is 5 percent or lower.
4
The device validates the request and authenticates the firmware file with the algorithm specified in the firmware file payload.
5
If the upload was not successful, then go to the next step. If the upload was successful and auto-commit was disabled, then go to the next step. Else, the device will commit the image automatically.
If commit was successful, the device sends Notification 0x0905 - Firmware Update Successful to the host.
If commit was unsuccessful, the device sends Notification 0x0906 - Firmware Update Failed to the host.
Tag
Len
Value / Description
Typ
Req
Default
Tag
Len
Value / Description
Typ
Req
Default
Example (Hex):
Example (Hex):
Example (Hex):
Tag
Len
Value / Description
Typ
Req
Default
Commit Firmware Notification Detail Codes are used for auto-commit mode. In both cases, the device automatically resets.
D801 =Load Firmware File - Command 0xD801
81
01
Progress Indicator Reserved for future use. Populate with 0x03.
B
R
85
02
Image Type
- 0x0000 = Boot Loader 1 image
- 0x0001 = Main App image
- 0x0002 = WiFi Module image
- 0x0003 = BLE Module image
B
R
86
20
Hash Checksum
B
R/O
87
var
Payload
B
R
88
01
Load Options
0x00 = Default mode
0x01 = Auto Commit
B
O
0x00
End of any wrappers, at minimum including Request Message
D801 = Load Firmware File - Command 0xD801
No parameters.
End of any wrappers, at minimum including Response Message
D801 = Load Firmware File - Command 0xD801
81
01
Progress Indicator Reserved for future use. Populate with 0x03.
B
R
85
02
Image Type
- 0x0000 = Boot Loader 1 image
- 0x0001 = Main App image
- 0x0002 = WiFi Module image
- 0x0003 = BLE Module image
B
R
86
20
Hash Checksum This is a SHA-256 hash of the entire object Firmware File Type being uploaded. For backward compatibility, this TLV is required in Default Mode, it is Optional in Auto-Commit Mode.
B
R/O
87
var
Payload This is the binary file or Firmware File Type object being loaded into the device.
B
R
88
01
Load Options 0x00 = Default mode 0x01 = Auto Commit
B
O
0x00
End of any wrappers, at minimum including Request Message
Beginning of any wrappers, at minimum including Request Message
Beginning of any wrappers, at minimum including Response Message
Beginning of any wrappers, at minimum including Request Message
Host composes and sends request
Device acknowledges receipt
Device validates and authenticates
Commit / Notifications
Table LFF-1 - Request Data for Command 0xD801 - Load Firmware File
Table LFF-2 - Response Data for Command 0xD801 - Load Firmware File
Table LFF-2- Response Example for Command 0xD801 Battery Charge State
If the request started successfully, the Request Status in the message wrapper is OK, Started / Running, All good / requested operation was successful.
Table LFF-3 - Request Example
Table LFF-4 - Response Example
Table LFF-5 - Request Data for Command 0xD801 - Load Firmware File
AA 00 81 04 82 01 D8 01 82 04 80 02 03 16
AA 00 81 04 01 01 D8 01 84 83 0C 76 58 D8 01 81 01 03 85 02 00 01 86 20 DF C7 1E 09 A3 CE 8E 86 B0 F5 B6 75 BE B7 7A 0E 82 33 BF F1 8A CD 8F 38 34 B0 DB 20 D9 40 4B 28 87 83 0C 76 28
Plus 0C7628 bytes of firmware Payload, excluded here for brevity.