BGX13 Variable Reference

This page provides a list of Bluetooth Xpress (BGX) BLE variables with a full description of the function of each variable together with example usage.

Variables are cached in volatile RAM and must be saved to non-volatile flash memory to persist between reboots. To save variables to flash, use the save command.

NOTE! Don't forget to check out command navigation tips to make it easier to find and type specific variable names.

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) = 1. These settings are provided to make it easy for a host microcontroller to parse responses by examining response headers.

List of Variables


All

al

All (variables)

Description

Returns a list of all variables. This includes the list of GPIO settings returned by gp u.

AttributeDescription
accessget

Get example

> get al
bl a     : D0CF5E828F18
bl c c   : 0
bl c i   : 12
bl c t   : 400
bl d a   : 512
bl e b   : 1
bl e k   : none
bl e p   : secure
bl p p   : 1m
bl t c   : 8
bl v h d : 30
bl v h i : 32
bl v l d : 0
bl v l i : 874
bl v m   : high
bu i     : command
bu s c   : level
bu s s   : 242424
ce c c   : 0
ce s h d : 30
ce s h i : 96
ce s l d : 300
ce s l i : 2048
ce s m   : off
ce w m   : ack
gp u     : 
!  # Description
#  0 none
#  1 none
#  2 none
#  3 none
#  4 none
#  5 none
#  6 none
#  7 none
sy c e   : 1
sy c h   : 0
sy c p   : 1
sy d n   : BGX-8F18
sy i m   : Silicon Labs
sy i p   : Blue Gecko Xpress
sy i s   : 04047F00
sy o e   : 1
sy p     : 4
sy r e   : 1
sy s m   : deep
sy u     : <DMS.UUID here>
sy v     : BGX13.1.0.880.1-821-880
sy w c   : 1
tm n p   : 0
ua b     : 115200
ua f     : 0
uf u     : 
!  # Description
#  0 none ()
#  1 none ()
#  2 none ()
#  3 none ()

BLE Peripheral

bl a

BLE Address

Description

Returns the BLE device address.

AttributeDescription
format6-byte hex string, big-endian
defaultunique per device
accessget
saven/a

Get example

> get bl a
D0CF5E35E0D8

bl c c

BLE Connection Count

Description

Returns the number of centrals that are connected when acting as a peripheral. Will return 0 or 1.

AttributeDescription
formatinteger
unitscount
min0
max1
default0
accessget
saven/a

Get example

> get bl c c
0

bl c i

BLE Connection Interval

Description

BLE connection interval. See Bluetooth specification : Important Connection Parameters : Connection Interval, Supervision Timeout

AttributeDescription
formatinteger
units1.25 ms
min6 (7.5 ms)
max3200 (4000 ms)
default12 (15 ms)
accessget/set
saveyes

Get example

> get bl c i
12

Set example

> set bl c i 10
Success

bl c t

BLE Connection Timeout

Description

BLE connection supervision timeout. See Bluetooth specification : Important Connection Parameters : Connection Interval, Supervision Timeout.

AttributeDescription
formatinteger
units10 ms
min10 (100 ms)
max3200 (32000 ms)
default400 (4000 ms)
accessget/set
saveyes

Get example

> get bl c t
400

Set example

> set bl c t 500
Success

bl d a

BLE Device Appearance

Description

BLE device appearance is a 16 bit integer that describes how the device appears to other devices. It is part of the GAP database. The default value of 512 corresponds to Generic tag, Generic category.

For other appearance values, see Bluetooth GAP Appearance.

AttributeDescription
formatinteger
unitsn/a
min0
max65535
default512
accessget/set
saveyes

Get example

get bl d a
512

Set example

set bl d a 512
Success

bl e b

BLE Encryption Bondable (mode)

Description

Enables or disable bonding. Encryption is always enabled for the Bluetooth Xpress module.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default1
accessget/set
saveyes

Get example

> get bl e b
1

Set example

> set bl e b 1
Success

bl e k

BLE Encryption Key

Description

The BLE encryption key can be set to none or to a 6 digit pin. Entering more or less than 6 digits, or entering a pin with non-numeric characters other than 'none' will cause the command to fail. Encryption is always enabled on the Bluetooth Xpress module.

The key type determines the pairing procedure and security mode and level. See Security.

Note: if the key is set to none, and an Android phone requests a pin, use 000000.

AttributeDescription
format6-digit integer or 'none'
unitsn/a
min000000
max999999
default'none'
accessget/set
saveyes

Get example

> get bl e k
none

Set example

> set bl e k 123456
Success

bl e p

BLE Encryption Pairing (mode)

Description

Selects whether to allow LE Legacy Pairing. If the connecting device supports LE Secure Connections (BLE 4.2 or newer) it will be used by default. Setting to any will allow pairing with either secure or legacy methods while secure requires secure connections pairing. Encryption is always enabled on Bluetooth Xpress modules.

AttributeDescription
formatstring enumeration
units'secure'=secure only
'any'=secure or legacy
defaultsecure
accessget/set
saveyes

Get example

> get bl e p
secure

Set example

> set bl e p any
Success

bl p p

BLE Preferred PHY

Description

Chooses between the 1M PHY and the 2M PHY as the preferred PHY to use for connections. Attempted connections to devices that do not support 2M PHY will connect with the 1M PHY, even if 2M PHY is selected as the preferred PHY.

AttributeDescription
formatstring enumeration
units'1m'=1M PHY
'2m'=2M PHY
default1m
accessget/set
saveyes

Get example

> get bl p p
1m

Set example

> set bl p p 2m
Success

bl t c

BLE Transmit Connected (power)

Description

Configures the RF transmit power when connected.

AttributeDescription
formatinteger
unitsdBm
min-25
max8
default8
accessget/set
saveyes

Get example

> get bl t c
8

Set example

> set bl t c 4
Success

bl v h d

BLE adVertising High Duration

Description

Configures high mode advertising duration. This is the duration in seconds for which advertising continues after issuing the adv high command. See BLE Advertising.

AttributeDescription
formatinteger
unitsseconds
min0 (advertise forever)
max1000
default30
accessget/set
saveyes

Get example

> get bl v h d
30

Set example

> set bl v h d 40
Success

bl v h i

BLE adVertising High Interval

Description

Configures high mode advertising interval, used for the adv command high option. The interval is measured in slots. For example, an interval of 32 means advertise in slot 0, then 32, then 64 and so on. Valid range: 32 - 16384 slots inclusive.

AttributeDescription
formatinteger
unitsslots
min32
max16384
default32
accessget/set
saveyes

Get example

> get bl v h i
32

Set example

> set bl v h i 50
Success

bl v l d

BLE adVertising Low Duration

Description

Configures low mode advertising duration. This is the duration in seconds for which advertising continues after issuing the adv low command. See BLE Advertising.

AttributeDescription
formatinteger
unitsseconds
min0 (advertise forever)
max1000
default0 (forever)
accessget/set
saveyes

Get example

> get bl v l d
0

Set example

> set bl v l d 350
Success

bl v l i

BLE adVertising Low Interval

Description

Configures low mode advertising interval, used for the adv command low option. The interval is measured in slots. For example, an interval of 32 means advertise in slot 0, then 32, then 64 and so on. Valid range: 32 - 16384 slots inclusive.

AttributeDescription
formatinteger
unitsslots
min32
max16384
default874
accessget/set
saveyes

Get example

> get bl v l i
874

Set example

> set bl v l i 64
Success

bl v m

BLE adVertising Mode

Description

Get peripheral advertising mode, as set by the adv command.

AttributeDescription
formatstring enumeration
units'high'=adv high mode
'low'=adv low mode
'off'=no advertising
default'high'
accessget
saven/a

Get example

> get bl v m
high

Bus

bu i

Bus Initialization (mode)

Description

Serial bus initialization mode. The mode in which the bus initializes on boot-up.

Notes:

AttributeDescription
formatstring enumeration
units'stream'=stream mode
'command'=command mode (remote command mode locked out)
default'command'
accessget/set
saveyes

Get example

> get bu i
command

Set example

> set bu i stream
Success
> save
Success

bu s c

Bus Serial Control

Description

The serial bus control variable determines how the serial bus is switched between STREAM mode and COMMAND mode. If bu s c is set to edge, a rising edge on the str_select pin toggles modes. If however bu s c is set to level, the serial bus mode is selected by driving a constant high or low logic level onto the str_select pin. The str_select pin is configured with the GPIO function command.

AttributeDescription
formatstring enumeration
units'edge'=rising edge toggle on str_select
'level'=mode selected by logic level
default'level'
accessget/set
saveyes

Get example

> get bu s c
level

Set example

> set bu s c edge
Success

bu s s

Bus Stream (breakout) Sequence

Description

Set a new bus stream breakout sequence. Sending the breakout sequence when in STREAM mode places the device in local COMMAND mode. To disable the breakout sequence, set to none. See Serial Bus Modes.

In order to be seen as a breakout condition, the breakout sequence must be preceded and followed by idle periods of at least 500 milliseconds on the BGX UART's rx line. The amount of time between each character in the breakout sequence must be less than milliseconds.

Due to these timing constraints, tt is generally not possible to send the breakout sequence by manually typing it into a terminal. Instead, a terminal program with the capability to send macros should be used.

Note: Setting to 00 sets the breakout sequence to the hexadecimal 0x00, corresponding to the ASCII NULL character.

Note: The breakout sequence does not work reliably for serial data rates less than 5000 bits per second.

AttributeDescription
formatup to 4-byte hex string
default242424 ('$$$')
accessget/set
saveyes

Get example

> get bu s s
242424

Set example

Set breakout sequence to ASCII characters "BRK"

> set bu s s 42524b
Success

Disable breakout sequence:

> set bu s s none

Central

ce c c

Central Connection Count

Description

Returns the number of peripherals connected when acting as a central. Will return 0 if not connected, and 1 if connected.

AttributeDescription
formatinteger
unitscount
min0
max1
default0
accessget
saven/a

Get example

> get ce c c
0

ce s h d

Central Scan High Duration

Description

Configures central scan high mode duration. This is the duration in seconds for which scan continues after issuing the scan high command.

AttributeDescription
formatinteger
unitsseconds
min0 (scan forever)
max1000
default30
accessget/set
saveyes

Get example

> get ce s h d
30

Set example

> set ce s h d 40
Success

ce s h i

Central Scan High Interval

Description

Configures central high mode scanning interval, used for the scan command high option.

AttributeDescription
formatinteger
unitsslots
min4
max16384
default96
accessget/set
saveyes

Get example

> get ce s h i
96

Set example

> set ce s h i 1000
Success

ce s l d

Central Scan Low Duration

Description

Configures central low mode scanning duration. This is the duration in seconds for which scanning continues after issuing the scan low command.

AttributeDescription
formatinteger
unitsseconds
min0 (scan forever)
max1000
default300
accessget/set
saveyes

Get example

> get ce s l d
300

Set example

> set ce s l d 350
Success

ce s l i

Central Scan Low Interval

Description

Configures low mode scanning interval, used for the scan command low option.

AttributeDescription
formatinteger
unitsslots
min4
max16384
default2048
accessget/set
saveyes

Get example

> get ce s l i
2048

Set example

> set ce s l i 64
Success

ce s m

Central Scan Mode

Description

With this device acting as a Central, returns scan mode, as set by the scan command.

AttributeDescription
formatstring enumeration
units'high'=scan high mode
'low'=scan low mode
'off'=no scanning
default'off'
accessget
saven/a

Get example

> get ce s m
off

ce w m

Central Write Mode

Description

This variable controls whether the connection requires acknowledgement on writes.

AttributeDescription
formatstring enumeration
units'ack'=use write acknowledgement
'noack'=do not use acknowledgment
default'ack'
accessget/set
saveyes

Get example

> get ce w m
ack

Get example

> set ce w m noack
Success

GPIO

gp u

GPIO Usage

Description

Get GPIO usage. See the GPIO function command for a description of configurable and automatically assigned GPIO functions.

By default get gp u displays the function and the direction set by the gdi or gdis commands. For example:

> gfu 5 stdio
Success
> gdi 5 ipu
Success
> gfu 6 stdio
Success
> gdi 6 ohi
Success
> get gp u
!  # Description
...
#  5 stdio,ipu
#  6 stdio,ohi
...

To view the pin mode and extra options set by the gdi command set this variable to verbose. To change back to the shorter display, set this variable to default.

> set gp u verbose
Success
> get gp u
!  # Description
    ...
#  5 stdio,ipu (ioz)
#  6 stdio,ohi (ioz,pp,drvst)
    ...
AttributeDescription
formattable list
accessget/set
saven/a

Get example

> get gp u
!  # Description
#  0 stdio
#  1 stdio
#  2 none
#  3 none
#  4 none
#  5 none
#  6 none
#  7 none

uf u

User Function Usage

Description

User functions and the events that trigger them are displayed using this read-only variable. This multi-line variable behaves similar to the gpio "gp u" variable.

AttributeDescription
formattable list
accessget
saven/a

Get example

> get uf u
!  # Description
#  0 lo,3 (con D0CF5E35E0D8 10)
#  1 hi,3 (dct)
#  2 none ()
#  3 none ()

System

sy c e

System Command Echo

Description

Enable/disable character echo.

Note! If character echo is turned off, keystrokes that are subsequently typed are not echoed to the serial interface (or terminal). This mode is primarily intended for machine control.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default1
accessget/set
saveyes

Get example

> get sy c e
1

Set example

> set sy c e 0
Success

sy c h

System Command Header

Description

Enable/disable a response header for commands. Only applies to command mode. Response headers make it easy to parse responses with a host MCU.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default0
accessget/set
saveyes

Get example

> get sy c h
0

Set example

> set sy c h 1
Success

sy c m

System Command Mode

Description

Puts the Bluetooth Xpress command interface into human or machine mode. See Serial Interface, Configuration. Note! This variable is NOT readable.

AttributeDescription
formatstring enumeration
units'machine'=machine mode
'human'=human mode
default'human'
accessset
saveyes

Set example

> set sy c m machine
Success

sy c p

System Command Prompt

Description

Enable/disable terminal command prompt. Only applies to command mode. A prompt makes it easy for humans to interact with Bluetooth Xpress module.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default1
accessget/set
saveyes

Get example

> get sy c p
1

Set example

> set sy c p 1
Success

sy d n

System Device Name

Description

Bluetooth device name, up to 16 characters in length. The last 2 to 6 characters from the BD_ADDR may be substituted for # wildcards supplied in the final characters of the name. See the examples below.

AttributeDescription
formatstring
min--
max16 characters length
default'BGX-####'
accessget/set
saveyes

Get example

> get bl d
4C55CCABCDEF
> get sy d n
BGX-CDEF

Set example

In the following examples the BD_ADDR address is 4C55CCABCDEF (see bl a)

> set sy d n ACK-##
Success
> get sy d n
ACK-EF
> set sy d n BGX###
Success
> get sy d n
BGXDEF
> set sy d n my######
Success
> get sy d n
myABCDEF

sy i m

System Info Manufacturer

Description

Manufacturer string, up to 32 characters in length. Use double quotes to enter a name containing a space.

AttributeDescription
formatstring
min--
max32 characters length
default'Silicon Labs'
accessget/set
saveyes

Get example

> get sy i m
Silicon Labs

Set example

> set sy i m "Placeholder Name"
Success
> get sy i m
Placeholder Name

sy i p

System Info Product

Description

Product information string, up to 32 characters in length. Use double quotes to enter a name containing a space.

AttributeDescription
formatstring
min--
max32 characters length
default'Blue Gecko Xpress'
accessget/set
saveyes

Get example

> get sy i p
Blue Gecko Xpress

Set example

> set sy i p "Placeholder Product"
Success
> get sy i p
Placeholder Product

sy i s

System Indicator Status (setting)

Description

Set the blink pattern for the con_status_led pin function. The command takes 4 hexadecimal values AABBCCDD, where AA, BB, CC and DD are hex numbers in the range 00 to 7F.

'AABB' sets the LED blink pattern when not connected. 'CCDD' sets the LED blink pattern when connected.

The low part of the blink pattern is set with AA when not connected (or CC when connected).

The high period of the blink pattern is set with BB when not connected (or DD when connected).

Each pattern tick equals 0.1 sec (100 msec).

Some examples:

Low = AA/CCHigh = BB/DDPeriodDuty CycleNotes
01010.20s50%Fastest possible blink. Duty cycle = 50%
04040.80s50%1.25 Hz --- default blink pattern when not connected
007f.100%Always on --- default blink pattern when connected
1c043.20s12.5%period = (28 + 4 = 32) x 0.1, duty cycle = 100 x 4/(28 + 4)
7f7f25.4s50%Slowest possible blink. Duty cycle = 50%
AttributeDescription
format4-byte hex string
units0.1 sec resolution per byte
min'00' per byte (inactive)
max'7F' per byte
default'04047F00' (1.25 Hz blink when not connected, full on when connected)
accessget/set
saveyes

Get example

> get sy i s        
0404007f

Set example

Set to fastest blink when not connected, slowest blink when connected.

> set sy i s 01017f7f
Success

sy o e

System OTA Enable

Description

Enable or disable OTA upgrades.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default1
accessget/set
saveyes

Get example

> get sy o e
1

Set example

> set sy o e 1
Success

sy p

System Print (level)

Description

System print level.

AttributeDescription
formatinteger
units0 = no messages
1 = synchronous system messages
2 = synchronous logging messages
3 = asynchronous system messages
4 = all/asynchronous logging messages
min0
max4
default4
accessget/set
saveyes

Get example

> get sy p
0

Set example

> set sy p 0
Success

sy s m

System Sleep Mode

Description

Sets the sleep mode to be entered by the Bluetooth Xpress module. See Power Management for more information.

AttributeDescription
formatstring enumeration
units'deep' = sleep mode with radio off
'radio' = sleep mode with radio on, advertising enabled
default'deep'
accessget/set
saveyes

Get example

> get sy s m
deep

Set example

> set sy s m radio
Success

sy r e

System Remote (commanding) Enabled

Description

Enables/disables access to the Bluetooth Xpress module command interface from a remote terminal via the BLE interface (remote COMMAND mode). If sy r e is set to 0, access to the command interface is restricted to the UART interface (local COMMAND mode). See Serial Interface.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default1
accessget/set
saveyes

Get example

> get sy r e
1

Set example

> set sy r e 1
Success

sy u

System UUID

Description

Returns the hardware UUID of the module.

AttributeDescription
format20-byte hex string
defaultunique per device
accessget
saven/a

Get example

> get sy u
0D06EA434C55CC01B10B1411081309007E615F0A

sy v

System (firmware) Version

Description

Returns the Bluetooth Xpress firmware version.

AttributeDescription
formatstring
defaultvaries
accessget
saven/a

This is the variable equivalent of the ver command.

Get example

> get sy v
BGX13.1.0.821.0-821-821

sy w c

System Wake on CTS

Description

Enables/disables waking the device from Sleep Mode when a falling edge is detected on the UART CTS pin.

UART baud rate must be greater than 9600 bps for the device to wake from sleep on a falling edge of CTS. If the baud rate is 9600 bps or less, the UART interface is operational in Sleep Mode, so CTS retains its normal function as a flow control signal and cannot be used as a wake pin. In this scenario, the user can issue the wake command to wake the device.

See Power Management for more information on power modes.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default1
accessget/set
saveyes

Get example

> get sy w c
1

Set example

> set sy w c 0
Success

Test mode

tm n p

Test Mode Number of Packets

Description

This variable reports the number of packets that were transmitted or received between the dtm start and dtm stop commands. It is set to 0 when dtm start runs and records total packets when dtm stop runs.

See Test mode (dtm) for more details.

AttributeDescription
formatinteger
unitscount
min0
max65535
default0
accessget
saven/a

Get example

> get tm n p
0

UART

ua b

UART Baud

Description

Sets the UART baud rate.

AttributeDescription
formatinteger
unitsbits per second
min0
max2000000
default115200
accessget/set
saveyes

Get example

> get ua b
115200

Set example

> set ua b 115200
Success

ua f

UART Flow control

Description

Turn on/off UART hardware flow control.

AttributeDescription
formatinteger
units1=true/enabled, 0=false/disabled
min0
max1
default0
accessget/set
saveyes

Get example

> get ua f
1

Set example

> set ua f 0
Success