0xD801 - Load Firmware File

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

Host composes and sends request

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

Device acknowledges receipt

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

Device validates and authenticates

The device validates the request and authenticates the firmware file with the algorithm specified in the firmware file payload.

5

Commit / Notifications

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.

Commit Firmware Notification Detail Codes are used for auto-commit mode. In both cases, the device automatically resets.

Table LFF-1 - Request Data for Command 0xD801 - Load Firmware File

Tag	Len	Value / Description	Typ	Req	Default
Beginning of any wrappers, at minimum including Request 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	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

Table LFF-2 - Response Data for Command 0xD801 - Load Firmware File

Tag	Len	Value / Description	Typ	Req	Default
Beginning of any wrappers, at minimum including Response Message
D801 = Load Firmware File - Command 0xD801
No parameters.
End of any wrappers, at minimum including Response Message

Response Example

Example (Hex):

AA 00 81 04 82 01 D8 01 82 04 80 02 03 16

If the request started successfully, the Request Status in the message wrapper is OK, Started / Running, All good / requested operation was successful.

---

Request Example

Example (Hex):

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.

---

Response Example

Example (Hex):

AA 00 81 04 82 01 D8 01 82 04 00 00 00 00

Request Data for Command 0xD801 - Load Firmware File

Tag	Len	Value / Description	Typ	Req	Default
Beginning of any wrappers, at minimum including Request 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