Device Firmware Upgrade (dfu)#
These commands and events are related to controlling firmware update over the configured host interface and are available only when the device has been booted into DFU mode.
The DFU process:
Boot device to DFU mode with DFU reset command
Wait for DFU boot event
Send command Flash Set Address to start the firmware update
Upload the firmware with Flash Upload commands until all the data has been uploaded
Send Flash Upload Finish when all the data has been uploaded
Finalize the DFU firmware update with Reset command.
DFU mode is using UART baudrate from hardware configuration of firmware. Default baudrate 115200 is used if firmware is missing or firmware content does not match with CRC checksum.
Commands#
dfu_flash_set_address#
After re-booting the local device into DFU mode, this command can be used to define the starting address on the flash to where the new firmware will be written in.
Command#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0x20 | hilen | Message type: Command |
1 | 0x04 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x01 | method | Message ID |
4-7 | uint32 | address | The offset in the flash where the new firmware is uploaded to. Always use the value 0x00000000. |
Response#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0x20 | hilen | Message type: Response |
1 | 0x02 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x01 | method | Message ID |
4-5 | uint16 | result | Result code:
For other values refer to the Error codes |
API#
/* Function */
struct gecko_msg_dfu_flash_set_address_rsp_t *gecko_cmd_dfu_flash_set_address(uint32 address);
/* Response id */
gecko_rsp_dfu_flash_set_address_id
/* Response structure */
struct gecko_msg_dfu_flash_set_address_rsp_t
{
uint16 result
}dfu_flash_upload#
This command can be used to upload the whole firmware image file into the Bluetooth device. The passed data length must be a multiple of 4 bytes. As the BGAPI command payload size is limited, multiple commands need to be issued one after the other until the whole .bin firmware image file is uploaded to the device. The next address of the flash sector in memory to write to is automatically updated by the bootloader after each individual command.
Command#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0x20 | hilen | Message type: Command |
1 | 0x01 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x02 | method | Message ID |
4 | uint8array | data | An array of data which will be written onto the flash. |
Response#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0x20 | hilen | Message type: Response |
1 | 0x02 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x02 | method | Message ID |
4-5 | uint16 | result | Result code:
For other values refer to the Error codes |
API#
/* Function */
struct gecko_msg_dfu_flash_upload_rsp_t *gecko_cmd_dfu_flash_upload(uint8 data_len, const uint8 *data_data);
/* Response id */
gecko_rsp_dfu_flash_upload_id
/* Response structure */
struct gecko_msg_dfu_flash_upload_rsp_t
{
uint16 result
}dfu_flash_upload_finish#
This command can be used to tell to the device that the DFU file has been fully uploaded. To return the device back to normal mode the command DFU Reset must be issued next.
Command#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0x20 | hilen | Message type: Command |
1 | 0x00 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x03 | method | Message ID |
Response#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0x20 | hilen | Message type: Response |
1 | 0x02 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x03 | method | Message ID |
4-5 | uint16 | result | Result code:
For other values refer to the Error codes |
API#
/* Function */
struct gecko_msg_dfu_flash_upload_finish_rsp_t *gecko_cmd_dfu_flash_upload_finish();
/* Response id */
gecko_rsp_dfu_flash_upload_finish_id
/* Response structure */
struct gecko_msg_dfu_flash_upload_finish_rsp_t
{
uint16 result
}dfu_reset#
This command can be used to reset the system. This command does not have a response, but it triggers one of the boot events (normal reset or boot to DFU mode) after re-boot.
Command#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0x20 | hilen | Message type: Command |
1 | 0x01 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x00 | method | Message ID |
4 | uint8 | dfu | Boot mode:
|
Command does not have response
API#
/* Function */
void *gecko_cmd_dfu_reset(uint8 dfu);
/* Command does not have response */Events generated#
Event | Description |
|---|---|
system_boot | Sent after the device has booted into normal mode |
dfu_boot | Sent after the device has booted into UART DFU mode |
Events#
dfu_boot#
This event indicates that the device booted into DFU mode, and is now ready to receive commands related to device firmware upgade (DFU).
Event#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0xa0 | hilen | Message type: Event |
1 | 0x04 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x00 | method | Message ID |
4-7 | uint32 | version | The version of the bootloader |
API#
/* event id*/
gecko_evt_dfu_boot_id
/* event structure*/
struct gecko_msg_dfu_boot_evt_t
{
uint32 version
}dfu_boot_failure#
This event indicates that there has been error in bootloader, which prevents the device from booting.
Event#
Byte | Type | Name | Description |
|---|---|---|---|
0 | 0xa0 | hilen | Message type: Event |
1 | 0x02 | lolen | Minimum payload length |
2 | 0x00 | class | Message class:Device Firmware Upgrade |
3 | 0x01 | method | Message ID |
4-5 | uint16 | reason | The reason for boot failure, refer to the Error codes |
API#
/* event id*/
gecko_evt_dfu_boot_failure_id
/* event structure*/
struct gecko_msg_dfu_boot_failure_evt_t
{
uint16 reason
}