Serial Interface

Bluetooth Xpress BLE provides a flexible serial interface.

The serial protocol for issuing commands and receiving responses can be used locally via the UART interface or remotely via the BLE interface. Bluetooth Xpress modules also allow data to be streamed directly between the UART and BLE interfaces.

The serial bus mode determines whether data is streamed, or which interface can send commands to Bluetooth Xpress modules.

For a demonstration of serial bus modes, bus mode selection, and remote control of a Bluetooth Xpress module, see the Bus Mode Selection and Remote Control application note.

UART Protocol

UART baud rate is determined by the ua b variable. The default is 115200 .

UART flow control is determined by the ua f variable. The default is 0 , no flow control.

The serial port settings, corresponding to the Bluetooth Xpress module defaults, are 115200 8N1 with NO hardware flow control:

• Baud rate: 115200
• Date: 8 bit
• Parity: none
• Stop: 1 bit
• Flow control: none

See Getting Started, Evaluating BGX with a Terminal Program .

Hardware Flow Control

Hardware flow control is used to regulate the flow of serial data between a Bluetooth Xpress device and a connected serial device such as an MCU. The following diagram shows typical connections to implement hardware flow control.

Flow Control Connections

Enabling Flow Control

Hardware flow control is enabled or disabled by the ua f variable. When enabled, the BGX device will utilize the hardware flow control signals. When disabled the hardware flow control signals RTS and CTS are not used.

Flow Control Signals

The Bluetooth Xpress device provides active low serial hardware flow control signals RTS and CTS with the following functions:

NOTE: If the BGX deasserts its RTS pin while actively receiving a byte on its RX pin, that byte will be received by the BGX. However, if the connected serial device begins transmission of a byte after the BGX deasserts its RTS pin, reception of that byte by the BGX is not guaranteed.

Flow Control Operation

BGX-to-MCU

NOTE : The following diagrams are meant to help with understanding the overall data flow. They show a simplified representation of internal buffers of the BGX and other devices and should not be taken literally.

As BGX receives data from a remote Bluetooth device, it transmits the data to the MCU via the serial TX line. The MCU signals that it can receive data by asserting its RTS signal. In this condition the BGX will continuously transmit any data it receives to the MCU.

NOTE : In the below diagrams, the "ack" data are BLE acknowledgements in the case of Legacy Flow Control, and are Buffer Bytes Freed Streaming Control Messages in the case of Fast-Ack Flow Control (see Xpress Streaming Service Flow Control ).

Data Flow to MCU

When the MCU needs to halt data flow for internal buffer management or some other reason, the MCU deasserts RTS. In this condition the BGX will stop transmitting data to the MCU and will begin to accumulate data in its internal buffers.

MCU Stops Incoming Data

Eventually the internal buffer will fill and BGX will stop acknowledging data from the remote Bluetooth device.

BGX Buffer Fills

This will eventually cause the remote Bluetooth device to stop sending data.

Remote Stops Sending

When the MCU asserts RTS again, then the BGX will resume transmitting data to the MCU, and its internal buffer will drain and begin to acknowledge data from the remote Bluetooth device.

Mobile-to-BGX Remote Configuration

If the remote Bluetooth device is a mobile device using the Xpress Mobile Framework, then it will stop transmitting data to the BGX when the BGX buffer is full due to CTS being deasserted.

BGX-to-BGX Remote Configuration

If the remote Bluetooth device is another BGX acting as central, then it can be configured to use acknowledged writes or unacknowledged writes. This is done using the ce w m variable.

In a BGX-to-BGX connection, data integrity is guaranteed if UART flow control ( 'ua f' ) is enabled on both BGX devices and the Central BGX is configured to use acknowledged writes ( ce w m = ack ).

While unacknowledged writes do not guarantee data integrity in all circumstances, there are some use cases where they can be safely used. For example, a BGX-to-BGX connection may be used to send a large file from one device to another. In this use case, using unacknowledged writes can significantly decrease the amount of time it takes to transfer the file due to the increased throughput of unacknowledged writes (see [Throughput] (~/throughput)). The file can be safely transferred with unacknowledged writes if the following conditions are met:

• Both BGX devices have UART flow control ( ua f ) enabled.
• The BGX device receiving the file over its BLE interface (the "receiving BGX") has its UART baud rate ( ua b ) set to a value significantly higher than the maximum possible throughput (see Throughput for a list of throughput values). If possible, it is recommended that the baud rate be set to its maximum value of 2000000.
• The host processor communicating with the receiving BGX must never deassert the BGX's CTS pin. This guarantees that the BGX can transmit received BLE data immediately, preventing a build-up of received BLE data inside its internal buffers.
• The host processor communicating with the receiving BGX must not transmit UART data to the BGX while it is actively receiving BLE data.

In this scenario the receiving BGX never needs to use the acknowledge mechanism to "hold off" the transmitting BGX, so data integrity is ensured.

MCU-to-BGX

As the MCU sends serial data to the BGX, the BGX internal buffer level will vary as it transmits the data to the remote Bluetooth device.

Data Flow From MCU

If the remote device stops receiving data (because of buffer fullness or other reason), the BGX will not transmit data to the remote device and the BGX internal buffer will begin to fill.

Remote Device Stop Data Flow

If the BGX internal buffer approaches full, it will deassert RTS to indicate it cannot receive any more data. The MCU should detect this condition on its CTS line and should stop sending data to the BGX.

BGX Buffer Full

Once the remote begins accepting data again, then the BGX internal buffer level will drop and it will re-assert its RTS signal. The MCU observes this on its CTS signal and can then resume sending serial data.

Flow Control Time Limit

When using Legacy Flow Control, the maximum amount of time that data flow can be stopped by hardware flow control is 30 seconds. If data flow does not resume within 30 seconds, then the connection will be dropped. For more information about the 30 second timeout, refer to the following sections of the Bluetooth Specification:

• Volume 3, Part F: Attribute Protocol (ATT), Section 3.3.3 - Transaction
• Volume 3, Part G: Generic Attribute Profile (GATT), Section 4.13 - Procedure Timeouts

When using Fast-Ack Flow Control, there is no maximum amount of time that data flow can be stopped by hardware flow control.

Serial Bus Modes

A Bluetooth Xpress module can operate in any one of three distinct bus modes:

• local COMMAND mode --- Bluetooth Xpress commands are issued via the serial UART interface (the remote COMMAND interface is disabled)
• STREAM mode --- data is transferred directly between the serial UART interface and the wireless BLE interface. This mode requires the Xpress Streaming Service feature.
• remote COMMAND mode --- Bluetooth Xpress module commands are issued via the wireless BLE interface (the local COMMAND interface is disabled). This mode requires the Xpress Streaming Service feature.

The diagram below shows a schematic representation of the three bus modes.

There are various ways to make Bluetooth Xpress BLE transition between bus modes including:

• Assert a GPIO (manually via a push button or using a microcontroller)
• Issue the str command (when the module is in either local or remote command mode)
• Set the Xpress Streaming Service mode characteristic (using a remote BLE host such as an iOS/Android/Windows app or another Bluetooth Xpress module)

Manual and Automatic Bus Mode Selection

When a Bluetooth Xpress module boots up, it may be desirable to control it via the UART interface, or by a remote BLE device.

To allow for either option to work without further configuration, Bluetooth Xpress modules support a choice of manual and automatic bus mode selection.

Bus mode selection depends on whether the str_select GPIO is configured. See the gfu (GPIO function) command.

When str_select IS configured:

• bus mode selection is manual
• if bus serial control is set to 'edge' (see bu s c ), then the bus mode initializes to the value set by bu i
• str_select GPIO determines if the bus is in STREAM mode or local COMMAND mode by level or edge (see bu s c )
• if the bus is in STREAM mode, the remote device can use the mode characteristic to switch to remote COMMAND mode, if enabled. See sy r e

When str_select IS NOT configured:

• bus mode selection is automatic
• if a remote device is connected: the bus is in STREAM mode
• if NO remote device is connected: the bus is in local COMMAND mode
• if the bus is in STREAM mode, the remote device can use the mode characteristic to switch to remote COMMAND mode, if enabled. See sy r e

The state diagrams below show the possible transitions.

Manual Bus Mode Selection

Manual mode state diagram

Automatic Bus Mode Selection

Automatic mode state diagram

local COMMAND mode

To enter local COMMAND mode:

• if manual bus mode is selected, either:
  • boot the module with the bu i (bus mode initialization) variable set to command
  • assert/toggle the mode_sel GPIO --- see the gfu (GPIO function) command
• if automatic bus mode is selected:
  • disconnect any remote device

See Command Protocol for details of sending commands and handling responses.

STREAM mode

For details of this service, see BLE Services, Xpress Streaming Service

To enter STREAM mode:

• if manual bus mode is selected, either:
  • boot the module with the bu i (bus mode initialization) variable set to stream
  • with the module in local COMMAND mode, assert/toggle the mode_sel GPIO --- see the gfu (GPIO function) command.
• if automatic bus mode is selected:
  • connect remote device
  • issue the str (stream) command

In Stream mode, bytes or characters sent from the host to a serial interface are transparently pushed by a Bluetooth Xpress module to the remote device via the wireless interface.

Conversely, bytes or characters received from a remote device are transparently pushed by Bluetooth Xpress BLE to a serial interface connected to the host.

The Getting Started example is a typical application that uses stream mode.

Command Protocol

Both local COMMAND mode and remote COMMAND mode provide an asynchronous command interface that a host may use to send and receive control and setup information. Command mode is typically used by a host to configure Bluetooth Xpress modules.

Command mode is the primary mode used to configure Bluetooth Xpress modules. Grasping how command mode works, and the options provided, is the key to mastering the use of Bluetooth Xpress modules. The serial interface is designed to cater for humans and machines alike, and the interface is configurable to suit the needs of both.

In Command mode, control, data and debug logs (if enabled) are interleaved.

Configuration

In command mode, Bluetooth Xpress modules effectively provide a slave interface to the host. The host is the master and a Bluetooth Xpress module is the slave. The host initiates all transactions which follow the format of "host issues a command, the Bluetooth Xpress module provides a response". Bluetooth Xpress module commands are used by the host to read and write Bluetooth Xpress module variables , send control information, and send and receive data across network connections.

The system command mode variable ( sy c m ) is provided for convenience to make it easy to switch between human mode and machine mode.

Setting sy c m to human or machine conveniently changes the value of each of the following variables to configure the desired command mode.

Human-Friendly Command Mode

By default, the serial interface is configured to be human friendly with the following settings. See System Variables .

set sy c m human

is equivalent to:

set sy p 4    -> Turn on all debug & informational prints
set sy c h 0  -> Disable response header
set sy c p 1  -> Turn on the user prompt
set sy c e 1  -> Turn on echo to see what you're typing

Machine-Friendly Command Mode

To configure the serial interface for machine-friendly operation, use the following settings. See System Variables .

set sy c m machine

is equivalent to:

set sy p 0    -> Turn off all debug & informational prints
set sy c h 1  -> Enable response header
set sy c p 0  -> Turn off the user prompt
set sy c e 0  -> Turn off echo

Command Format

<command name> [variable name <argument>]\r\n

Commands sent to Bluetooth Xpress modules are formatted as shown in the following table. The <command name> is a Bluetooth Xpress command issued by the host, and [variable name <argument>]\r\n is an (optional) Xpress variable name and accompanying argument terminated by a carriage return and newline character.

Response Format

Responses from Bluetooth Xpress module follow the format shown in the text below.

RXYYYYY\r\n
<response data>

where:

• R denotes a Response header.
• X is the error code (response error codes are listed below).
• YYYYY is the response data length in bytes including a trailing \r\n . The response data length is zero if no data is available, or >2 (including \r\n ) if data is available.
• <response data> . If the response data length is >0, the <response data> is the data returned from a Bluetooth Xpress module in response to the command.

Response Error Codes