BGX13-1.0 Command Reference
This page provides a list of Bluetooth Xpress API commands with a full description of how to use each command.
The Bluetooth Xpress command mode is very simple. The backspace erases characters, but no other editing is provided. Backspace operation requires vt100 terminal emulation or similar.
Many of the Bluetooth Xpress responses shown in the examples on this page were captured with system print level (sy p) = all, and system command header enabled (sy c h) = true. These settings are provided to make it easy for a host microcontroller to parse responses by examining response headers. See Serial Interface, Response Format.
Documentation for each command is provided in the format shown below.
A description of how to use the command, together with notes about available options and arguments.
Formal command syntax with a listing of all available options and arguments.
Alphabetical List of Commands
- adv --- advertise as a peripheral
- fac --- restore factory settings
- ver --- version
- wake --- exit sleep mode
Description of Commands
Advertise as a peripheral
Turn on advertising as a peripheral at the specified rate. The command
adv off turns advertising off. If no argument is supplied, the default is
On reset, advertising defaults to high for a duration specified by bl v h d (default: 30 seconds), then switches to low for a duration specified by bl v l d (default: always on), then turns off.
The advertising settings correspond to the following advertising modes.
high- High Duty Cycle Undirected Advertising
low- Low Duty Cycle Undirected Advertising
off- No Advertising
For more information, see the variables used to control advertising:
- bl v h d - advertising high mode duration
- bl v h i - advertising high mode interval
- bl v l d - advertising low mode duration
- bl v l i - advertising low mode interval
> adv [low | high | off]
> adv high Success
Deletes all bonding information from previously paired devices. All devices will need to complete a pairing procedure on their next connection. See Security.
Note: The bonding information must also be cleared on the previously paired devices. If this is not done, then pairing will fail on the next connection attempt! See Solving Connection Problems for more information.
Connect to a peripheral
Connect to a Bluetooth Xpress peripheral with the specified index number or BD address. The index number is obtained from the output of the scan command.
This command blocks until either a successful connection is made or the command times out. It then returns a status indicating success or failure.
The central can connect to only one peripheral at a time.
> con <index>|<BD_ADDRESS> [<timeout>]
<index>- the index obtained from the scan command output
<BD_ADDRESS>- the BLE device address of the Bluetooth Xpress peripheral
<timeout>optional - timeout in seconds before
concommand fails and returns error code "Timeout"
<timeout>range is 1 second to 1000 second. Default: 10 seconds
Return status is as follows:
|An argument is incorrect|
|The device already has a connection to a peripheral|
|Connection establishment timed out|
|Failure to start encryption due to bonding/pairing error|
> con 1 Success
Disconnect from peripheral or central
Closes any ongoing BLE connection.
> dct Success
Device Test Mode
Places the device into or out of Device Test Mode (DTM).
DTM can operate in the transmit or the receive direction. In transmit mode, the Bluetooth Xpress module's radio will continuously transmit Bluetooth packets at a fixed interval. A Bluetooth tester device should receive and analyze these packets. In receive mode, the Bluetooth Xpress module will continuously receive packets transmitted by a DTM tester device.
dtmcommand will stop advertising before entering DTM. If more time is needed to set up test equipment between the end of advertising and the beginning of DTM, the user can manually stop advertising with the
- A device cannot enter Device Test Mode if it has an active connection or is scanning.
- Upon exiting DTM, a device that was previously advertising will not
resume advertising. After sending
dtm stop, The user can issue the
adv lowcommand to resume advertising.
> dtm <operation> <direction> <channel> <phy> <packet type> <length>
<operation>- Operation to perform. May be one of the following values:
start: Start DTM
stop: Stop DTM
<direction>- Direction of the test. Only specified if operation is start. May be one of the following values:
rx: The module receives packets from the external Bluetooth tester device
tx: The module transmits packets to the external Bluetooth tester device
<channel>- Bluetooth channel to use in DTM. Only specified if operation is start. Must be an integer value in the range [0:39] designating the Bluetooth channel that will be used in DTM. The frequency can be derived from channel with:
F = ((2 * channel) + 2402) MHz
<phy>- PHY to use in DTM. Only specified if operation is start. May be one of the following values:
1m: 1M PHY
2m: 2M PHY
<packet type>- Packet type to transmit. Only specified if operation is start and direction is tx. May be one of the following values:
prbs9: PRBS9 packet payload
f0: 11110000 packet payload
aa: 10101010 packet payload
carrier: Unmodulated carrier
<length>- Packet length in bytes. Only specified if operation is start and direction is tx. Must be an integer value in the range [0:255]. Note: The length is ignored if packet type is set to carrier.
Start DTM in Rx mode. Puts the device in DTM receive mode on Bluetooth channel 10, with the 2M PHY.
> dtm start rx 10 2m Success
Start DTM in TX mode. Puts the device in DTM transmit mode on Bluetooth channel 39, with the 1M PHY, packet payload of all 0xF0, and packet length of 37 bytes.
> dtm start tx 39 1m f0 37 Success
Stop DTM. Stops the current DTM operation and take the device out of DTM.
dtm stop, the user can see how many packets were
transmitted/received while in DTM by reading the Test Mode Number of Packets
variable (tm n p).
> dtm stop Success > get tm n p 0
Restore factory settings
Performs a factory reset. Return variables to factory default settings by deleting user configuration (if present). See save.
To avoid accidental factory reset, the BD address of the module must be provided as an argument. Obtain the BD address with the get bl a command.
Note 1: The default bus mode may change after a factory reset. If you are
unable to communicate with the module with serial commands, it may be necessary
to toggle from
STREAM mode to
Note 2: Using this command will also cause the BGX to clear its internal bonding table. This means the BGX will forget all devices to which it previously connected. If the other device does not also clear its bonding information, this can cause a connection problem. See the section about solving connection problems for more information.
Factory reset deletes the entire user dynamic area, including user saved configurations.
> fac <BD_ADDRESS>
> get bl a 4C55CC129A42 > fac 4C55CC129A42 [COMMAND_MODE]
Set GPIO direction and pin mode
Sets the direction and pin mode for any of the general purpose I/O pins.
This command works on all pins configured with any function other than
reserved. Use the gfu command to select the pin function.
See GPIOs for more information.
To set multiple GPIO directions in a single command, see gdis.
To view the detailed pin mode set (gp u) =
> gdi <GPIO#> <direction> [<mode>] [<pull resistor>] [<drive strength>] [<debounce>]
<GPIO#>- The GPIO number
<direction>- Pin direction. Any one of the following types:
in: Input high impedance (for
ipd: Input with pull-down (for
ipu: Input with pull-up (for
olo: Output initialized to low value
ohi: Output initialized to high value
hiz: High impedance
inw: Input interrupt (for input functions other than
ipuw: Input interrupt with pull-up (for input functions other than
ipdw: Input interrupt with pull-down (for input functions other than
<mode>- Mode of the pin. Only available for output pins (
ohi). May be one of the following types:
pp: Push-pull (default value)
<pull resistor>- Pull resistor setting of the pin. Only be available for pins with mode
os. In open-drain mode, the resistor is pull-up. In open-source mode, it is pull-down. May be one of the following types:
pren: Pull resistor enabled (default value).
prdi: Pull resistor disabled.
<drive strength>- Drive strength of the pin. Only available for pins with mode
ospins can only use the strong drive strength. May be one of the following types:
drvst: Strong drive strength (10 mA) (default value)
drvwk: Weak drive strength (1 mA)
<debounce>- Debounce ticks. Only available for input interrupt
ipdwpins. Takes the following syntax:
db#: where # is a number between 0 to 9 that specifies the tick count. Ticks are ~20 msec. If 0, debounce is turned off. Otherwise, the input is debounced for an amount of time in the range:
[20 * ticks] msec : [(20 * ticks) + 10] msec
(default is db0)
> gfu 0 con_status_led Success > gdi 0 ohi od Success > gfu 2 str_select Success > gdi 2 ipuw db3 Success
Set direction for multiple GPIOs
Sets the direction for all GPIOs at once, using a list of settings. This command works
on all pins configured with any function other than
reserved. Use the
gfu command to select the pin function.
GPIO function pins typically only operate in one direction (in or out). In the case of
these uni-directional function pins, this command will fail if it attempts to switch the
direction of the pin.
stdio pins are an exception to this as they are always bi-directional.
The list is a string with a single digit representing the direction for each GPIO, with the GPIO 0 direction at the left.
Directions are enumerated as shown in the table below:
|Enumerator||I/O Type Description|
|0||Input, with pull-up (see gdi |
|1||Input, pull-down (see gdi |
|2||Input, high-impedance (see gdi |
|4||Output, open-drain with no pull-up (see gdi |
|5||Output, open-drain with pull-up (see gdi |
|6||For any function other than |
|7||Output, open-source with no pull-up (see gdi |
|8||Output, open-source with pull-up (see gdi |
|X||Do nothing. Acts as a placeholder for pins that should not be modified.|
Drive strength cannot be set with this command. In order to set drive strength to weak, the gdi command must be used individually for each pin.
There must be exactly one enumerated value for each GPIO. For a GPIO you do not wish to modify, use the placeholder value
X. Supplying the wrong number of values results in an
To reset all GPIOs set to
none, supply the value
6 for every GPIO. For example:
To set and get multiple GPIO values, see gses and gges. To set individual GPIO function, direction and value, see gfu, gdi, gse and gge. To view a list of GPIO functions, use the command get gp u.
> gdis <value list>
> gdis 66666666 Success > gges XXXXXXXX
Get the value of a variable
Get the value of the specified variable.
> get <variable>
> get ua b 115200
Select GPIO function
Configure a GPIO with the specified function. A function may only be assigned
to a pin that has a function set to
none i.e. the pin is not already assigned.
A list of available functions is shown in the following table.
|O||con_active||Asserts when BLE is connected and encrypted. (active high)|
|O||con_active_n||Asserts when BLE is connected and encrypted. (active low)|
|O||con_status_led||Blinks when BLE is connected and encrypted. The blink pattern is controlled with the sy i s variable.|
|O||str_active||Asserts when BLE is connected, encrypted, and stream mode is active. (active high)|
|O||str_active_n||Asserts when BLE is connected, encrypted, and stream mode is active. (active low)|
|O||str_activity_led||Asserts when BLE is connected, encrypted, and stream mode data is being transmitted or received.|
|I||str_select||Input selects bus serial mode.|
Depending on setting of variable: bu s c (bus serial control) as edge or level,
--- mode toggles on rising edge
--- low level - COMMAND_MODE
--- high level - STREAM_MODE
|I||sleep_select||Active low input that forces the module into sleep mode when asserted and wakes the module from sleep when de-asserted.|
|I||ufu_level||User function event trigger. See uevt command.|
|I/O||stdio||User controlled GPIO.|
Note: Each function except for
ufu_level may be assigned to
only one pin at any time.
See also: gdi, gge, gse, bu s c, gpu, GPIOs
> gfu <GPIO#> <function>
> gfu 6 none Success > gfu 6 str_select Success
Get GPIO value
Get the current value of a general purpose I/O pin configured for the
function. See GPIOs.
> gge <GPIO#>
> gge 5 1
Get multiple GPIO values
Get a list of values for all GPIOs at once.
For GPIOs not set to a
stdio function, the placeholder is
X. The GPIO 0
value is at the left.
To configure GPIO function and direction, see the gfu, gdi, and gdis commands. To view a list of GPIO functions, use the get gp u command. To set the values of STDIO GPIOs, see gses and gse.
> gges XXXXXXX1
Set GPIO value
Immediately set the value of a general purpose I/O pin. When setting a GPIO, the GPIO direction must be set correctly, using the GPIO direction command gdi, or the command will fail. See GPIOs.
> gse <GPIO#> <value>
> gse 2 0 Success > gge 2 0
Set multiple GPIO values
Set the value for all GPIOs at once, using a list of settings.
The list is a string with a single digit representing the value for each GPIO, with the GPIO 0 setting at the left.
The command can set the value only for GPIOs that have been configured with a
stdio function and
output direction. Values for GPIOs not set to a
function are placeholders and have no effect.
Note: There must be exactly one character for each GPIO. For a GPIO set to
a STDIO output function, the character must be
1. For other GPIOs you
can use any character as a placeholder. Supplying the wrong number of values
results in an
Invalid argument response.
For example, to configure GPIO 1 as a push-pull output and drive it high, use the following commands:
gfu 1 stdio gdis 63666666 gses X1XXXXXX
To configure GPIO function and direction, see the gfu, gdi, and gdis commands. To view a list of GPIO functions, use the get gp u command. To get the values of STDIO GPIOs, see gges and gge.
> gses <GPIO values>
> gfu 1 stdio Success > gdis 63666666 Success > gses X1XXXXXX Success > gges X1XXXXXX
Change remote peripheral bus mode
Change the bus mode of a remote Bluetooth Xpress module operating as a peripheral. The
rbmode command enables a Bluetooth Xpress module operating as a central (and connected to
a remote peripheral) to :
- read the bus mode of the remote peripheral
- set the bus mode of the remote peripheral by changing the BLE
modecharacteristic of the remote
If the bus mode of the remote peripheral is set to remote COMMAND mode, the remote peripheral device can be controlled as if it was a local device. To control the remote peripheral, the controlling module connects as a central to the (remote) peripheral and then:
rbmode remoteto set the bus mode of the remote peripheral to remote COMMAND mode
- switches itself to
streammode, either with the
str_selectGPIO (see gfu), or by issuing the the str command
- issues one or more commands to the remote peripheral as a stream, and reads the response(s)
For information on bus modes, see Serial Bus Modes, Serial Interface.
For a description of remote command mode, see BLE Services, Xpress Streaming Service.
For a demonstration of remote control of a Bluetooth Xpress module, see the Bus Mode Selection and Remote Control application note.
- The bus mode of the remote peripheral device cannot be changed to
local COMMAND modeusing
- The remote device must have remote access enabled. See sy r e
> rbmode [stream | remote]
Read the bus mode of a remote peripheral (returns the value of the BLE
characteristic of the remote peripheral).
> rbmode stream
Set the bus mode of a remote peripheral to remote COMMAND mode.
> rbmode remote Success
Restart the device
Reboot the application. After reboot, the bus serial mode is displayed between square brackets.
> reboot [COMMAND_MODE] > set bu i stream Success > save Success > reboot [STREAM_MODE]
Save the current user configuration value of all variables to non-volatile flash memory. After save completes, user configuration variable settings are automatically loaded on reboot.
Save user configuration.
> save Success
Scan for nearby Bluetooth Xpress peripherals
Scan for nearby BGX peripherals. Scan mode may be
determines the scan rate. If no scan mode argument is supplied, the default is
high. Scan intervals and configuration are defined by
ce s h d, ce s h i,
ce s l d, and ce s l i.
For peripherals in range, the scan details are listed with an index number and an address. The index number is used with the con command to connect to the peripheral.
Scanning only detects peripherals that are advertising the Bluetooth Xpress Streaming Service UUID. Each device detected during scanning is listed only once in the scan results.
scan off to turn off scanning immediately.
The scan command asynchronously sends scan results to the serial interface. If the system print level sy p >= 3, asynchronous messages are shown and responses indicating a device is detected may be interleaved with subsequent commands and responses.
To prevent asynchronous scan results appearing, set sy p < 3
scan results to view results.
> scan [low | high | off | results]
scan scan low scan high scan off scan results
scan high ! # RSSI BD_ADDR Device Name # 1 -46 4C:55:CC:1a:3d:df Device1 # 2 -46 4C:55:CC:1a:30:1f Device2
Set the value of a variable
Sets the value of the specified variable. See the variable documentation for details of valid arguments.
> set <variable> <args>
> set sy c e 0 Success
Enter sleep mode
Put the module into the lowest-power sleep state. The module sleeps until a
wakeup event occurs such as an interrupt on the
See Power Management.
> sleep Success
Switch to serial bus STREAM mode.
For information on bus modes, see Serial Bus Modes, Serial Interface.
For a description of the Xpress Streaming Service, see BLE Services, Xpress Streaming Service. For information about using a mobile app to control and monitor a Bluetooth Xpress module, see the BGXpress Mobile Framework.
> str STREAM_MODE
Initializes UART with new UART-related settings. This command can be used to change UART settings at runtime without a device reset. When this command is executed, UART-settings stored in the Bluetooth Xpress module will take effect.
> uartu Success
Assigns an event trigger to run a user function. To view a list of user functions and events, use the command get uf u.
For a pin to be a trigger for a user function, it must be set to function
ufu_level with the gfu command.
> uevt <UFN#> <event> [<GPIO#>]
<UFN#>- User function number that will be triggered by this event.
<event>- Event that will trigger execution of the user function.
hi: Input pin asserted high
lo: Input pin asserted low
<GPIO#>- The GPIO number that generates this event.
> gfu 7 ufu_level Success > uevt 0 lo 7 Success
Assigns an arbitrary command string to the indicated user function. To view a list of user functions and events, use the command get uf u.
> ufu <UFN#> [<command string>]
<UFN#>- User function number that is being assigned.
[<command string>]- Any command that can be entered through the console. The command may contain spaces. If empty, the UFN# is erased.
> ufu 0 con 90FD9F05F608 Success
Last user function result
Displays the results from the last user function executed.
> ufu 0 con 90FD9F05F608 Success > urun 0 > ulast Timeout
Run a user function
Runs the specified user function. Used to test that the command string was entered correctly.
> urun <UFN#>
<UFN#>- User function number that will be executed.
> ufu 1 clrb Success > urun 1 Success
Returns the Bluetooth Xpress product name, version and other build information.
This is the command equivalent of the sy v variable.
> ver BGX18.104.22.1680.1-880-880
Exit sleep mode
Wakes the module from sleep mode.
Note: This command is only available if the UART baud rate (ua b)
is set to 9600 or less. This is because the UART is disabled in sleep mode at
higher baud rates. See Power Management.
> wake Success