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

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 s u --- service UUID
  • bl t a --- transmit power (advertising)
  • bl t c --- transmit power (connection)
  • bl v m --- advertising mode
  • 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
• Bus
  • bu i --- bus initialization mode
  • bu s c --- bus serial control level or edge sensitivity
• BLE Central
  • ce c c --- connection count
  • ce c m --- connection mode
  • ce s h d --- central high scan duration
  • ce s h i --- central high scan interval
  • ce s l d --- central low scan duration
  • ce s l i --- central low scan interval
  • ce s m --- scan mode
• 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
  • ua b --- UART baud
  • ua f --- UART flow
• User Storage
  • us v --- User storage

Variable Description

All

al

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

Description

Get BLE device address

Arguments

-

Default

-

Get example

> get bl a
R000014
4C55CC129A42

bl c c

Description

Returns the number of centrals connected when acting as a peripheral.

Arguments

-

Default

-

Get example

> get bl c c
R000003
0

bl s u

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

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

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 m

Description

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

Arguments

-

Default

-

Get example

> get bl v m
R000006
high

bl v h d

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.

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

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

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

300

Get example

> get bl v l d
R000004
300

Set example

> set bl v l d 350
R000009
Success

bl v l i

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

Bus

bu i

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

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

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

Central

ce c c

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

Description

Returns the connection mode when connected with a peripheral.

Connection modes are:

• none: no connection
• low: connected with low connection interval
• high: connected with high connection interval

Arguments

-

Default

-

Get example

> get ce c m
R000006
none

ce s d

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

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

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

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

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

Description

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

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

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

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

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

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

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

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

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

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:

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

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

Description

System print level. Print levels:

• 0 - None
• 1 - Synchronous system msgs
• 2 - Synchronous logging msgs
• 3 - Asynchronous system msgs
• 4/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

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

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

Description

Returns the hardware UUID of the module.

Get example

> get sy u
R000042  
0D06EA434C55CC01B10B1411081309007E615F0A

sy v

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

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

Description

Sets the UART baud rate. The argument must be one of the following standard rates: 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200, 128000, 153600, 230400, 256000, 460800, 921600, 1000000, 1500000.

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

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

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!