TruConnect Variable Reference
This page provides a list of TruConnect 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. Some variables impact the operation of the entire system. A save and reboot is required before new settings for these types of variables take effect.
Documentation Format
Many of the TruConnect 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. The response headers appear first in the response output and are similar to R000009.
Documentation for each variable is provided in the format shown below.
variable
Brief Description | A one-line variable description |
Access | get/set |
Description
A description of variable function.
Arguments
A full list of mandatory and optional arguments.
Default
The factory reset default value.
Get example
An example of how to read the variable, including response codes.
Set example
An example of how to write the variable, including response codes (for writeable variables).
NOTE! Don't forget to check out command navigation tips to make it easier to find and type specific variable names.
List of Variables
- All Variables
- al --- all variables
- BLE Peripheral
- bl a --- BD address
- bl c c --- connection count
- bl e e --- encryption enabled
- bl e k --- encryption key
- bl s u --- service UUID
- bl t a --- transmit power (advertising)
- bl t c --- transmit power (connection)
- bl v d b --- advertising data, generic beacon content
- bl v d f --- advertising data format
- bl v d g --- advertising data, GPIO mask
- bl v d i --- advertising data, iBeacon content
- bl v h d --- advertising high duration
- bl v h i --- advertising high interval
- bl v l d --- advertising low duration
- bl v l i --- advertising low interval
- bl v m --- advertising mode
- Bus
- BLE Central
- GPIO
- gp u --- GPIO usage
- System
- sy a t --- system activity timeout
- sy b n --- board name
- sy c e --- command echo
- sy c h --- command header
- sy c m --- command mode
- sy c p --- command prompt enabled
- sy d n --- device name
- sy i s --- system indicator status LED blink behavior
- sy o e --- OTA enabled
- sy p --- print level
- sy r e --- remote command enabled
- sy s t --- system go-to-sleep timeout
- sy u -- system UUID
- sy v -- firmware version
- sy w t -- system wakeup timeout
- UART
- User Storage
- us v --- User storage
Variable Description
All
al
Brief Description | All variables |
Access | get |
Description
Returns a list of all variables. This includes the list of GPIO settings returned by gp u.
Arguments
-
Default
-
Get example
> get al
bl a : 20737A129A42
bl c c : 0
bl s u : 175f8f23-a570-49bd-9627-815a6a27de2a
bl t a : 0
bl t c : 4
bl v m : off
bl v h d : 30
bl v h i : 32
bl v l d : 300
bl v l i : 1024
bu i : stream
bu s c : edge
ce c c : 0
ce c m : none
ce s h d : 30
ce s h i : 96
ce s l d : 300
ce s l i : 2048
ce s m : off
gp u :
! # Description
# 0 i2c_sda
# 1 i2c_scl
# 2 user_tx
# 3 none
# 4 none
# 5 user_rx
# 6 none,factory
# 7 reserved
# 8 none
# 9 mode_sel
# 10 status_led
# 11 none
# 12 none
# 13 speaker
# 14 none
sy a t : 300
sy b n : AMS001-E01.2
sy c e : 1
sy c h : 0
sy c p : 1
sy d n : AMS-9A42
sy o e : 1
sy p : 4
sy r e : 1
sy u : 0D06EA434C55CC01B10B1411081309007E615F0A
sy v : TruConnect-1.5.0.18, Built:Mar 19 2015 14:03:19, Module:N/A, Board:N/A
ua b : 115200
ua f : 0
us v :
BLE Peripheral
bl a
Brief Description | BD address |
Access | get |
Description
Get BLE device address
Arguments
-
Default
-
Get example
> get bl a
R000014
4C55CC129A42
bl c c
Brief Description | Connection count |
Access | get |
Description
Returns the number of centrals connected when acting as a peripheral.
Arguments
-
Default
-
Get example
> get bl c c
R000003
0
bl e e
Brief Description | BLE encryption enabled |
Access | get |
Description
BLE encryption enabled.
Set the encryption key if required with bl e k.
The key type determines the pairing procedure and security mode and level. See Security.
Arguments
<0/1>
Default
0
Get example
> get bl e e
R000003
0
> set bl e e 1
Success
bl e k
Brief Description | BLE encryption key |
Access | get |
Description
BLE encryption key. This can be set to none
, to a 6 digit pin, or to a 128 bit hex string (32 hex digits).
BLE encryption must be enabled.See bl e e.
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
.
Arguments
none|<6 digit pin code>|<128 bit hex string>
Default
<empty>
Get example
> get bl e k
R000003
none
Set example
> set bl e k 00112233445566778899AABBCCDDEEFF
Success
bl s u
Brief Description | Service UUID |
Access | get/set |
Description
Configures the peripheral service UUID. Also used as the default service UUID for the scan command.
Arguments
<UUID>
Default
-
Get example
> get bl s u
R000038
175f8f23-a570-49bd-9627-815a6a27de2a
Set example
> set bl s u 175f8f23-a570-49bd-9627-815a6a27de2a
R000009
Success
bl t a
Brief Description | Transmit power (advertising) |
Access | get/set |
Description
Configures the RF transmit power when advertising. Units: dBm, range -25 to 4.
Used in conjunction with bl t c. Connecting at higher power than advertising helps to provide a more stable connection.
Arguments
<advertising_power_dbm>
Default
0
Get example
> get bl t a
R000003
4
Set example
> set bl t a 0
R000009
Success
bl t c
Brief Description | Transmit power (connection) |
Access | get/set |
Description
Configures the RF transmit power when connected. Units: dBm, range -25 to 4.
Used in conjunction with bl t a. Connecting at higher power than advertising helps to provide a more stable connection.
Arguments
<connection_power_dbm>
Default
4
Get example
> get bl t c
R000003
0
Set example
> set bl t c 4
R000009
Success
bl v d b
Brief Description | BLE generic beacon data |
Access | get |
Description
Set the data for the BLE generic beacon (manufacturer specific data). You can set all 31 octets of the beacon data.
Requires bl v d f = b
.
The beacon must be formatted according to the Bluetooth specification. See http://www.bluetooth.org, Bluetooth v4 Core Specification: Vol. 3, Part C, sections 8 and 11, and Core Specification Supplement, Part A, section 1.4.
Note that a typical generic beacon starts with a flags structure, followed by a manufacturer data structure. See Example Generic Beacon.
Arguments
<data>
<data>
is specified as hex bytes with no preceding0x
Default
-
(empty)
Get example
> get bl v d b
R000002
Set example
> set bl v d b 0201051bff460200112233445566778899aabbccddeeff0011223344556677
Success
bl v d f
Brief Description | BLE advertising beacon format |
Access | get |
Description
Set the format for BLE advertising. See Advertising.
A range of possible formats is available.
Arguments
<format>
where the currently available formats are shown below. For each format you can set field-specific information with variables as shown:
Format | Description | Variable |
---|---|---|
b | advertise generic beacon | bl v d b - Set generic beacon data. |
i | advertise iBeacon | bl v d i - Set iBeacon values |
s | advertise service ID and name | bl s u - Set service UUID sy d n - Set device name |
s,g | advertise service ID and name. The value of digital GPIOs is sent as a hex value in the scan response packet | bl s u - Set service UUID sy d n - Set device name bl v d g - Set GPIO mask |
Default
s
Get example
> get bl v d f
R000003
s
Set example
> set bl v d f s,g
Success
bl v d g
Brief Description | BLE beacon GPIO mask |
Access | get |
Description
Set the BLE beacon GPIO mask.
Requires bl v d f = s,g
.
See Advertising.
Arguments
<mask>
<mask>
is specified as two hex bytes representing 16 bits, with no preceding0x
. Each bit corresponds to a GPIO, with GPIO 0 represented as the least significant bit. For example,0020
masks all but GPIO 5.
Default
FF
(no GPIO is masked)
Get example
> get bl v d g
R000008
0x00ff
Set example
> set bl v d g 00FF
Success
bl v d i
Brief Description | BLE ibeacon content |
Access | get |
Description
Set the BLE iBeacon content. iBeacon is a protocol standardised by Apple and introduced at the Apple Worldwide Developers Conference in 2013.
Requires bl v d f = i
.
See Advertising.
Arguments
<UUID>,<major>,<minor>
iBeacon content is specified as a string in a specific format: <UUID>,<major>,<min>
.
<UUID>
- the 128-bit UUID is specified as a string of 16 hex octets with hyphen separators after octets 4, 6, 8 and 10, as shown in the examples below. See http://www.bluetooth.org, Bluetooth v4 Core Specification: Vol. 3, Section 3.2 for details of UUID format.<major>
- 2 hex octets with or without preceding0x
<minor>
- 2 hex octets with or without preceding0x
Default
FF
(empty)
Get example
> get bl v d i
R000052
e2c56db5-dffb-48d2-b060-d0f5a71096e0,0x0000,0x0000
Set example
> set bl v d i e2c56db5-dffb-48d2-b060-d0f5a71096e0,0001,0002
Success
bl v h d
Brief Description | Advertising high duration |
Access | get/set |
Description
Configures high mode advertising duration. This is the duration in seconds for which advertising continues after issuing the adv high command. Valid range: 0 - 1000 seconds. A value of 0 means advertise forever.
See Advertising.
Arguments
<duration>
Default
30
Get example
> get bl v h d
R000004
30
Set example
> set bl v h d 40
R000009
Success
bl v h i
Brief Description | Advertising high interval |
Access | get/set |
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 - 8000 slots inclusive.
Arguments
<interval>
Default
32
Get example
> get bl v h i
R000004
32
Set example
> set bl v h i 50
R000009
Success
bl v l d
Brief Description | Advertising low duration |
Access | get/set |
Description
Configures low mode advertising duration. This is the duration in seconds for which advertising continues after issuing the adv low command. Valid range: 0 - 1000 seconds inclusive. A value of 0 means advertise forever.
Arguments
<duration>
Default
0
(Advertise in low mode forever)
Get example
> get bl v l d
R000004
300
Set example
> set bl v l d 350
R000009
Success
bl v l i
Brief Description | Advertising low interval |
Access | get/set |
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 - 8000 slots inclusive.
Arguments
<interval>
Default
1024
Get example
> get bl v l i
R000004
1024
Set example
> set bl v l i 64
R000009
Success
bl v m
Brief Description | Advertising mode |
Access | get |
Description
Get peripheral advertising mode, as set by the adv command.
Arguments
-
Default
-
Get example
> get bl v m
R000006
high
Bus
bu i
Brief Description | Bus initialization mode |
Access | get/set |
Description
Serial bus initialization mode. The mode in which the bus initializes on boot up.
Note: Save before reboot, or changes will be lost. See Serial Interface.
To control the bus mode of a remote peripheral TruConnect module, see rbmode.
Arguments
<stream/command
bu i value | Description | Interface in Control |
---|---|---|
command | Initialize to Local COMMAND mode | Serial interface (remote locked out) |
stream | Initialize to STREAM mode | Serial or Remote interface |
Default
stream
Note: The serial bus mode depends on the mode_sel
GPIO configuration. See Serial Interface, Manual and Automatic Bus Mode Selection.
Get example
> get bu i
R000008
stream
Set example
> set bu i command
R000009
Success
> save
R000009
Success
bu s c
Brief Description | Bus serial control level or edge sensitivity |
Access | get/set |
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 mode_sel
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 mode_sel
pin.
The mode_sel
pin is configured with the GPIO function command.
Arguments
<edge/level>
Default
level
Get example
> get bu s c
R000006
edge
Set example
> set bu s c edge
R000009
Success
bu s s
Brief Description | Set bus stream breakout sequence |
Access | get/set |
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 0
. Note that this is distinct from setting the value 00
. Setting to 00
sets the breakout sequence to the hexadecimal 0x00
, corresponding to the ASCII NULL character.
See Serial Bus Modes.
Arguments
<sequence>
where:
<sequence>
is provided as hexadecimal numbers, corresponding to a string of ASCII characters.
Minimum length: 1 byte; Maximum length: 4 bytes.
For example, the value616263
sets the sequence to the ASCII stringabc
.
Default
242424
This correspondings to the ASCII characters "$$$".
Get example
> get bu s s
R000008
242424
Set example
Set breakout sequence to ASCII characters "BRK"
> set bu s s 42524b
R000009
Success
Central
ce a d
Brief Description | Central auto-connect device |
Access | get |
Description
Set BD_ADDR or device name of peripheral to which central automatically connects.
To disable connection, set to 0
Arguments
[<BD_ADDR>/<device name>]
where:
BD_ADDR
: BD address of device to which central automatically connects<device name>
: device name of device to which central automatically connects
Maximum device name length: 8 bytes
Default
0
Get example
> get ce a d
R000003
0
Set example
> set ce a d 4C55CC129A42
R000009
Success
ce c c
Brief Description | Central connection count |
Access | get |
Description
Returns the number of peripherals connected when acting as a central.
Arguments
-
Default
-
Get example
> get ce c c
R000003
0
ce c m
Brief Description | Central connection mode |
Access | get |
Description
Returns the connection mode when connected with a peripheral.
Connection modes are:
none
: no connectionlow
: connected with low connection intervalhigh
: connected with high connection interval
Arguments
-
Default
-
Get example
> get ce c m
R000006
none
ce s d
Brief Description | Central scan high duration |
Access | get/set |
Description
Configures central scan high mode duration. This is the duration in seconds for which scan continues after issuing the scan high command. Valid range: 0 - 1000 seconds.
If <duration>
= 0, scan forever at the specified rate.
Arguments
<duration>
Default
300
Get example
> get ce s h d
R000004
30
Set example
> set ce s h d 40
R000009
Success
ce s h i
Brief Description | Central scan high interval |
Access | get/set |
Description
Configures central high mode scanning interval, used for the scan command high
option. Valid range: 96-8000, Default: 96
Arguments
<interval>
Default
96
Get example
> get ce s h i
R000004
96
Set example
> set ce s h i 1000
R000009
Success
ce s l d
Brief Description | Advertising low duration |
Access | get/set |
Description
Configures central low mode scanning duration. This is the duration in seconds for which scanning continues after issuing the scan low command. Valid range: 0 - 1000 seconds inclusive.
If <duration>
= 0, scan forever at the specified rate.
Arguments
<duration>
Default
300
Get example
> get ce s l d
R000004
300
Set example
> set ce s l d 350
R000009
Success
ce s l i
Brief Description | Advertising low interval |
Access | get/set |
Description
Configures low mode scanning interval, used for the scan command low
option. Valid range: 96-8000: Default 2048
Arguments
<interval>
Default
2048
Get example
> get ce s l i
R000004
1024
Set example
> set ce s l i 64
R000009
Success
ce s m
Brief Description | Central scan mode |
Access | get |
Description
With this device acting as a Central, returns scan mode, as set by the scan command. Values:
- off: no scan
- low: low scan
- high: high scan
Arguments
-
Default
-
Get example
> get ce s m
R000005
off
GPIO
gp u
Brief Description | GPIO usage |
Access | get |
Description
Get GPIO usage. See the GPIO function command for a description of configurable and automatically assigned GPIO functions.
For GPIOs set to the stdio
function, get gp u
displays the function and the direction set by the gdi or gdis commands. For example:
> gfu 9 stdio
Success
> gdi 9 ipu
Success
> gfu 10 stdio
Success
> gdi 10 ohi
Success
> get gp u
! # Description
...
# 9 stdio,ipu
# 10 stdio,ohi
...
Arguments
-
Default
-
Get example
> get gp u
R000220
! # Description
# 0 i2c_sda
# 1 i2c_scl
# 2 user_tx
# 3 none
# 4 none
# 5 user_rx
# 6 none,factory
# 7 reserved
# 8 none
# 9 mode_sel
# 10 status_led
# 11 none
# 12 none
# 13 speaker
# 14 none
System
sy a t
Brief Description | System activity timeout |
Access | get/set |
Description
Specify a period of inactivity on the BLE and UART interfaces. After the system activity timeout
elapses it may trigger power management features as follows.
The system activity timeout
triggers entry to low power advertising mode. See Power Management, Low Power Advertising Mode.
The activity
GPIO may be configured to respond to the system activity timeout
. See the gfu (GPIO function) command.
If configured, the activity
GPIO goes high on PoR, and on any UART or BLE activity, and remains high for the duration specified by system activity timeout
. After no interface activity for the specified duration, the activity
GPIO goes low. See Power Management, activity GPIO and system activity timeout.
Arguments
<duration in seconds>
Default
300
Get example
> get sy a t
R000005
300
Set example
> set sy a t 400
R000009
Success
sy b n
Brief Description | System board name |
Access | get/set |
Description
Configure board name. Maximum length: 16 characters
Arguments
<name>
Default
<board name>
Get example
> get sy b n
R000014
AMS001-E01.2
Set example
> set sy b n MyWahoo
R000009
Success
sy c e
Brief Description | System command echo |
Access | get/set |
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.
Arguments
<0/1>
Default
0
Get example
> get sy c e
R000003
1
Set example
> set sy c e 0
R000009
Success
sy c h
Brief Description | System command header |
Access | get/set |
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.
Arguments
<0/1>
Default
0
Get example
> get sy c h
R000003
1
Set example
> set sy c h 1
R000009
Success
sy c m
Brief Description | System command mode |
Access | set |
Description
Puts the TruConnect command interface into human or machine mode. See Serial Interface, Configuration.
Note! This variable is NOT readable.
Arguments
<human/machine>
Default
human
Set example
> set sy c m machine
R000009
Success
sy c p
Brief Description | System command prompt enabled |
Access | get/set |
Description
Enable/disable terminal command prompt. Only applies to command mode. A prompt makes it easy for humans to interact with TruConnect.
Arguments
<0/1>
Default
1
Get example
> get sy c p
R000003
1
Set example
> set sy c p 1
R000009
Success
sy d n
Brief Description | System device name |
Access | get/set |
Description
Bluetooth device name, up to 8 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 following examples.
Arguments
<name[#]>
Default
AMS-####
Get example
> get bl d
4C55CCABCDEF
> get sy d n
R000010
AMS-CDEF
Set example
In the following examples the BD_ADDR address is 4C55CCABCDEF
(see bl a)
> set sy d n ACK-##
R000009
Success
> get sy d n
R000008
ACK-EF
> set sy d n ACKme###
R000009
Success
> get sy d n
R000009
ACKmeDEF
> set sy d n my######
R000009
Success
> get sy d n
R000010
myABCDEF
sy i s
Brief Description | System indicator status LED blink behavior |
Access | get/set |
Description
Set the blink pattern of the system indication status LED.
This can be used in power management. See Power Management.
Arguments
<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).
The minimum high or low period is 0.125s (125ms).
Some examples:
Low = AA/CC | High = BB/DD | Period | Duty Cycle | Notes |
---|---|---|---|---|
01 | 01 | 0.25s | 50% | Fastest possible blink. Duty cycle = 50% |
04 | 04 | 1.00s | 50% | 1 Hz --- default blink pattern when not connected |
00 | 7f | . | 100% | Always on --- default blink pattern when connected |
1c | 04 | 4.00s | 12.5% | period = (28 + 4 = 32) x 0.125, duty cycle = 100*4/(28+4) |
7f | 7f | 31.75s | 50% | Slowest possible blink. Duty cycle = 50% |
Default
0404007f
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
Brief Description | System OTA enabled |
Access | get/set |
Description
Enable/disable OTA upgrades. 1: enabled; 0: disabled
Arguments
<1/0>
Default
1
Get example
> get sy o e
R000003
1
Set example
> set sy o e 1
Success
sy p
Brief Description | System print level |
Access | get/set |
Description
System print level. Print levels:
0
- None1
- Synchronous system msgs2
- Synchronous logging msgs3
- Asynchronous system msgs4/all
- Asynchronous logging msgs
Arguments
<[0-4]/[all]>
Default
all
Get example
> get sy p
R000003
0
Set example
> set sy p 0
R000009
Success
sy r e
Brief Description | System remote command enabled |
Access | get/set |
Description
Enables/disables access to the TruConnect 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.
Arguments
1/0
Default
1
Get example
> get sy r e
R000003
1
Set example
> set sy r e 1
Success
sy s t
Brief Description | System go-to-sleep timeout |
Access | get/set |
Description
The module automatically goes to sleep after a timeout period of the specified <seconds>
. The timeout countdown restarts when a wake event occurs.
Module go-to-sleep is delayed while data is available on the connection.
The minimum timeout is 10 seconds. This provides time, while the module is awake, to issue a command to set sy s t
to 0
, which prevents the module cycling back to sleep.
A save and reboot is required before the sleep timeout is enabled.
See Power Management, Sleep or Wake on Timeout.
Arguments
<seconds>
Range: 0 or 10 to 86400
Set to 0
to disable go-to-sleep.
Default
0
Get example
> get sy s t
R000003
0
Set example
> set sy s t 10
Success
sy u
Brief Description | System UUID |
Access | get |
Description
Returns the hardware UUID of the module.
Get example
> get sy u
R000042
0D06EA434C55CC01B10B1411081309007E615F0A
sy v
Brief Description | Firmware version |
Access | get |
Description
Returns the TruConnect firmware version.
This is the variable equivalent of the ver command.
Get example
> get sy v
TruConnect-1.5.0.1, Built:Feb 23 2015 16:50:00, Module:N/A, Board:AMS001-E01.2
sy w t
Brief Description | System wakeup timeout |
Access | get/set |
Description
The module automatically wakes from sleep after timeout <seconds>
from the moment of going to sleep.
0
disables auto-wakeup on a timer.
A save and reboot is required before the sleep timeout is enabled.
See Power Management, Sleep or Wake on Timeout.
Arguments
<seconds>
Range: 0 to 86400
Set to 0
to disable wakeup.
Default
0
Get example
> get sy w t
R000003
0
Set example
> set sy w t 3600
Success
UART
ua b
Brief Description | UART baud |
Access | get/set |
Description
Sets the UART baud rate. The
Get arguments -
Set arguments <baud rate>
Default
115200
Get example
> get ua b
R000008
115200
Set example
> set ua b 115200
R000009
Success
ua f
Brief Description | UART flow |
Access | get/set |
Description
Turn on/off UART hardware flow control.
Arguments
<1/0>
Default
0
Get example
> get ua f
R000003
1
Set example
> set ua f 0
R000009
Success
us v
Brief Description | User storage |
Access | get/set |
Description
Allows storage and retrieval of up to 32 bytes (256 bits) of arbitrary user information.
Arguments
<user_info>
Default
-
Set example
> set us v 32_bytes_of_my_user_information!
Success
Get example
> get us v
32_bytes_of_my_user_information!