User's Guide

Operational Examples
EZ-Serial BLE Firmware Platform User Guide, Doc. No. 002-11259 Rev. *E 30
rates. Refer to Section 2.3.2 (Connecting the Serial Interface) for detailed instructions and specific
requirements for proper functionality when connecting an external UART device to the BLE Pioneer Kit.
WARNING: Selecting a baud rate below 9600 and using API protocol communication can result in a
situation where EZ-Serial generates API response and event packets faster than the UART interface
can transmit them to the host. If this occurs, data will flow continuously out of the module, but it will not
respond to incoming commands. The most likely trigger for this situation is a scan started with
gap_start_scan (/S, ID=4/10), or auto-starting CYSPP client mode operation (which also begins a scan).
Performing a scan in a busy environment will generate scan result events rapidly and continuously.
Possible workarounds include:
- If using CYSPP, keep the CYSPP pin externally asserted to suppress API output
- If possible, select a faster baud rate
- If possible, reduce the quantity of devices in the environment to decrease scan result frequency
Example 1: Set UART to 38400 baud, even parity, flow control enabled, and store in flash
Direction Content Effect
TX→
STU,B=9600,F=1,P=2
Set new UART parameters (RAM only) – “38400” decimal is “9600” hex
←RX
@R,0009,STU,0000
Response indicates success
Change host UART parameters to match new settings here before sending additional data
TX→
STU$
Write UART settings to flash
←RX
@R,000A,STU$,0000
Response indicates success
Note the use of the command “STU$” with no additional arguments. In text mode, most SET commands have no required
arguments, allowing you to change only the desired settings. Optional arguments that are omitted will not be modified,
because the EZ-Serial platform substitutes the current runtime values as if you had supplied all of them.
In the example above, the “baud,” “flow,” and “parity” settings are stored in RAM with the first command, and then the
second command writes to flash whichever runtime values are affected by the system_set_uart_parameters (STU,
ID=2/25) API command.
Example 2: Set UART to 115200 baud, no parity, flow control disabled, and store in RAM only
Direction Content Effect
TX→
STU,B=1C200,F=0,P=0
Apply new UART parameters
←RX
@R,0009,STU,0000
Response indicates success
3.1.3 How to Change the Device Name and Appearance
Use the gap_set_device_name (SDN, ID=4/15) API command to set a new friendly device name at any time, and the
gap_set_device_appearance (SDA, ID=4/17) API command to set a new appearance value.
EZ-Serial uses the device name and appearance to populate the GAP service’s name and appearance characteristic
values in the GATT database. If EZ-Serial is allowed to automatically manage the advertisement and scan response data
content (default behavior), then it will also include up to 29 bytes of the device name in the scan response packet. (The
limit of 29 bytes is due to a BLE specification limit on the maximum scan response payload, which is 31 bytes; the other
two bytes are needed for the field length and field type values that are part of the device name field.)
NOTE: EZ-Serial limits the device name length to 64 bytes to minimize internal SRAM requirements.
Using EZ-Serial’s special macro codes, described in Section 7.5 (Macro Definitions), you can enter a single text string
which is expanded internally to include module-specific values—in this case, the Bluetooth MAC address. This is shown in
the first example below.