TruConnect Command Reference

This page provides a list of TruConnect commands with a full description of how to use each command.

Command Editing

The TruConnect 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 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) = 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
- adc --- read an ADC value
- adv --- advertise as a peripheral
B
- beep --- send a beep to a speaker
C
- con --- connect to a peripheral
D
- dct --- disconnect from a peripheral
F
- fac --- restore factory reset
G
- gdi --- configure GPIO direction/initial value (stdio)
- get --- get the value of a variable
- gfu --- configure GPIO function
- gge --- read a GPIO value (stdio)
- gse --- write a GPIO value (stdio)
P
- pwm --- control the Pulse Width Modulator
R
- rbmode --- change bus mode of a remote device
- reboot
S
- save --- save configuration variables
- scan --- scan for nearby peripherals
- set --- set the value of a variable
- sleep
- str --- switch to stream mode
V
- ver --- version

Description of Commands

adc

Read an ADC value

Description

Get value of ADC in mV. Valid only for GPIOs that support ADC. The adc command can be used regardless of the GPIO function configuration.

Syntax

> adc <GPIO>

Example

> adc 2
R000006
1404
> adc 3
R000006
2563

adv

Advertise as a peripheral

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 h d (default: 300 seconds), then turns off.

The advertising settings correspond to the following advertising modes.

high - High Duty Cycle Undirected Advertising
low - Low Duty Cycle Undirected Advertising
off - No Advertising

For more information, see the variables used to control advertising:

Syntax

> adv [<low/high/off>]

Example

> adv high
Success

beep

Send a beep to a speaker

Description

Emit a short beep from a speaker. The speaker must be connected to a GPIO that is configured with the GPIO alternate function: speaker

Syntax

> beep <duration> ... where <duration> is expressed in milliseconds, ranging from 50 to 1000.

Example

> beep 200
Success

con

Connect to a peripheral

Description

Connect to a peripheral with the specified index number. The index number is obtained from the output of the scan command.

Syntax

> con <index>

Example

> con 1
Success

dct

Disconnect from a peripheral

Description

Disconnect from a peripheral

Syntax

> dct

Example

> dct
Success

fac

Factory reset

Description

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

Syntax

> fac <BD_ADDRESS>

Example

> get bl a
4C55CC129A42
> fac 4C55CC129A42
TruConnect-1.0.0.14, Built:Nov 10 2014 17:07:33, Module:AMS002.5, Board:AMS001-E01.2
[COMMAND_MODE]

gdi

GPIO direction

Description

Set the direction and initial state of a general purpose I/O pin (configured as stdio). See Peripherals.

Syntax

> gdi <GPIO#> <direction> where

<GPIO#> - The GPIO number
<direction> - may be any one of the following types.
- in : Input high impedance
- ipd : Input, pull-down
- ipu : Input, pull-up
- olo : Output initialized to low value
- ohi : Output initialized to high value
- hiz : High impedance

Example

> gdi 12 in
R000009
Success

get

Get the value of a variable

Description

Get the value of the specified variable.

Syntax

> get <variable>

Example

> get ua b
115200

gfu

GPIO function

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.
Factory reset is an exception: it may be moved to any pin, but not de-assigned by setting to none.
A list of available functions is shown in the following table.
Note: A save and reboot is required after configuring a function, with the exception of the none, stdio and pwm functions.

Function	Description
`activity`	BLE and UART activity indicator. Can act as a system power off, if the `activity` GPIO pin is connected to the enable of a power regulator. See Power Management.
`ble_blink`	GPIO toggles regularly when there is activity on the wireless BLE interface. Connect this GPIO to an LED to indicate wireless activity
`conn_gpio`		Connection indication GPIO (output) --- Logic 0 : Not connected to any other BLE device --- Logic 1 : At least one connection is established
`factory`		Factory reset pin. May be moved, but NOT deassigned.
`mode_sel`		Selects bus serial mode (input). If `mode_sel` configured, bus mode selection is manual. If `mode_sel` 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, `mode_sel` works as follows: edge: --- mode toggles on rising edge level: --- low level - COMMAND_MODE --- high level - STREAM_MODE
`none`	GPIO is not assigned to any function (high impedance)
`pwm`	GPIO configured for use with the PWM command. Available only for a GPIO with a PWM connected.
`reserved`	GPIO not available to user. Do not connect to this pin.
`shutdown`	GPIO has two possible functions. --- If `activity` GPIO is not configured, acts as edge triggered sleep/wake toggle --- if `activity` GPIO is configured as described, and `shutdown` is asserted for more than 1 second, shuts down module. See Power Management.
`sleepwake`	GPIO level controls sleep or wake - sleep low, wake high. See Power Management.
`speaker`		GPIO configured for use with 'beep' command.
	This works only with a GPIO connected to a speaker
	(GPIO 13 on Wahoo Eval Board).
`status_led`		GPIO is configured to operate as general status indicator (output) to show the connection status. The blink pattern is controlled with the sy i s variable. Works with any LED on the Wahoo EVB - GPIO 10, 11 or 14.
`stdio`	GPIO is configured as a standard IO (input/output/others). Use the following commands to control pins configured as stdio: --- gdi: configure direction & configure initialization value --- gse: set the output level --- gge: get the input level
`stream_gpio`		GPIO to indicate the serial bus is set to STREAM mode (output) --- Logic 1: STREAM mode --- Logic 0: COMMAND mode
`user_cts`*	The user UART CTS function (input) is assigned automatically to GPIO 4 when flow control is enabled by the set ua f 1 command. Any other function configured for this pin is overridden.
`user_rts`*	The user UART RTS function (output) is assigned automatically to GPIO 3 when flow control is enabled by the set ua f 1 command. Any other function configured for this pin is overridden.
`user_rx`	GPIO will be used as User UART RX (input).
`user_tx`	GPIO will be used as User UART TX (output).

NOTES:

^ This function may be assigned to only one pin at any time
- This function is auto-assigned and cannot be manually controlled See also: gdi, gge, gse, bu s c, gp u, Peripherals - GPIOs

Syntax

> gfu <GPIO#> <function>

Example 1

> gfu 6 none
Success
> gfu 6 mode_sel
Success

Example 2

> gfu 13 speaker
Success

gge

Get GPIO value

Description

Get the current value of a general purpose I/O pin configured for the stdio function. See Peripherals.

Syntax

> gge <GPIO#>

Example

> gge 12
1

gse

Set GPIO value

Syntax

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

Example

> gse 12 0
Success
> gge 12
0

pwm

Control a Pulse Width Modulator

Description

The pwm command controls a pulse width modulator GPIO. See Peripherals. The GPIO must be set to the pwm function. See gfu.

Syntax

> pwm <gpio> <[low_count high_count]|[stop]> The internal PWM clock rate is 128 * 1024 = 131072 Hz.

The PWM signal is high for high_count clock cycles, and low for low_count clock cycles.

The maximum value of high_count + low_count is 1023, so the minimum frequency is about 128Hz and the maximum frequency is 65536Hz.

Note: It is not possible to achieve a duty cycle of 100%. To set a GPIO high or low, use gfu to set the GPIO to the stdio function, use gdi to set the direction to ohi or olo, then use gse to set the value to 1 or 0.

Duty cycle is expressed as a fraction of 1.0 in the equations below.

high_count =     131072 x duty_cycle
             ---------------------------
                      frequency

low_count  = 131072 x (1.0 - duty_cycle)
             ---------------------------
                      frequency

For a 0.5 (50%) duty cycle: 

high_count = low_count = 131072 x 0.5
                         -------------
                           frequency

Example

Play middle C on the Wahoo eval board speaker, then stop the PWM:

> gfu 13 none         <-- De-assign any existing function 
                          on GPIO 13 (may not be needed)
Success
> gfu 13 pwm          <-- Configure GPIO 13 
                          for use with the PWM
Success
> pwm 13 250 250      <-- Start PWM on GPIO 13 with 
                          50% duty cycle since 
                          high = low = 250
Success
> pwm 13 stop         <-- Stop PWM
Success

rbmode

Change remote device bus mode

Description

Change the bus mode of a remote TruConnect device operating as a peripheral. The rbmode command enables a TruConnect device 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 the mode_sel 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)

For a detailed description of bus modes, see Serial Bus Modes, Serial Interface.

For a demonstration of remote control of a TruConnect device, 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 using rbmode.
The remote device must have remote access enabled. See sy r e

Syntax

> rbmode [stream | remote]

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

reboot

Reboot

Description

Reboot the application. After reboot, the bus serial mode is displayed between square brackets.

Syntax

> reboot

Example

> reboot
[COMMAND_MODE]
> set bu i stream
Success
> save
Success
> reboot
[STREAM_MODE]

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.

The save factory <BD_ADDR> command sequence writes the current value of all variables to a unique factory configuration.

Factory settings may be saved repeatedly in the lifetime of the module.

Before factory settings are saved, double check the module configuration is correct. To avoid accidentally running the factory save sequence, BD_ADDR must be passed as an argument.

If factory settings are saved with the lock option, factory settings cannot be overwritten. After running the save command once with the lock option, issuing the save factory command again results in the response Command failed.

The BD_ADDR may be obtained using the get bl a command. When factory reset is activated, user settings are discarded and factory settings are restored. See fac.

Syntax

> save [factory <BD_ADDR>] [lock]

Example 1

Save user config

> save
Success

Example 2

Save factory settings

> get bl a
4C55CC012345                 
> save factory 4C55CC012345                                 
Success

Example 3

Save factory settings and lock. Locked settings cannot be overwritten.

> save factory 4C55CC012345 lock
Success

scan

Scan for nearby peripherals

Description

Scan for nearby BLE peripherals. Scan mode may be low or high, which determines the scan rate. If no scan mode argument is supplied, the default is high.

Scanning continues for a fixed period which is 300 seconds for low and 30 seconds for high. 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.

By default, scan is restricted to peripherals with the service UUID specified in the variable bl s u. Use the scan argument all to remove this restriction.

Issue scan off to turn off scanning immediately.

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.

Peripherals with the service UUID specified by bl s u are returned in scan results by default. To scan for peripherals advertising with a specific service UUID, provide the service UUID as an argument to the scan command. Or, to scan for all BLE peripherals, use the all parameter.

Each peripheral detected during scanning is listed only once in scan results. To enable duplicate result listing, use the dup parameter. This parameter is useful for obtaining real-time information about the signal strength (proximity) of a peripheral.

Syntax

> scan [<low / high> <all / service_uuid> <dup>] | [<off / results>]Examples:

scan
scan low
scan high
scan off
scan dup
scan all
scan high dup
scan high 175f8f23-a570-49bd-9627-815a6a27de2a
scan low all dup
scan results

Example

scan high
R000038
! # RSSI BD_ADDR           Device Name
# 1  -46 4C:55:CC:1a:3d:df AMS-3DDF
# 2  -46 4C:55:CC:1a:30:1f AMS-301F

set

Set the value of a variable. See the variable documentation for details of valid arguments.

Description

Syntax

> set <variable> <args>

Example

> set sy c e 0
Success

sleep

Sleep

Description

Put the module into the lowest-power sleep state. The module sleeps until a wakeup event occurs such as an interrupt on the mode_sel GPIO (Button 2 on the Wahoo EVB).

Syntax

> sleep

Example

> sleep
R000009
Success

str

Stream mode

Description

Switch to serial bus STREAM mode. Press Button 2 on the Wahoo EVB to toggle back to COMMAND mode. See Serial Interface.

Syntax

> str

Example

> str
STREAM_MODE

ver

Version

Description

Returns the TruConnect firmware version.

This is the command equivalent of the sy v variable.

Syntax

ver

Example

> ver
TruConnect-1.0.0.1, Built:Nov  9 2014 12:58:29, Module:AMS001.4, Board:AMS001-E01.2