docs.silabs.

com
BGX13-1.x Command Reference
search This page provides a list of Bluetooth Xpress API commands with a full
description of how to use each command.

General Overview Command Editing

Getting Started
The Bluetooth Xpress command mode is very simple. The backspace erases
characters, but no other editing is provided.
Configuration and Setup
Backspace operation requires
vt100 terminal emulation or similar.
Serial Interface
BGX-1.x
BLE Services

BLE Advertising Documentation Format

Security

GPIOs 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
Bus Mode Selection
parse responses by
examining response headers. See Serial Interface, Response
Format.
Power Management
Documentation for each command is provided in the format shown below.
Throughput

Firmware Update command

Frequently Asked Questions Brief description

Command API Reference Description

Commands
A description of how to use the command, together with notes about available
options and arguments.
Variables
Syntax
Application Examples
Formal command syntax with a listing of all available options and arguments.
BGX to Phone
Example
BGX to BGX
Xpress Connect and User Functions Example usage.

I2C

Revision History Alphabetical List of Commands

Document Revisions

Release Notes A
adv --- advertise as a peripheral
BGXpress Host Software C
Overview clrb --- clear bonding information
Commander Overview con --- connect to a peripheral
D
Android
dct --- disconnect from peripheral or central
iOS dtm --- direct test mode
F
More Documentation fac --- restore factory settings
G
gdi --- set GPIO direction and pin mode (stdio)
gdis --- set direction for multiple GPIOs
get --- get the value of a variable
gfu --- select GPIO function
gge --- get GPIO value (stdio)
gges --- get multiple GPIO values
gse --- set GPIO value (stdio)
gses --- set multiple GPIO values
I
i2crd --- read I2C data
i2cwr --- write I2C data
R
rbmode --- change bus mode of a remote peripheral
reboot --- restart the device
rssi --- display RSSI value for the current connection
S
save --- save configuration variables
scan --- scan for nearby Bluetooth Xpress peripherals
send --- send data to the remote device via the STREAM bus mode
set --- set the value of a variable
sleep --- enter sleep mode
str --- switch to stream mode
U
 uartu --- restart UART with new baud rate and flow control settings
uevt --- assign event trigger to run a user function
ufu --- set the value of a user function
ulast --- display results from last user function run
urun --- run requested user function
V
ver --- version
W
wake --- exit sleep mode

Description of Commands

adv
Advertise as a peripheral

Version Notes

Starting with version 1.1.1229.0 , advertising is performed on the BLE PHY(s)

determined by bl p m and bl p p.

Added xpr argument in 1.2.2045.0 .

Description

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
adv high .

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.

When the adv xpr command is issued, the BGX will initiate Xpress mode
advertising. It does this by advertising in Limited
Discoverable Mode (all
other advertising modes advertise in General Discoverable Mode). Xpress mode
advertising can be used to
uniquely identify a specific BGX13 for connection.
For example, a button press could be used to initiate Xpress mode advertising
on a BGX device, and a central device could then distinguish that BGX from any
other BGX that may be advertising in the vicinity.
Xpress mode advertising
advertises at interval bl v x i for duration
bl v x d. Once the bl v x d
duration expires, the device stops
advertising.

The advertising settings correspond to the following advertising modes.

high - High Duty Cycle Undirected Advertising

low - Low Duty Cycle Undirected Advertising
xpr - Xpress Mode 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
bl v x d - advertising xpress mode duration
bl v x i - advertising xpress mode interval

Syntax

> adv [low | high | xpr | off]

Example

> adv high

Success

clrb
Clear bonding information

Version Notes

Optional parameters added in 1.1.1229.0

Description

Deletes existing bonding information for the specified BLE device address or
for all previously bonded devices. All cleared and new
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
bonded devices. If this is not done, then pairing will likely
fail on the next
connection attempt! See Solving Connection Problems
for more information.

Syntax

clrb [all | <BD_ADDRESS>]

where:

all (or no parameter) - deletes bonding information for all previously paired
devices
<BD_ADDRESS> - deletes bonding information for this BLE device address only

Example

> clrb D0CF5E828EF4

Success
> clrb
Success

con
Connect to a peripheral

Version Notes

Starting with version 1.1.1229.0 , the BLE PHY used to initiate a connection
is determined by bl p p.

Added xpr , <name> , and params arguments in 1.2.2045.0 .

Description

Connect to a Bluetooth Xpress peripheral by providing one of the following:

Index number returned from the scan command

BD address
The name of the target BGX peripheral
The xpr keyword. If provided, the device will connect to the first
Bluetooth Xpress peripheral it finds that is in Xpress advertising mode
(see
adv).

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.

Syntax 1

> con <index> | <BD_ADDRESS> | <name> | xpr [<timeout>]

where:

<index> - the index obtained from the scan command output

<BD_ADDRESS> - the BLE device address of the Bluetooth Xpress peripheral
<name> - the name of the Bluetooth Xpress peripheral (configured via
sy d n)
xpr - scan and connect to the first Bluetooth Xpress peripheral found that
is advertising with adv xpr
<timeout> optional - timeout in seconds before con command fails and
returns error code "Timeout"
<timeout> range is 1 second to 1000
second. Default: 10 seconds

Return status is as follows:

Status Description

Invalid argument An argument is incorrect

Command failed The device already has a connection to a peripheral

Timeout Connection establishment timed out

Security mismatch Failure to start encryption due to bonding/pairing error

Examples

Connect to the device in the scan table with index 1.

> con 1
Success

Connect to the device with address D0CF5E828EF4. Set connection timeout to 5

seconds.

> con D0CF5E828EF4 5

Success
 Connect to the device named MY_BGX.

> con MY_BGX

Success

Connect to the first Bluetooth Xpress peripheral found in Xpress advertising

mode (adv xpr).

> con xpr

Success

Syntax 2

A second syntax is available for acquiring the connection parameters of an

active connection:

> con params

returns:

Addr - BLE Address (bl a) of the connected device

Itval - BLE Connection Interval (bl c i) of the
connection
Mtu - MTU size of the connection
Phy - Active Phy setting (bl p p) of the connection
Tout - BLE Connection Supervision Timeout (bl c t) of
the connection
Err - The last error code returned in response to a BLE operation (see
Error Codes for a
list of error codes)

If con params is issued when there is not an active connection, it will return
only the Err parameter in response.

Example

> con params

! Param Value
# Addr D0CF5E828DF6
# Itvl 12
# Mtu 250
# Phy 1m
# Tout 400
# Err 0000

dct
Disconnect from peripheral or central

Description

Closes any ongoing BLE connection.

Syntax

> dct

Example

> dct
Success

dtm
Direct Test Mode

Version Notes

Added PHY arguments 125k and 500k in 1.1.1229.0

Description

Places the device into or out of Direct 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.

Notes

The dtm command 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
adv off command.
A device cannot enter Direct 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 high or adv low command to resume advertising.

Syntax

> dtm <operation> <direction> <channel> <phy> <packet type> <length>

where:

<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
125k : Coded PHY(S=8)
500k : Coded PHY(S=2)

<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
pn9 : PN9
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.

Example 1

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

Example 2

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

Example 3

Stop DTM. Stops the current DTM operation and take the device out of DTM.
After sending 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

fac
Restore factory settings

Description

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 COMMAND mode.

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.

Syntax

> fac <BD_ADDRESS>

Example

> get bl a
4C55CC129A42
> fac 4C55CC129A42
[COMMAND_MODE]

gdi
Set GPIO direction and pin mode

Description

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
none or 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) = verbose .

Syntax

> gdi <GPIO#> <direction> [<mode>] [<pull resistor>] [<drive strength>] [<debounce>]

where:

<GPIO#> - The GPIO number

<direction> - Pin direction. Any one of the following types:

in : Input high impedance (for stdio only)

ipd : Input with pull-down (for stdio only)
ipu : Input with pull-up (for stdio only)
olo : Output initialized to low value
ohi : Output initialized to high value
hiz : High impedance
inw : Input interrupt (for input functions other than stdio )
ipuw : Input interrupt with pull-up (for input functions other than stdio )
ipdw : Input interrupt with pull-down (for input functions other than stdio )

<mode> - Mode of the pin. Only available for output pins ( olo or ohi ).
May be one of the following types:

pp : Push-pull (default value)

od : Open-drain
os : Open-source

<pull resistor> - Pull resistor setting of the pin. Only be available for
pins with mode od or 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 pp or od . os pins 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 inw ,

ipuw or ipdw pins. 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)

Example
 > gfu 0 con_status_led
Success
> gdi 0 ohi od
Success
> gfu 2 str_select
Success
> gdi 2 ipuw db3
Success

gdis
Set direction for multiple GPIOs

Version Notes

For versions previous to 1.1.1229.0 , calling 'gdis' with any value other than
6 or X for a pin configured as none results in an
error. The pin must
first be configured as stdio with the gfu command.

Description

Sets the direction for all GPIOs at once, using a list of settings.

If a GPIO is configured as none , this command will set it as 'stdio' (unless

the value '6' or 'X' is used for that pin).

If a GPIO is configured as any function other than none or reserved , this

command wil not change its function but will change it
direction.

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 ipu )

1 Input, pull-down (see gdi ipd )
2 Input, high-impedance (see gdi in )
3 Output, push-pull
4 Output, open-drain with no pull-up (see gdi od prdi )
5 Output, open-drain with pull-up (see gdi od pren )
6 For any function other than none or reserved , the GPIO is set to none . Otherwise do nothing.
7 Output, open-source with no pull-up (see gdi os prdi )
8 Output, open-source with pull-up (see gdi os pren )
X Do nothing. Acts as a placeholder for pins that should not be modified.

Notes:

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 Invalid argument response.

To reset all GPIOs set to none , supply the value 6 for every GPIO. For
example:

gdis 66666666

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.

If there is an invalid setting for any pin in the list of direction values,
the command fails without configuring any pins, including
those for which a
valid setting was given.

Syntax

> gdis <value list>

Example

> gdis 66666666

Success
> gges
XXXXXXXX
get
Get the value of a variable

Description

Get the value of the specified variable.

Syntax

> get <variable>

Example

> get ua b
115200

gfu
Select GPIO function

Version Notes

i2cm_scl and i2cm_sda added in 1.2.2045.0

Description

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.

I/O Function Description

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 i2cm_scl I2C SCL pin for I2C master operations. (i2crd and i2cwr commands)
O i2cm_sda I2C SDA pin for I2C master operations. (i2crd and i2cwr commands)
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.
If str_select is configured, bus mode selection is manual. If str_select not configured, bus mode
selection is automatic. See Serial Interface.
Depending on setting of variable: bu s c (bus serial control) as edge or level, str_select works as follows:
edge:
--- mode toggles on rising edge
level:
--- 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 deasserted.
I ufu_level User function event trigger. See uevt command.
I/O stdio User controlled GPIO.

Note: Each function except for stdio and ufu_level may be assigned to
only one pin at any time.

See also: gdi, gge, gse, bu s c,

gpu, GPIOs

Syntax

> gfu <GPIO#> <function>

Example

> gfu 6 none

Success
> gfu 6 str_select
Success
gge
Get GPIO value

Description

Get the current value of a general purpose I/O pin configured for the stdio
function. See GPIOs.

Syntax

> gge <GPIO#>

Example

> gge 5
1

gges
Get multiple GPIO values

Description

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.

Syntax

> gges

Example

> gges
XXXXXXX1

gse
Set GPIO value

Description

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.

Syntax

> gse <GPIO#> <value>

Example

> gse 2 0
Success
> gge 2
0

gses
Set multiple GPIO values

Description

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 stdio
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 0 or
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.

Syntax

> gses <GPIO values>

Example

> gfu 1 stdio

Success
> gdis 63666666
Success
> gses X1XXXXXX
Success
> gges
X1XXXXXX

i2crd
Reads I2C data from a given I2C slave address

Version Notes

Added in 1.2.2045.0

Description

The device acts as the I2C master. The read operation can take one of two
formats:

If <addr> is supplied, the read will be a combined write/read sequence. This

operation type is useful for accessing a register
address or memory address on
an I2C slave. Otherwise, the read will be a plain read sequence.

The speed of the I2C bus is configured by i2 b s.

If the read operation does not complete within 3 seconds, the command will fail
with return value Timeout .

Syntax

> i2crd [hex | bin] <slv_addr> <addr> <len>

where:

[hex | bin] optional - Data format of <slv_addr> , <addr> and the

received data. If not supplied, default is hex .
bin - <slv_addr> , <addr> , and the received bytes are represented as
binary. Characters that cannot be expressed in ASCII can be
expressed via
escape sequence. See escape sequence documentation in the
send command.
hex - <slv_addr> , <addr> , and the received bytes are represented as a
hex string. Each byte in the hex string must be exactly two
characters
long (e.g. a value of 1 must be expressed as 01 , not 1 ).
<slv_addr> - I2C address of the slave. <slv_addr> is expressed in 8 bits
by left-justifying (or multiplying by 2) the 7-bit slave address.
The
least-significant bit of <slv_addr> is ignored.
<addr> optional - Register or memory address from which data will be read.
If not supplied, the read operation will be a plain read
sequence. Maximum
length is 8 bytes.
<len> - Length of received data. Must be expressed as a decimal integer.
Range is 1 to 64 bytes.

Return status is as follows:

 Status Description

Invalid An argument was incorrect

argument

Too few args The minimum number of arguments was not provided

Timeout The I2C operation did not complete within 3 seconds

Command The I2C operation failed for some other reason. (This status is returned if i2cm_sda and i2cm_scl have not been
failed assigned to a pin via gfu.)
Success The I2C operation completed successfully

Example 1

Both commands below read 10 bytes , with the values [0x61, 0x62, 0x63, 0x64,
0x65, 0x66, 0x67, 0x68, 0x69, 0x6A], from I2C slave
at address 0x40
(non-shifted address: b' 010 0000):

> i2crd 40 10
6162636465666768696A

> i2crd bin @ 10

abcdefghij

Example 2

Both commands below read 5 bytes, with the values [0x50, 0x51, 0x52, 0x53,
0x54], from register address 0x0A at I2C slave at
address 0xA0 (non-shifted
address: b' 101 0000):

> i2crd A0 0A 5
5051525354

> i2crd bin \xA0 \n 5

PQRST

i2cwr
Writes I2C data from a given I2C slave address

Version Notes

Added in 1.2.2045.0

Description

The device acts as the I2C master. The write operation can take one of two
formats:

If <addr> is supplied, the write will be a combined write/write sequence. This

operation type is useful for accessing a register
address or memory address on
an I2C slave. Otherwise, the write will be a plain write sequence.

The speed of the I2C bus is configured by i2 b s.

If the write operation does not complete within 3 seconds, the command will fail
with return value Timeout .

Syntax

> i2cwr [rst] [hex | bin] <slv_addr> <addr> <data>

where:

[rst] - Forces a reset of the I2C bus. If supplied, all other arguments are
ignored.
[hex | bin] optional - Data format of <slv_addr> , <addr> , and <data> .
If not supplied, default is hex .
bin - <slv_addr> , <addr> , and <data> are represented as binary.
Characters that cannot be expressed in ASCII can be expressed
via escape
sequence. See escape sequence documentation in the
send command.
hex - <slv_addr> , <addr> , and <data> are represented as a hex
string. Each byte in the hex string must be exactly two characters
long
(e.g. a value of 1 must be expressed as 01 , not 1 ).
 <slv_addr> - I2C address of the slave. <slv_addr> is expressed in 8 bits
by left-justifying (or multiplying by 2) the 7-bit slave address.
The
least-significant bit of <slv_addr> is ignored.
<addr> optional - Register or memory address to which data will be written.
If not supplied, the write operation will be a plain write
sequence. Maximum
length is 8 bytes.
<data> - Data to send. The most amount of data that can be sent in one write
operation is 64 bytes.
Note: Depending on the format of the data, it may not be possible to fit
64 bytes into the command line.

Return status is as follows:

Status Description

Invalid An argument was incorrect

argument

Too few args The minimum number of arguments was not provided

Timeout The I2C operation did not complete within 3 seconds

Command The I2C operation failed for some other reason. (This status is returned if i2cm_sda and i2cm_scl have not been
failed assigned to a pin via gfu.)
Success The I2C operation completed successfully

Example 1

Both commands below write 16 bytes, with the values [0x20, 0x21, 0x22, 0x23,
0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x2B,
0x2C, 0x2D, 0x2E, 0x2F], to the
I2C slave at address 0x30 (non-shifted address: b' 001 1000):

> i2cwr 30 202122232425262728292A2B2C2D2E2F

Success

> i2cwr bin 0 \s!"#$%&'()*+,-./

Success

Example 2

Both commands below write 4 bytes, with the values [0x7A, 0x7B, 0x7C, 0x7D], to
register address 0x02F0 at I2C slave at address
0xEA (non-shifted address: b' 111 0101):

> i2cwr EA 02F0 7A7B7C7D

Success

> i2crd bin \xEA \x2\xF0 z{|}

Success

rbmode
Change remote peripheral bus mode

Version Notes

The password feature was added in version 1.2.2045.0 .

Description

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 mode
characteristic 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:

issues rbmode remote to set the bus mode of the remote

peripheral to remote COMMAND mode
switches itself to stream mode, either with the str_select GPIO (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)

If the remote command mode of the peripheral is protected via password, the
password must be provided as a parameter:

> rbmode remote 123456

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.

Notes:
 The bus mode of the remote peripheral device cannot be changed to local
COMMAND mode using rbmode .
The remote device must have remote access enabled. See
sy r e

Syntax

> rbmode [stream | remote] [<password>]

where <password> is a string matching the System Remote Password

(sy r p) of the remote device

Example 1

Read the bus mode of a remote peripheral (returns the value of the BLE mode
characteristic of the remote peripheral).

> rbmode
stream

Example 2

Set the bus mode of a remote peripheral to remote COMMAND mode.

> rbmode remote

Success

Example 3

Set the bus mode of a remote peripheral on which sy r p

is 'my_password' to remote COMMAND mode.

> rbmode remote my_password

Success

reboot
Restart the device

Description

Reboot the application. Use the dfu parameter to reboot in the UART-DFU
bootloader mode. If no parameters are specified, the
device will reboot in
the main application mode.

Using the dfu parameter has the same effect as holding the BOOT pin low
during a hardware reset.

Note:

Applications that require to communicate with the UART-DFU bootloader mode

should use the dfu parameter.

Syntax

> reboot [dfu]

Example 1

> reboot
[COMMAND_MODE]
> set bu i stream
Success
> save
Success
> reboot
[STREAM_MODE]

Example 2

> reboot dfu

(possible stray characters, device is in boot loader mode)

rssi
Display RSSI value for the current connection

Version Notes

Added in 1.1.1229.0
 Description

Returns the RSSI value from the latest received packet of the current active
connection. The returned value will range from -127 to
+20 and the units are
dBm. The command will return a failure if there is no active connection.

When this command is used via a serial connection, the RSSI value is the
signal strength of the remote device as received by the
local device. If the
remote device is also a BGX13, it is possible to read the remote RSSI value by
placing the remote device into
remote command mode,
and then issuing the rssi command.

Syntax

rssi

Example

> rssi
-43

save
Save variables

Description

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.

Syntax

> save

Example

Save user configuration.

> save
Success

scan
Scan for nearby Bluetooth Xpress peripherals

Version Notes

Starting with version 1.1.1229.0 , the BLE PHY used for scanning is determined
by bl p p.

Added xpr and <threshold> arguments in 1.2.2045.0 .

Description

Scan for nearby BGX peripherals. Scan mode may be low or high , which
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.

Issue scan off to turn off scanning immediately.

Issue scan xpr to scan only for BGX devices which are in Xpress advertising
mode (i.e. adv xpr). A scan xpr operation scans at
interval
ce s h i for duration ce s h d.
When the duration specified by ce s h d has elapsed, it
stops scanning.

scan accepts an optional <threshold> argument. When a threshold is

specified, found devices will only be added to the scan
table if their RSSI
meets or exceeds the threshold.

<threshold> range is -127dBm to 20dBm. 'dBm' must be included in the command

line argument for the argument to be
recognized as an RSSI threshold value.

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

and issue scan results to view results.

Syntax
 > scan [low | high | xpr | off | results] [<threshold>]

Examples:

scan
scan low
scan high
scan xpr
scan off
scan results
scan high -20dBm

Example

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

send
Send STREAM data

Version Notes

Added in 1.2.2045.0 .

Description

Sends data to the remote device via the STREAM bus mode.

Issuing the following command in local COMMAND mode:

send Hello!

is equivalent to entering STREAM bus mode and sending:

Hello!

The device must have an active BLE connection for this command to succeed. If
there is not an active BLE connection, it returns
"Command failed".

Syntax

> send <string>

where:

<string> - The string to send to the remote device via STREAM bus mode.
Maximum length is 64 characters.

If <string> includes spaces, the entire string must be surrounded by quotation

marks. Otherwise, each word in <string> will be
seen as a separate argument
and the command will fail with "Too many args".

Escape Sequences

Because <string> is an argument to the send command, it is not

treated like binary data and it can be impossible to send
certain values.
In order to overcome this limitation, <string> may contain C-style escape
sequences. The supported escape
sequences are:

\a - Alert
\b - Backspace
\e - Escape Character
\f - Formfeed Page Break
\n - Newline
\r - Carriage Return
\s - Space
\t - Horizontal Tab
\v - Vertical Tab
\\ - Backslash
\" - Double Quotation Mark (Double quotation marks will cause errors with
the BGX console if the string also includes spaces. Users
can get around this
by using \s instead of spaces in a string that includes double quotation
marks.)
\0 - NULL
\x - Hex value. The \x must be followed by one or two digits representing
the hex value. (e.g. \x0\x80\xff )

Examples

Send "Hello" to the remote device.

 > send Hello
Success

Send "Hello World" to the remote device.

> send "Hello World."

Success

Send "Hello World" with carriage return and newline to the remote device.

> send "Hello World.\r\n"

Success

Send the binary data [0x00, 0x01, 0x02, 0x7F, 0x80, 0xFF] to the remote device.

> send "\x0\x1\x2\x7f\x80\xff"

Success

Send "GPIO 2 pulled low.\r\n" to the remote device each time GPIO 2 is pulled
low.

> gfu 2 ufu_level

Success
> ufu 0 send "GPIO 2 pulled low.\r\n"
Success
> uevt 0 lo 2
Success

set
Set the value of a variable

Description

Sets the value of the specified variable. See the variable

documentation for details of valid arguments.

Syntax

> set <variable> <args>

Example

> set sy c e 0
Success

sleep
Enter sleep mode

Description

Put the module into the lowest-power sleep state. The module sleeps until a
wakeup event occurs such as an interrupt on the
sleep_select GPIO.
See Power Management.

Syntax

> sleep

Example

> sleep
Success

str
Stream mode

Description

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.

Syntax

> str

Example

> str
STREAM_MODE

uartu
UART initialization

Description

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.

Syntax

> uartu

Example

> set ua b 115200

Success
> uartu
Success

uevt
User event

Version Notes

Starting with version 1.2.2045.0 , multiple user functions can be assigned to

the same event trigger on the same ufu_level
input pin. Additionally, the
following new events were added: hi_long , hi_short , lo_long , lo_short ,
any , boot , con , dct .

Description

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.

It is possible to assign multiple user functions to the same event trigger on

the same ufu_level input pin. See the last example
in the Examples section
for an example of how this works.

Only one user function can be assigned to each of the boot , con , and dct
event triggers.

Syntax

> uevt <UFN#> <event> [<GPIO#>]

where:

<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

hi_long : Input pin asserted high and stays high for at least
uf l p * 100 milliseconds
hi_short : Input pin asserted high and then asserted low. Total high
time is less than uf l p * 100 milliseconds.
lo : Input pin asserted low
lo_long : Input pin asserted low and stays low for at least
uf l p * 100 milliseconds.
lo_short : Input pin asserted low and then asserted high. Total low
time is less than uf l p * 100 milliseconds.
any : Input pin asserted high or asserted low
boot : Device boot-up
con : Device connected to remote BLE device
dct : Device disconnected from remote BLE device

<GPIO#> - The GPIO number that generates this event. When configuring the
boot , con , and dct events, this argument
should be omitted as those
event types are not associated with a GPIO.
 Examples

Trigger dct when GPIO 7 goes low.

> gfu 7 ufu_level

Success
> ufu 0 dct
Success
> uevt 0 lo 7
Success

Trigger adv xpr on a short-press of GPIO 2 and con xpr on a

long-press of GPIO 2.

> gfu 2 ufu_level

Success
> ufu 0 adv xpr
Success
> uevt 0 lo_short 2
Success
> ufu 1 con xpr
Success
> uevt 1 lo_long 2
Success

Trigger con MY_BGX the first time GPIO 2 goes low; then trigger
dct the second time GPIO 2 goes low. A third low event on GPIO 2
will
trigger con MY_BGX again.

gfu 2 ufu_level
Success
ufu 0 con MY_BGX
Success
uevt 0 lo 2
Success
ufu 1 con MY_BGX
Success
uevt 1 lo 2
Success

ufu
User function

Description

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.

Syntax

> ufu <UFN#> [<command string>]

where:

<UFN#> - User function number that is being assigned.

[<command string>] - Any command that can be entered through the console.
The command may contain spaces. Maximum length is
24 characters. If empty,
the UFN# is erased. Commands that print text to the console (e.g.,
get al) will not print their output when invoked
as a user
function via ufu. To view the output of the command, use the command
ulast.

Example

> ufu 0 con 90FD9F05F608

Success

ulast
Last user function result

Description

Displays the results from the last user function executed.

Syntax

> ulast

Example
 > ufu 0 con 90FD9F05F608
Success
> urun 0
> ulast
Timeout

urun
Run a user function

Description

Runs the specified user function. Used to test that the command string was
entered correctly.

Syntax

> urun <UFN#>

where:

<UFN#> - User function number that will be executed.

Example

> ufu 1 clrb

Success
> urun 1
Success

ver
Version

Description

Returns the Bluetooth Xpress product name, version and other build information.

This is the command equivalent of the sy v variable.

The following table shows the meaning of the fields in the version string:

Field Example Meaning

App version 1.0.880.1 Overall version of BGX13 firmware, includes build number
Boot loader build -1229 Boot loader unique build number
App build number -880 BGX13 application unique build number

Notes:

The application build number embedded in the overall version usually

matches the value of the third field (App build number - 880 in the
above
example).
It is normal for the application build number and the boot loader build
number to be different.

Syntax

ver

Example

> ver
BGX13.1.0.880.1-1229-880

wake
Exit sleep mode

Description

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

> wake

Example

> wake
Success

Did you find this useful?

Yes No

Copyright © 2021 Silicon Laboratories. All rights reserved.