PSoC® 4 BLE Troubleshooting Guide
Section 1: General Queries
1. Why don’t custom service UUIDs and characteristic UUIDs of a Peripheral appear in Android phones? Similarly, why does a BLE Peripheral with custom services work with the CySmart PC application, but not with Android mobile?
A) When you create a custom service, the automatically generated UUID will be in the Bluetooth base UUID. Versions of Android higher than 5.0 do not allow access to custom UUIDs that use the same base UUID as the Bluetooth base UUID. You should update/modify the default Bluetooth base UUID with a different base UUID. To do so, change the UUID from the Bluetooth base UUID, i.e., it should not be of the format 00000000-0000-1000-8000-00805F9B34FB (which is generated in BLE Component custom service/characteristic UUID. You must edit the number format of the custom characteristic / service UUID to make it different from the Bluetooth base format.
2. Why are dynamically updated advertising packets not visible in the CySmart™ PC application?
A) If the 'Duplicate filtering' property of Central devices is enabled, Central devices filter (will not accept) the multiple advertising packets from the same device (devices with same address).
Duplicate Filtering is already enabled in the CySmart tool, so it will receive the advertising data only once. Therefore, for refreshing the data, disable Duplicate filtering in CySmart. To do so, click Configure Master Settings > Scan Parameters > Duplicate Filter Policy > Disable Duplicate Filtering.
3. How do I check the disconnect reason of CyBLE?
A) When the BLE device gets disconnected, the CYBLE_EVT_GAP_DEVICE_DISCONNECTED event is triggered. This event indicates that the CyBLE device is disconnected from the remote device or failed to establish a connection. The parameter returned with the event contains a pointer to the reason for disconnection, which is of type uint8. For details, refer to BLE Core Specification Version 4.2, Vol 2, Part D.
In firmware, you can get the event parameter value from the CYBLE_EVT_GAP_DEVICE_DISCONNECTED event as follows:
Printf ("Error code is: 0x%x \r\n",*(uint8 *) eventParam);
Check the error code, and find the corresponding description from the “HCI error commands” section in the BLE Core Specifications Version 4.2, Vol 2, Part D, Section 1.3: List of error codes ).
4. How do I set a CyBLE device as Broadcaster and Observer at the same time?
In the BLE Component, put the device in to Central and Peripheral GAP role.
For the Broadcaster role, make Advertisement settings as follows:
- Discovery mode: Non discoverable
- Advertising: Non connectable undirected advertising
For the Observer role, add the following code in the CYBLE_EVT_STACK_ON event.
CyBle_GapcStartScan(); // API to start scanning
CyBle_GappStartAdvertisement(); // API to start advertisement
With these changes, the device will act both as Broadcaster and Observer.
5. How do I set a CyBLE Central device so that it scans only for a particular channel among channel 37, 38, 39 ?
A) To change the scan channel map configuration, change the bits 13, 14, and 15 of the CYREG_BLE_BLELL_SCAN_CONFIG register.
Bits - 15:13
Name - SCAN_CHANNEL_MAP advertising channels that are enabled for scanning operation.
Bit 15: setting 1 - enables channel 39 for use.
Bit 14: setting 1 - enables channel 38 for use.
Bit 13: setting 1 - enables channel 37 for use.
Default Value: 7
See the PSoC/PRoC BLE Register TRM.
To scan only in 37th advertising channel, use the following code in CYBLE_EVT_STACK_ON event in the BLE callback event handler. Ensure that the following code is added before calling the start scan API.
#define CYREG_BLE_BLELL_SCAN_CONFIG_USER (*(uint32*) CYREG_BLE_BLELL_SCAN_CONFIG)
CYREG_BLE_BLELL_SCAN_CONFIG_USER=CYREG_BLE_BLELL_SCAN_CONFIG_USER & 0xFFFF2FFF;
6. Why doesn’t the BLE device name show in an iOS phone?
iOS supports only a few specific profiles (for example HID, ANCS) for listing the device name in Bluetooth setting. See https://support.apple.com/en-us/HT204387.
An iOS device shows your device in its Bluetooth device list only if your Server/Peripheral device has any of these services,
7. Why do unexpected BLE disconnections occur and firmware get stuck in the interrupt handler?
Check the following parameters in firmware:
- Make sure that CyBle_ProcessEvents is called at regular intervals in the firmware. Go through the API description in BLE Component configuration for the time interval at which CyBle_ProcessEvents must be called. If a custom function consumes more time for execution, call CyBle_ProcessEvents inside it.
- If the disconnection happens in a custom board, check external crystal / clock settings. Ensure that external crystal parameters meet the specifications mentioned in Cypress application note, AN90589.
- Ensure that the BLE subsystem (BLESS) interrupt has the highest priority.
- Check any continuous flash writes during the BLE connected state. This may result in processing of BLE events to be pending and can cause disconnection. Try calling the flash write only if the BLESS state is CYBLE_BLESS_STATE_EVENT_CLOSE.
- If it is a custom board, ensure that the PCB layout design meets the specifications. See the Cypress application note: http://www.cypress.com/documentation/application-notes/an91445-antenna-design-and-rf-layout-guidelines
8. As per the BLE specification, BLE Data packets sent through BLE notification are not acknowledged in the application layer. Does this result in packet loss or out-of-order packet delivery in PSoC BLE devices?
A) When you use notifications, there will not be any acknowledgment in the application layer, but there will be acknowledgment in the link layer. This means that when the peer sends the packets, the next packet will not be sent unless the sender receives an acknowledgement at the link layer. This ensures that there are no missing packets.
To ensure packet delivery in the correct order, you should handle reading the received packets in the application layer. This requires that the application should not be busy with other tasks when receiving notifications.
9. The Ez-BLE module is working fine with the old BLE Component, but stops working when BLE Component is updated to version (V_3.1/V3.2/V3.3). Why?
10. How do I change the advertising data at runtime?
A) Use the CyBle_GapUpdateAdvData() API.
Refer to the Dynamic broadcaster project in GitHub: https://github.com/cypresssemiconductorco/PSoC-4-BLE/tree/master/100_Projects_in_100_Days/Day009_Dynamic_Broadcaster
11. Why do write requests time out when notification of Server from Client is enabled?
A) When a BLE client enables Server notification, the Client is actually sending a write request to the custom characteristic descriptor (CCCD) of the Server. Thus, the Client expects a write response from the Server. If Client does not receive a write response, it leads to the write request timing out. Make sure that write responses are sent from the Server in response to CCCD write requests from the Client to enable notification.
12. Why is a Peripheral that is advertising unable to establish connection?
A) The can happen because of multiple reasons. Ensure that Peripheral advertisement mode is 'connectable'. In addition, check whether the Peripheral has enabled any whitelist constraints.
13. Is it possible for a Central device to send/receive data from multiple peripherals?
A) PSoC 4/PRoC BLE devices do not support multiple connections. As a workaround, use time division multiplexing (TDM). See the GitHub project for details: https://github.com/cypresssemiconductorco/PSoC-4-BLE/tree/master/100_Projects_in_100_Days/Day030_Time_Multiplexed_Central
14. If I set the MTU of the connection as 23 bytes and Server GATT characteristic size to 512 bytes (maximum value), I can send larger values using the GATT Write Long Characteristic Value operation. However, if the MTU size is 512 bytes, I can use the simple GATT write request. What are the differences between these two write operations?
A) The maximum length of an attribute value is 512 octets
If you are using a Write request, you can write up to (max negotiated MTU) – 3 bytes. Thus, if the negotiated MTU size is 512 bytes, the maximum value which you can write is 509 bytes in a single write operation.
In the Write long method, you can write a maximum value up to the maximum attribute length, that means up to 512 bytes.
Application example: Suppose your Peripheral is a CyBLE device and has a Central device (mobile phone, CyBLE etc.). Some mobile phones have the MTU size restricted to a particular value, say 23. The negotiated MTU size becomes 23 regardless of the MTU size of your Peripheral device because your Central device's MTU size is 23. If you want to write a value to the GATT Server characteristic which is greater than 23 bytes, the only option is write long
Note: Negotiated MTU size means the minimum of (MTU size of Central, MTU size of Peripheral). This negotiated MTU size will be used for the rest of the communication between Central and Peripheral.
15. Why doesn’t the Central BLE device receive scan response data from the peripheral?
A) For receiving a scan response from the Peripheral, the Central device should be doing ‘Active Scanning’. Check the scan settings of the Central device.
16. Can a GATT Server start the MTU exchange?
A) No. Only the Client can initiate the MTU exchange request.
17. I have set the MTU size as 50. However, I am not able to send data bytes more than 20. Why?
A) This may happen if the Central device hasn't sent an MTU exchange request. By default, the MTU size will be set to 23 bytes. If you want to set the MTU size as more than 23, the Central device must send an MTU exchange request.
18. My Central is a smart phone and Peripheral is CyBLE 4.1 device. I am not able to get my device working with whitelist filtering. Why?
A) Most smartphones use resolvable private address, so the phone uses a random address (not the same) each time. In BLE 4.1, the controller does not resolve the address, but the Host does. You can use the following method to connect to only one particular device.
In your application, use Bonding but don’t enable whitelist. Therefore, every time you connect with the same device (if only one device), the connection handle will be 4. If you connect with new device, the connection handle will be 3. In the CYBLE_EVT_DEVICE_CONNECTED event, check the connection handle. If connection handle is not 4, immediately disconnect the connection from the Peripheral. If an already bonded device connects (using a resolvable private address), the connection handle would be 4.
19. How can I disable BLE power amplifier?
A) Call the SetTXPower() API with the 0x00 parameter. It will make the power amplifier range as minimal.
20. How do I disable random advDelay in firmware?
A) Use the following code to disable random advDelay in firmware:
#define ADV_RAND_DISABLE_MASK 0x0100
register_value = CY_GET_XTND_REG32(CYREG_BLE_BLELL_ADV_CONFIG);
register_value |= ADV_RAND_DISABLE_MASK;
21. How often I need to call CyBle_ProcessEvents()?
A) This event handler must be called at least once every interval 't' where:
1.'t' is equal to the connection interval or scan interval, whichever is smaller, if the device is in GAP Central mode of operation, or
2. 't' is equal to the connection interval or advertisement interval, whichever is smaller, if the device is in GAP Peripheral mode of operation.
For more details, see the API description in the BLE Component datasheet.
Section 2: Low-power modes
1. How do I implement low-power mode in a BLE project?
A) Refer to the following application notes:
- AN92584 - Designing for Low Power and Estimating Battery Life for BLE Applications | Cypress Semiconductor
2. Why does the power consumption go high even though code for low-power operation is added?
A) Do the following:
1. Check if Debug Select option was changed from SWD to GPIO.
2. Ensure that you have managed leakage currents in ADCs and GPIOs.
3. Ensure that you have stopped ECO by using the ECO stop API or by calling CyBle_EnterLPM().
3. Why doesn't the device enter low-power mode for a custom board, but work fine on the BLE Pioneer kit?
A) Ensure that you have selected WCO external crystal for LFCLK. Make sure the selected WCO meets the specifications needed.
4. How can I use low-power implementation without using WCO?
A) It is not possible for the BLESS to enter low-power mode without WCO because the ILO clock accuracy is not sufficient to maintain the time constraints during low-power mode. Thus, the stack will not allow the BLESS to enter low-power mode with ILO; you must use the WCO.
5. How do I reduce the current consumption during scanning?
A) Reduce the scan window and increase the scan interval.
6. How do you place PSoC 4 BLE, PRoC BLE, and Ez-BLE modules in Stop mode?
Section 3: Security-Related Queries
1. Why do Read / Write fail when trying to read/write a particular characteristics of BLE Server from Client device?
A) Ensure that the Peripheral has Read / Write properties for the characteristic. If permissions for the characteristic require Authentication / Authorization, make sure that these are provided. Make sure the attribute size set in the server firmware is less than or equal to the size which the Client is trying to write.
2. How do i authenticate between Central and Peripheral when the devices do not have I/O capabilities?
3. How do I use CyBle_GattsDbAuthorize for authorizing one Central to access the GATT database of the Peripheral?
Suppose you are setting 'Authorization required' for any characteristic. Then the CyBle_GattsDbAuthorize API setting determines whether the Client can access the GATT DB characteristics (which is set as 'Authorization required') or not. If you set CyBle_GattsDbAuthorize(0), it will not give access to the Client to access that GATT DB characteristics (which is set as 'Authorization required'). If you set that to a non-zero value, the Client will be able to access the characteristic values. In this way, you can use the API and decide the Clients that can access the GATT DB of the Server
4. Why does an authentication failure occur when a BLE device tries to connect the peer device for second time?
A) The phone might have stored the pairing information of the device (bonded to the device), whereas the device might not have bonded or had removed the bonding information. Therefore, the phone must be unpaired from the mobile manually.
5. What is the maximum number of devices for adding to Bond list and whitelist?
For Bonding – Maximum 4
For Whitelist – Maximum 8 including bonded devices
These numbers are for PSoC 4 BLE. PSoC 6 BLE has more capability.
6. A Peripheral is connected without asking a passkey entry even though Authentication is enabled when using CySmart Android app/ PC application, but this does not happen in CySmart iOS. Why?
A) CySmart iOS sends the Authentication request on establishing the connection. For CySmart PC and CySmart Android, user need to press on the ‘Pair’ button for sending the Authentication request. Otherwise, an Authentication request need to be sent from the Peripheral firmware.
7. Is the Peripheral sending the Central an authentication request after every connection a valid method for authentication? (During the CYBLE_EVT_GAP_DEVICE_CONNECTED event) even if it is already bonded to that device.
A) Yes, it is valid.
8. I am getting authentication failure with CySmart PC but no issues with mobile app. Why?
A) Make sure the security settings of CySmart PC match with peripheral security settings.
9. How do I use various authentication I/O capabilities?
Section 4: OTA-Related Queries
1. Error while adding new BLE APIs to Bootloadable project in Fixed Stack OTA. Why?
(Example: I modified my application project using the BLE Fixed OTA stack example documentation. Everything works fine, but I am unable to use the CyBle_GattsWriteAttributeValue function in my project now.
GATT_DB_LOCALLY_INITIATED is also undefined. How do I update the value of a characteristic in the bootloadable project?)
A) This is because the Bootloadable project does not have the definitions of these APIs. Therefore, you need to KEEP the APIs in the linker script. Thus, definitions of the APIs will be taken from the bootloader project. First, KEEP the APIs in the script file cm0gcc.ld. Set the bootloader project active. Open the cm0gcc.ld file in the Bootloader project. Add the KEEP APIs. Now save and build the project and run the mk.bat file. Now in Bootloadable project, add the declaration of the API as an extern in the ota_mandatory.h file.
2. How do I reduce the Bootloader project size?
- Check the commands added in your Bootloader project. To do so, double-click on bootloader Component, and remove the commands that you don't want in your project.
- In the Bootloader project, navigate project > Build Settings > Compiler > Optimization Change to Size (from debug)
- Remove unnecessary UART prints
- To reduce the RAM size consumed, try reducing the stack size.
3. Why does the firmware upgrade fail at the authentication stage in CySmart PC?
A) In most cases, OTA fails at the authentication stage because of security setting mismatches in the peer device. Make sure that the security settings of the CySmart PC application match with that of the OTA stack project.
4. Why does a firmware upgrade fail?
Figure: CySmart PC OTA Progress Window
- Ensure that you have selected the correct .cyacd file
- Check in the BLE Component Bootloader settings, and ensure that the data byte size of the bootloader characteristic is set correctly.
- If establishing a connection failed, check the BLE firmware, and look for custom board issues.
- If an authentication failure occurs, ensure that the security settings match with project settings.
- If discovering bootloader service/enable notification fails, it may indicate that the device might not have entered bootloader mode. Make the device to enter bootloader mode again and try OTA. Check the project bootloader characteristic settings are correct as well.
- If failed in transfer firmware image – ensure that the correct .cyacd file is selected. Ensure that the flash read/ writes are correctly handled in firmware.
5. How do I add OTA to an existing application?
6. Where is the Bootloadable ‘start vector’ defined? Is there a way to modify it?
A) You can modify the Bootloadable start vector. To do so, open the bootloadable Component and check Manual application image placement and write the placement address. Refer Bootloadable Component datasheet for details. Ensure that this address does not interfere in the Bootloader area.
Section 5: Schematic Review / Programming related
1. What are the third-party programmers recommended for BLE chips?
2. How do I recover the Pioneer kit that stopped detecting in PC (PSoC Creator/Programmer)
A) Check the KitProg LED status, and then check the solution in section: A.2 KitProg Status LED States from Pioneer Kit Guide (http://www.cypress.com/mwginternal/de5fs23hu73ds/progress?id=zy9zJr8xbCb9X3NU4CBCdR4nXDPsxxo4bpt4WRlG7Bg,&dl).
3. Why isn't the device detected in Programmer/Creator?
- Check whether the part number and hex file are selected correctly.
- Check the SWD pins connections. Ensure that there are no resistors added on programming pins.
- Ensure that the port settings are correct
4. Why doesn't the CySmart Dongle get detected in CySmart?
5. What are the major points to keep in mind for schematic design for PSoC 4/PRoC BLE?
- Select proper ECO and WCO crystals. See http://www.cypress.com/documentation/application-notes/an95089-psoc-4proc-ble-crystal-oscillator-selection-andtuning
- For VDD pins, make the capacitor connections as below:
- For VDDD - If you are shorting all VDDD pins, you can have one 1-µF cap in parallel, but each .1 µF should be placed near to each pin separately (close to each VDDD pin).
- For VDDA - If you are shorting all VDDA pins, you can have one 1-µF capacitor in parallel, but each .1 µF should be placed near to each pin separately (close to each VDDA pin).
- For VDDR - If you are shorting all VDDR pins, you can have one 1-µF capacitor in parallel, but each .1 µF should be placed near to each pin separately (close to each VDDR pin).
- Antenna – See http://www.cypress.com/documentation/application-notes/an91445-antenna-design-and-rf-layout-guidelines
- Selection of pins: Make sure that your project builds successfully with all the pins you selected for your design before going for PCB design.
Section 6: Related BLE KBAs
1. BLE public device address - http://www.cypress.com/node/434501
2. Maximum Transmission Unit - http://www.cypress.com/knowledge-base-article/maximum-packet-size-according-mtu-kba203312
3. WCO from external clock - http://www.cypress.com/knowledge-base-article/external-oscillator-wco-psoc-4-proc-ble-kba200299
4. 3D model of Ez-BLE modules - http://www.cypress.com/knowledge-base-article/3d-model-files-ez-ble-modules-kba218122
5. Ez-BLE module placement in your PCB - http://www.cypress.com/knowledge-base-article/ez-ble-module-placement-kba97095
7. How to Authorize Central - http://www.cypress.com/knowledge-base-article/authorize-ble-server-gatt-db-specific-ble-clients-kba219319
8. Setting ECO cap trim for Ez-BLE modules - http://www.cypress.com/knowledge-base-article/eco-capacitance-trim-values-ez-ble-modules-kba218990
9. BLE product listing & Qualification - http://www.cypress.com/knowledge-base-article/queries-ble-qualification-and-declaration-processes-kba210802
13. Recover Cysmart Dongle - http://www.cypress.com/knowledge-base-article/recover-cysmart-ble-dongle-kba220052
15. Directed Advertisement - http://www.cypress.com/knowledge-base-article/configuring-ble-peripheral-perform-directed-advertisement-kba218959
17. Extended range module as normal module - http://www.cypress.com/knowledge-base-article/how-make-extended-range-ble-modules-work-normal-modulekba219463
18. Change Attribute size - http://www.cypress.com/knowledge-base-article/changing-ble-attribute-size-runtime-kba219049
19. Selection of Scan channel - http://www.cypress.com/knowledge-base-article/configuring-ble-central-device-work-particular-scan-and-connection-channel
Section 7: Related Application Notes