Device Firmware Upgrade (dfu)#

These commands and events are related to controlling firmware updates over the configured host interface and are available only when the device is booted in DFU mode.

DFU process:

  1. Boot device to DFU mode with DFU reset command

  2. Wait for DFU boot event

  3. Send command Flash Set Address to start the firmware update

  4. Upload the firmware with Flash Upload commands until all data is uploaded

  5. Send Flash Upload Finish when all data is uploaded

  6. Finalize 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 the CRC checksum.

dfu commands#

dfu_flash_set_address#

After re-booting the local device in DFU mode, this command defines the starting address on the flash where the new firmware will be written.

C 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;  
}  

Command Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint32

address

The offset in the flash where the new firmware is

uploaded to. Always use the value 0x00000000.

Response Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint16

result

Result code

  • 0: success

  • Non-zero: an error has occurred

For other values see Error codes

dfu_flash_upload#

Upload the whole firmware image file into the Bluetooth device. The passed data length must be a multiple of 4 bytes. Because 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. After each command, the next address of the flash sector in memory to write to is automatically updated by the bootloader.

C 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;  
}  

Command Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint8

data_len

Array length.

uint8array

data_data

An array of data which will be written onto the

flash.

Response Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint16

result

Result code

  • 0: success

  • Non-zero: an error has occurred

For other values see Error codes

dfu_flash_upload_finish#

Inform the device that the DFU file is fully uploaded. To return the device back to normal mode, issue the command DFU Reset .

C 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;  
}  

Command does not have parameters (for BGAPI headers refer to#

link)

Response Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint16

result

Result code

  • 0: success

  • Non-zero: an error has occurred

For other values see Error codes

dfu_reset#

Reset the system. The command does not have a response but it triggers one of the boot events (normal reset or boot to DFU mode) after re-boot.

C API#

/* Function */  
void *gecko_cmd_dfu_reset(uint8 dfu);  
  
/* Command does not have response */  

Command Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint8

dfu

Boot mode:

  • 0: Normal reset

  • 1: Boot to UART DFU mode

  • 2: Boot to OTA DFU mode

Command does not have response (for BGAPI headers refer to [link)](bgapi-#

headers)

Events generated#

Event

Description

system_boot

Sent after the device has booted in normal mode

dfu_boot

Sent after the device has booted in UART DFU mode

dfu events#

dfu_boot#

This event indicates that the device booted in DFU mode and is now ready to receive commands related to device firmware upgrade (DFU).

C API#

/* event id*/  
gecko_evt_dfu_boot_id  
  
/* event structure*/  
struct gecko_msg_dfu_boot_evt_t  
{  
  uint32 version;  
}  

Event Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint32

version

The version of the bootloader

dfu_boot_failure#

This event indicates that an error, which prevents the device from booting, has occurred in bootloader.

C API#

/* event id*/  
gecko_evt_dfu_boot_failure_id  
  
/* event structure*/  
struct gecko_msg_dfu_boot_failure_evt_t  
{  
  uint16 reason;  
}  

Event Parameters (for BGAPI headers refer to link)#

Type

Name

Description

uint16

reason

The reason for boot failure. See [Error codes](error-

codes)