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. The protocol is easy to use for both humans and machines alike.

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:

See Getting Started, Evaluating BGX with a Terminal Program.

Serial Bus Modes

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

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:

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:

When str_select IS NOT configured:

str_sel GPIOBus mode selectionDescription
configuredmanual- bus mode initializes to the value set by bu i
- mode_sel GPIO determines if the bus is in STREAM mode or 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
not configuredautomatic- 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:

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


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

To enter STREAM mode:

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.


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 all  -> 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.

<response data>


Response Error Codes

CodeDescriptionFrom Commands
1Command failedall
2Parse errorall
3Unknown commandall
4Too few argumentsall
5Too many argumentsall
6Unknown variable or optionall
7Invalid argumentall
9Security mismatchcon
10GATT Procedure Failedcon