BGX13-1.x Command Reference
This page provides a list of Bluetooth Xpress API commands with a full description of how to use each command.
Command Editing
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.
Documentation Format
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.
command
Brief description
Description
A description of how to use the command, together with notes about available options and arguments.
Syntax
Formal command syntax with a listing of all available options and arguments.
Example
Example usage.
Alphabetical List of Commands
-
A
- adv --- advertise as a peripheral
- C
- D
-
F
- fac --- restore factory settings
- G
- I
- R
- S
- U
-
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 beforecon
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 theadv 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 theadv high
oradv 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 (forstdio
only) -
ipd
: Input with pull-down (forstdio
only) -
ipu
: Input with pull-up (forstdio
only) -
olo
: Output initialized to low value -
ohi
: Output initialized to high value -
hiz
: High impedance -
inw
: Input interrupt (for input functions other thanstdio
) -
ipuw
: Input interrupt with pull-up (for input functions other thanstdio
) -
ipdw
: Input interrupt with pull-down (for input functions other thanstdio
)
-
-
<mode>
- Mode of the pin. Only available for output pins (olo
orohi
). 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 modeod
oros
. 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 modepp
orod
.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 interruptinw
,ipuw
oripdw
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 anInvalid 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 ishex
.-
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 as01
, not1
).
-
-
<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 argument
|
An argument was incorrect |
Too few args
|
The minimum number of arguments was not provided |
Timeout
|
The I2C operation did not complete within 3 seconds |
Command failed
|
The I2C operation failed for some other reason. (This status is returned if
i2cm_sda
and
i2cm_scl
have not been 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 ishex
.-
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 as01
, not1
).
-
-
<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 argument
|
An argument was incorrect |
Too few args
|
The minimum number of arguments was not provided |
Timeout
|
The I2C operation did not complete within 3 seconds |
Command failed
|
The I2C operation failed for some other reason. (This status is returned if
i2cm_sda
and
i2cm_scl
have not been 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 thestr_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
usingrbmode
. - 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 theboot
,con
, anddct
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