TruConnect Command Reference
This page provides a list of TruConnect commands with a full description of how to use each command.
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.
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.
A description of how to use the command, together with notes about available options and arguments.
Formal command syntax with a listing of all available options and arguments.
Alphabetical List of Commands
- beep --- send a beep to a speaker
- con --- connect to a peripheral
- dct --- disconnect from a peripheral
- fac --- restore factory reset
- pwm --- control the Pulse Width Modulator
- ver --- version
Description of Commands
Read an ADC value
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.
> adc <GPIO>
> adc 2 R000006 1404 > adc 3 R000006 2563
Advertise as a peripheral
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
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:
- bl v h d - advertising high mode duration
- bl v h i - advertising high mode interval
- bl v l d - advertising low mode duration
- bl v l i - advertising low mode interval
> adv [<low/high/off>]
> adv high Success
Send a beep to a speaker
Emit a short beep from a speaker. The speaker must be connected to a GPIO that is configured with the GPIO alternate function:
> beep <duration> ... where
<duration> is expressed in milliseconds, ranging from 50 to 1000.
> beep 200 Success
Connect to a peripheral
Connect to a peripheral with the specified index number. The index number is obtained from the output of the scan command.
This command blocks until either a successful connection is made or the command times out. It then returns a status indicating success or failure.
The central can connect to only one peripheral at a time.
> con <index> [<timeout>]
<index>- the index obtained from the scan command output
<timeout>optional - timeout in seconds before
concommand fails and returns error code "Timeout"
<timeout>range is 1 second to 1000 second. Default: 10 seconds
Return status is as follows:
|An argument is incorrect|
|The device already has a connection to a peripheral|
|Connection establishment timed out|
|If the remote side asks for encryption and it is not enabled locally, or if encryption is enabled and key does not match|
> con 1 Success
Disconnect from a peripheral
Disconnect from a peripheral
> dct Success
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
> fac <BD_ADDRESS>
> get bl a 4C55CC129A42 > fac 4C55CC129A42 TruConnect-18.104.22.168, Built:Nov 10 2014 17:07:33, Module:AMS002.5, Board:AMS001-E01.2 [COMMAND_MODE]
Set the direction and initial state of a general purpose I/O pin (configured as
stdio). See Peripherals.
To set multiple GPIO directions in a single command, see gdis.
> 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
> gdi 12 in R000009 Success
Set direction for multiple GPIOs.
Set the direction for all GPIOs at once, using a list of settings.
This command sets the GPIO to the
stdio function and sets the direction as specified.
The list is a string with a single digit representing the direction for each GPIO, with the GPIO 0 direction at the left.
Directions are enumerated as shown in the table below:
|Enumerator||I/O Type Description|
|0||Input, with pull-up (see gdi |
|1||Input, pull-down (see gdi |
|2||Input, high-impedance (see gdi |
|6||For a |
otherwise do nothing, acting as a placeholder.
Note: there must be exactly one enumerated value for each GPIO. For a GPIO you do not wish to set to a STDIO function, use the placeholder value
6. Supplying the wrong number of values results in an
Invalid argument response.
For example, in the case of the Wahoo evaluation board, there are 15 GPIOs, numbered GPIO 0 to GPIO 14. See Peripherals, GPIO Functions and Pins. You must supply 15 values in the
To set Wahoo GPIOs 6 and 9 to pull-down inputs, and GPIOs 10, 11 and 14 to outputs, use the following command:
To deregister all GPIOs set to a STDIO, supply the value
6 for every GPIO. For example, in the case of the Wahoo:
To set and get multiple GPIO values, see gses and gges. To set individual GPIO function, direction and value, see gfu, gdi, gse and gge. To view a list of GPIO functions, use the command get gp u.
> gdis <value list>
> gdis 666666662233663 Success > gges XXXXXXXX0000XX0
Get the value of a variable
Get the value of the specified variable.
> get <variable>
> get ua b 115200
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
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
|BLE and UART activity indicator. Can act as a system power off, if the |
|GPIO toggles regularly when there is activity on the wireless BLE interface. Connect this GPIO to an LED to indicate wireless activity|
|Connection indication GPIO (output)|
--- Logic 0 : Not connected to any other BLE device
--- Logic 1 : At least one connection is established
|Active low connection indication GPIO (output)|
--- Logic 0 : At least one connection is established
--- Logic 1 : Not connected to any other BLE device
|Factory reset pin. May be moved, but NOT deassigned.|
|Selects bus serial mode (input).|
Depending on setting of variable: bu s c (bus serial control) as edge or level,
--- mode toggles on rising edge
--- low level - COMMAND_MODE
--- high level - STREAM_MODE
|GPIO is not assigned to any function (high impedance)|
|GPIO configured for use with the PWM command.|
Available only for a GPIO with a PWM connected.
|GPIO not available to user. Do not connect to this pin.|
|GPIO has two possible functions.|
|GPIO level controls sleep or wake - sleep low, wake high. See Power Management.|
|GPIO configured for use with 'beep' command.|
|This works only with a GPIO connected to a speaker|
|(GPIO 13 on Wahoo Eval Board).|
|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.
|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
--- gdis: configure multiple GPIO
--- gse: set the output level
--- gses: set multiple GPIO levels
--- gge: get the input level
--- gges: get multiple GPIO levels
|GPIO to indicate the serial bus is set to STREAM mode (output)|
--- Logic 1: STREAM mode
--- Logic 0: COMMAND mode
|Active low GPIO to indicate the serial bus is set to STREAM mode (output)|
--- Logic 1: COMMAND mode
--- Logic 0: STREAM mode
|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.|
|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.|
|GPIO will be used as User UART RX (input).|
|GPIO will be used as User UART TX (output).|
- ^ This function may be assigned to only one pin at any time
> gfu <GPIO#> <function>
> gfu 6 none Success > gfu 6 mode_sel Success
> gfu 13 speaker Success
Get GPIO value
Get the current value of a general purpose I/O pin configured for the
stdio function. See Peripherals.
> gge <GPIO#>
> gge 12 1
Get multiple GPIO values.
Get a list of values for all GPIOs at once.
For GPIOs not set to a
stdio function, the placeholder is
X. The GPIO 0 value is at the left.
To configure GPIO function and direction, see the gdis, gfu and gdi commands. To view a list of GPIO functions, use the get gp u command. To set the values of STDIO GPIOs, see gses and gse.
> gges XXXXXXXXXXXXXX1
Set GPIO value
> gse <GPIO#> <value>
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.
> gse 12 0 Success > gge 12 0
Set multiple GPIO values.
Set the value for all GPIOs at once, using a list of settings.
The list is a string with a single digit representing the value for each GPIO, with the GPIO 0 setting at the left.
The command can set the value only for GPIOs that have been configured with a
stdio function and
output direction. Values for GPIOs not set to a
stdio function are placeholders and have no effect.
Note: there must be exactly one character for each GPIO. For a GPIO set to a STDIO output function, the character must be
1. For other GPIOs you can use any character as a placeholder. Supplying the wrong number of values results in an
Invalid argument response.
For example, the Wahoo evaluation board has 15 GPIOs. See Peripherals. To set GPIO 14 (red LED) and turn it on, use the following commands:
gdis 666666666666663 gses XXXXXXXXXXXXXX1
To configure GPIO function and direction, see the gdis, gfu and gdi commands. To view a list of GPIO functions, use the get gp u command. To get the values of STDIO GPIOs, see gges and gge.
> gses <GPIO values>
> gdis 666666666666663 Success > gses XXXXXXXXXXXXXX1 Success > gges XXXXXXXXXXXXXX1
Control a Pulse Width Modulator
The pwm command controls a pulse width modulator GPIO. See Peripherals. The GPIO must be set to the
pwm function. See gfu.
> 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
olo, then use gse to set the value to
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
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
Change remote device bus mode
Change the bus mode of a remote TruConnect device operating as a peripheral.
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
modecharacteristic 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:
rbmode remoteto set the bus mode of the remote peripheral to remote COMMAND mode
- switches itself to
streammode, either with the
mode_selGPIO (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.
- The bus mode of the remote peripheral device cannot be changed to
local COMMAND modeusing
- The remote device must have remote access enabled. See sy r e
> rbmode [stream | remote]
Read the bus mode of a remote peripheral (returns the value of the BLE
mode characteristic of the remote peripheral).
> rbmode stream
Set the bus mode of a remote peripheral to remote COMMAND mode.
> rbmode remote Success
Reboot the application. After reboot, the bus serial mode is displayed between square brackets.
> reboot [COMMAND_MODE] > set bu i stream Success > save Success > reboot [STREAM_MODE]
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.
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
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.
> save [factory <BD_ADDR>] [lock]
Save user config
> save Success
Save factory settings
> get bl a 4C55CC012345 > save factory 4C55CC012345 Success
Save factory settings and lock. Locked settings cannot be overwritten.
> save factory 4C55CC012345 lock Success
Scan for nearby peripherals
Scan for nearby BLE peripherals. Scan mode may be
high, which determines the scan rate. If no scan mode argument is supplied, the default is
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.
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
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.
> 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
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 the value of a variable. See the variable documentation for details of valid arguments.
> set <variable> <args>
> set sy c e 0 Success
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).
> sleep R000009 Success
Switch to serial bus STREAM mode. Press Button 2 on the Wahoo EVB to toggle back to COMMAND mode. See Serial Interface.
> str STREAM_MODE
Returns the TruConnect firmware version.
This is the command equivalent of the sy v variable.
> ver TruConnect-22.214.171.124, Built:Nov 9 2014 12:58:29, Module:AMS001.4, Board:AMS001-E01.2