Using Vendor-Specific Commands in AnyCloud Bluetooth Applications - KBA232328
- Subscribe to RSS Feed
- Mark as New
- Mark as Read
- Bookmark
- Subscribe
- Printer Friendly Page
- Report Inappropriate Content
Version: **
A Bluetooth application based on AnyCloud SDK may require some device-specific functionality not serviced by the standard HCI commands or other API functions. In such cases, Vendor-Specific Commands (VSC) can be used. As the name suggests, VSC are defined by a vendor and are only applicable to their devices as opposed to standard HCI commands which need to be interoperable. These commands can help you achieve greater functionality from your device.
The structure of the VSC is similar to the standard HCI command with a 16-bit opcode followed by the parameter length and then the actual parameters. The 16-bit opcode consists of a 10-bit (0-9) Op-Code Command Field (OCF) and 6-bit Op-Code Group Field (OGF). In a VSC, the OGF is always 0b111111 (decimal 63) while the OCF can be as defined by the vendor. The rest of the parameters will be based on the actual command.
This article will first describe how to use the VSC in an AnyCloud application and then give a list of commands currently supported by some of the devices like CYW4343W and CYW43012.
The BTSTACK middleware provides an API to send VSC over HCI and receive events from the Bluetooth Controller via callbacks. Do the following to use VSC in your application:
1. Call the wiced_bt_dev_vendor_specific_command function in your application. See the btstack/<version>/wiced_include/wiced_bt_dev.h file as shown below:
- Parameter opcode: This is the opcode of the command you want to send. Some of the opcodes are shown in
Table 1. - Parameter param_len: Length of the parameters of the command. Depends on the command.
- Parameter p_param_buf: Buffer for parameter values. Depends on the command.
- Parameter p_cback: Callback that will be received upon command completion. If this is specified as NULL, there won’t be any command complete event.
- Return value: There are three types of return values:
- WICED_BT_SUCCESS: Command sent successfully; there is no command complete callback.
- WICED_BT_PENDING: Command sent successfully; waiting for a command complete event callback.
- WICED_BT_BUSY: Command not sent. The resource is waiting for the command complete event of the previous command.
The following snapshot shows an example of how to call this function:
In this snapshot, the wiced_bt_dev_vendor_specific_command is called with the following parameter values:
- HCI_UPDATE_BAUD_RATE_COMMAND: Opcode for updating the HCI baud rate. The command opcode is 0x18, which is combined with the vendor-specific command group to form a 16-bit value.
- HCI_UPDATE_BAUD_RATE_UNENCODED_LENGTH: This parameter value is 6, which means a parameter of size 6 bytes will follow.
- baud_rate_buf: Baud rate that must be set. In this example, the value is 3000000.
- vendor_specific_command_cb: Specifies the callback that must be called upon command completion.
2. Create a callback function which will be called upon command completion. The structure of the callback function is as shown below:
- Element opcode: Opcode of the command for which the callback is being called.
- Element param_len: Length of the parameters that will follow.
- Element *p_param_buf: Parameter value will be passed through this buffer. The values will depend on the command for which the callback is being called.
Table 1. VSC Commands
Command |
Description |
Opcode |
Parameters |
Return Values |
CYW4343W |
CYW43012 |
Set_Transmit_Power |
This command will adjust the transmit power attenuation on a per-connection basis |
0x026 |
Connection Handle uint_16: Connection handle of the connection for which the power level needs to be modified.
Max Tx Power Level int8: Tx power in dB. Maximum value is 4 and minimum value is -28 |
Status |
Yes |
Yes |
Update_UART_Baud_Rate |
Changes the baud rate at which the UART transport communicates. A “Command Complete" event will be generated at the previous baud rate. If the “Command Complete event" indicates success, the UART transport will then shift to the new baud rate. |
0x018 |
Encoded_Baud_Rate uint8_t: Make this as 0 to use unencoded baud rate
Explicit_Baud_Rate uint32_t: Baud rate in integer form |
Status |
Yes |
Yes |
LE_Read_Random_Address |
This command will read a random address |
0x0BA |
None |
Status
WD_ADDR bdaddr: Random address of the device |
Yes |
Yes |
Additional Resources
- See the PSoC 6 TRM for more details on the PSoC® 6 MCU memory architecture.
- See AN228740 for more details on the Serial Memory Interface.