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 DescriptionA one-line variable description
Accessget/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

Variable Description


All

al

Brief DescriptionAll variables
Accessget

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 DescriptionBD address
Accessget

Description

Get BLE device address

Arguments

-

Default

-

Get example

> get bl a
R000014
4C55CC129A42

bl c c

Brief DescriptionConnection count
Accessget

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 DescriptionBLE encryption enabled
Accessget

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 DescriptionBLE encryption key
Accessget

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 DescriptionService UUID
Accessget/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 DescriptionTransmit power (advertising)
Accessget/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 DescriptionTransmit power (connection)
Accessget/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 c e

Brief DescriptionBLE advertising connection enable
Access get, set

Description

Enable or disable connecting to the device while advertising. See Beacons and Advertising.

Connectable and non-connectable indirect advertising are supported.

See www.bluetooth.org, Bluetooth Core Standard version 4, Vol 6, Part B Section 2.3.1.

Arguments

<0/1>

where:

Defaults

1 : Connection requests accepted

Get Example

get bl v c e
1

Set Example

set bl v c e 0
Success

bl v d b

Brief DescriptionBLE generic beacon data
Accessget

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>

Default - (empty)

Get example

> get bl v d b
R000002

Set example

> set bl v d b 0201051bff460200112233445566778899aabbccddeeff0011223344556677
Success

bl v d f

Brief DescriptionBLE advertising beacon format
Accessget

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:

FormatDescriptionVariable
badvertise generic beaconbl v d b - Set generic beacon data.
iadvertise iBeaconbl v d i - Set iBeacon values
sadvertise service ID and namebl s u - Set service UUID
sy d n - Set device name
s,gadvertise 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 DescriptionBLE beacon GPIO mask
Accessget

Description

Set the BLE beacon GPIO mask.

Requires bl v d f = s,g.

See Advertising.

Arguments

<mask>

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 DescriptionBLE ibeacon content
Accessget

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

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 DescriptionAdvertising high duration
Accessget/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 DescriptionAdvertising high interval
Accessget/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 DescriptionAdvertising low duration
Accessget/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 DescriptionAdvertising low interval
Accessget/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 DescriptionAdvertising mode
Accessget

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 DescriptionBus initialization mode
Accessget/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 valueDescriptionInterface in Control
commandInitialize to Local COMMAND modeSerial interface (remote locked out)
streamInitialize to STREAM modeSerial 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 DescriptionBus serial control level or edge sensitivity
Accessget/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 DescriptionSet bus stream breakout sequence
Accessget/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:

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 DescriptionCentral auto-connect device
Accessget

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:

Default

0

Get example

> get ce a d
R000003
0

Set example

> set ce a d 4C55CC129A42 
R000009
Success

ce c c

Brief DescriptionCentral connection count
Accessget

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 DescriptionCentral connection mode
Accessget

Description

Returns the connection mode when connected with a peripheral.

Connection modes are:

Arguments

-

Default

-

Get example

> get ce c m
R000006
none

ce s d

Brief DescriptionCentral scan high duration
Accessget/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 DescriptionCentral scan high interval
Accessget/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 DescriptionAdvertising low duration
Accessget/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 DescriptionAdvertising low interval
Accessget/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 DescriptionCentral scan mode
Accessget

Description

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

Arguments

-

Default

-

Get example

> get ce s m
R000005
off

GPIO

gp u

Brief DescriptionGPIO usage
Accessget

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
!  # Description
#  0 i2c_sda
#  1 i2c_scl
#  2 user_tx
#  3 none
#  4 none
#  5 user_rx
#  6 stdio,ipd,factory
#  7 reserved
#  8 none
#  9 stdio,ipd
# 10 stdio,olo
# 11 stdio,olo
# 12 none
# 13 none
# 14 stdio,olo

System

sy a t

Brief DescriptionSystem activity timeout
Accessget/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 DescriptionSystem board name
Accessget/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 DescriptionSystem command echo
Accessget/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 DescriptionSystem command header
Accessget/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 DescriptionSystem command mode
Accessset

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 DescriptionSystem command prompt enabled
Accessget/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 DescriptionSystem device name
Accessget/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 DescriptionSystem indicator status LED blink behavior
Accessget/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/CCHigh = BB/DDPeriodDuty CycleNotes
01010.25s50%Fastest possible blink. Duty cycle = 50%
04041.00s50%1 Hz --- default blink pattern when not connected
007f.100%Always on --- default blink pattern when connected
1c044.00s12.5%period = (28 + 4 = 32) x 0.125, duty cycle = 100*4/(28+4)
7f7f31.75s50%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 DescriptionSystem OTA enabled
Accessget/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 DescriptionSystem print level
Accessget/set

Description

System print level. Print levels:

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 DescriptionSystem remote command enabled
Accessget/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 DescriptionSystem go-to-sleep timeout
Accessget/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 DescriptionSystem UUID
Accessget

Description

Returns the hardware UUID of the module.

Get example

> get sy u
R000042  
0D06EA434C55CC01B10B1411081309007E615F0A

sy v

Brief DescriptionFirmware version
Accessget

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 DescriptionSystem wakeup timeout
Accessget/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 DescriptionUART baud
Accessget/set

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

Brief DescriptionUART flow
Accessget/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 DescriptionUser storage
Accessget/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!