As explained in Firmware Architecture Cypress device can typically be used in two configurations – Controller mode or Embedded mode.
In controller mode, the host typically downloads some code like the general patch to the Bluetooth device’s SRAM or OCF. If the code is downloaded to SRAM, it needs to happen on each boot as the SRAM contents are lost on reset.
In embedded mode, the device embedded stack is used for some of the host functionality and the application code needs to be downloaded to the device’s OCF.
1. File Formats
Application code is usually kept in .hex or .hcd format. The *.hcd file is typically used for SRAM downloads and *.hex files are typically used for flash downloads. As an intermediate step, the source code along with some configuration values are converted to .cgs (configuration source) format and then converted to .hex or .hcd format. The .hcd file is useful when an external MCU needs to program the Bluetooth device in controller mode as the file size is smaller and the payload format is similar to the HCI commands. Intel .hex file is used when programming to flash. Figure 1 shows the file conversion process.
These files must be parsed and converted to HCI commands to download to the device. In ModusToolbox this is done by the ChipLoad tool.
Figure 1. File Conversion process
1.1 Details of *.hcd Format
The hcd files are binary files that can be parsed and interpreted directly as HCI commands. The hcd files have all the commands in binary format except the packet type which needs to be added by the host. The format of the hcd files are as follows:
- The first two bytes are the command identifier. For example, the HCI_WRITE command is represented by 0x4C, 0xFC.
- The next byte is the command payload length. For example, 0x06 indicates that six more bytes will follow to complete the command.
- The command payload.
To convert the file to HCI commands, only the HCI packet type needs to be added. For example, when sending a command from the host, 0x01 should precede any HCI command to indicate that it is a command rather than an event.
The following WRITE_RAM command is an example:
01 4C FC nn xx xx xx xx yy yy yy …
In this WRITE_RAM command:
- nn is 4 + N, which represents four address bytes plus N payload bytes.
- xx xx xx xx is the 4-byte, absolute RAM address.
- yy yy yy … are the N payload bytes to be loaded into the addressed RAM location.
The following response to each WRITE_RAM command is expected within 200 ms:
04 0E 04 01 4C FC 00
1.2 Details of *.hex Format
The .hex file follows the Intel I32HEX conventions. The format consists of records delimited by ASCII carriage return and line feed (0x0D, 0x0A). The format of the .hex files is as follows:
- First character is the start code ‘:’ (ASCII 0x3A)
- Next byte indicates payload length. For example, ‘FF’ indicates 255.
- Next four bytes indicates 16 address bits. For example, ‘1000’ represents address 0x1000. The type of address depends on the type of command.
- Next byte indicates the type of command:
- ‘00’ is for data and the address field represents the lower 16 bits of the destination address.
- ‘01’ indicates end of file. The payload is 0 and the address field is set as ‘0000’.
- ‘04’ indicates extended address. The address field indicates the lower 16 bits of the address and the payload represents the higher 16 bits of the address.
- ‘05’ for a 32-bit address payload. The address field is set as ‘0000’, the payload length is set as ‘04’ and the payload is interpreted as a 32-bit address. This is often used to indicate a LAUNCH_RAM (described later) destination.
1.3 Details of *.cgs Format
The .cgs file contains configuration parameters, patch code, and application code.The .elf file generated from the application source code is converted to .cgs format and is appended to the patch .cgs file located at wiced_btsdk\dev-kit\baselib\<device>\internal\<device>\patches\patch.cgs.
The definition of the configuration parameters in the .cgs file can be found in wiced_btsdk\dev-kit\baselib\<device>\internal\<device>\configdef<device>.hdf.
Parameters such as the crystal frequency, UART configuration, BD_ADDR, local name, and RSSI configuration can be modified using the patch .cgs file.
2. File Generation During Build
The file conversion process is as follows:
- The source files (.c, .h) are compiled and converted to .o (object) files using GNU tools.
- Library sources are linked to library .a files.
- These along with prebuilt library files are then linked to a .elf (executable and linkable format) file by GNU tools.
- The .elf file is converted to .cgs (configuration source) file using the wiced_btsdk\dev-kit\baselib\<device>\make\scripts\wiced-gen-cgs.pl script. The ROM patch code and platform .cgs files are also appended.
- The wiced_btsdk\dev-kit\btsdk-tools\Windows\CGS tool is then used to convert the .cgs file to Intel hex format. The cgs.exe application takes inputs such as the .cgs file created in the previous step and .btp file. The cgs.exe application can take runtime arguments such as BD ADDRESS and overwrite the BD ADDRESS in the .btp file. This can be useful while programming multiple devices with different addresses.
- The hex file is converted to an hcd file using the tool wiced_btsdk\dev-kit\btsdk-tools\Windows\IntelHexToBin
3. Recovery Process
Sometimes, the CYW20719 device may enter an unknown state or the HCI baud rate might have been changed from default. In such cases, it is not possible to program the device using HCI UART. To program the device correctly, the device needs to be put into the recovery mode. This is done by asserting the HCI UART CTS line while resetting the device.
When the Bluetooth device is reset, it checks for status of the HCI UART CTS pin (recovery pin) during power-ON. If the recovery pin is asserted (LOW) during reset, then the device enters what is called recovery mode. This mode will attempt to detect the UART baud rate by checking the RX line for the bit pattern of an HCI_RESET command. When detected, the HCI_RESET response is given at the same baud rate.
In this mode, most of the HCI commands will have no response. To download to the device in this mode, ignore the ‘no response’ to HCI_DOWNLOAD_MINIDRIVER and proceed with the download procedures. If the CTS pin is high after reset, then the device will check the OCF and apply any stored configuration, typically ending in a mode ready to accept all HCI commands at a default baud rate. If no configuration is available, the device will enter autobaud mode. Note that the application code can be directly loaded to the SRAM and executed or to the serial flash and then executed on next boot up.
4. Minidriver
The minidriver is separate FW independent of the ROM code. It is used to download the application code to the on-chip flash. The minidriver contains code to interpret certain HCI commands such as WRITE_RAM and READ_RAM and execute those commands. To download the code to the on-chip flash, first the minidriver needs to be written and executed from SRAM, which will interpret further HCI commands and write the code to the correct location in flash. As soon as the code download is complete, the minidriver is discarded because it is no longer needed. The minidriver will differ if the interface changes from UART to SPI or something else. The default minidriver can be found at wiced_btsdk\dev-kit\baselib\<device>\platforms\minidriver.hex.
5. Other Resources
- WICED Module Programmer User Guide – KBA225060
- Programming Using Chipload.exe - KBA228316
- Programming an EZ-BT WICED Module – KBA223428
