User's Guide

API Protocol Reference
EZ-Serial BLE Firmware Platform User Guide, Doc. No. 002-11259 Rev. *E 177
• Mode 1: Anticipate (factory default with 5 ms wait and 20 byte length)
This mode waits up to [wait] milliseconds in anticipation for at least [length] bytes to arrive from the external host.
If the target byte count is reached before the wait time expires, all available bytes will be transmitted immediately.
If the configured wait time expires before reaching the target byte count, all available bytes will be transmitted at
that time. Anticipate mode is suitable for most general operations and will not negatively impact throughput if the
incoming serial data arrives fast enough to keep the UART receive buffer full.
The [wait] setting must be between 1 and 255. The [length] setting must be between 1 and 128, which is the
internal UART RX software buffer size.
• Mode 2: Fixed
This mode waits indefinitely until at least [length] bytes have been read, then transmits exactly that many bytes.
Fixed mode is best used in cases where the host sends chunks of data which are always of the same size.
Setting a [length] value that is larger than the GATT MTU payload size will result in multiple transmissions once
all data has been buffered. For example, a fixed packet length of 32 bytes with the default GATT MTU size of 23
bytes (usable payload size of 20 bytes) will result in one 20-byte packet followed by one 12-byte packet. The
MTU depends on the value negotiated by the client after connection.
The [length] setting must be between 1 and 128, which is the internal UART RX software buffer size. The [wait]
setting is irrelevant in this mode.
• Mode 3: Variable
This mode requires an additional length value from the host before each packet to indicate how many bytes to
expect. EZ-Serial consumes this byte (it is not transmitted to the remote peer), and then waits until exactly that
many bytes to have been read before transmitting them. Variable mode is suitable for applications that require
packets of differing lengths and which can accommodate an extra transmitted byte from the host indicating each
packet’s length.
For example, the host can send [ 04 61 62 63 64 ] to transmit the 4-byte ASCII string “abcd” to the remote peer in
a single packet. Or, the host can send [ 05 61 62 63 64 65 03 66 67 68 ] to transmit “abcdefgh” in two packets
(“abcde” followed by “def”).
The prefixed packet length byte must not be greater than 128. Values greater than this will be capped at 128.
The [wait] and [length] settings are irrelevant in this mode.
• Mode 4: End-of-packet
This mode buffers data until the configured end-of-packet byte is encountered in the data stream, or until either
the MTU payload size or UART RX buffer has filled. End-of-packet (EOP) mode allows variable-length packets
without knowing in advance how long the packet will be.
The EOP byte defaults to 0x0D (the carriage return byte, often expressed as ‘\r’ in code). However, you can
change it to any value between 0x00 and 0xFF. When the EOP byte occurs in the data stream, all buffered data
up to that point including the EOP byte itself will be transmitted to the remote side.
In this mode, EZ-Serial will also transmit buffered data under two other conditions:
1. If the GATT MTU payload size is less than the UART RX buffer size (128 bytes) and enough data is buffered
to fill a single GATT packet, one packet’s worth of data will be transmitted. The default GATT MTU is 23
bytes with a usable payload size of 20 bytes.
2. If the GATT MTU payload size is greater than the UART RX buffer size (128 bytes) and the RX buffer is full,
128 bytes of data will be transmitted. This can only occur in cases where the connected client has
negotiated a GATT MTU greater than 131 bytes (actual transmit payload is MTU - 3 bytes).
For the “Anticipate” mode (1), you must consider the UART baud rate when choosing the [wait] and [length] values. A
5 ms wait time is suitable for a 20-byte target length at 115200 baud, but this is not enough time to read in 20 bytes at
9600 baud (for example). If you change the baud rate, be sure to choose a [wait] value that allows the target packet length
to be filled under normal operating conditions. Table 7-4 below contains “safe” wait values for 20-byte packets at common
baud rates for reference.