Serial Interface

TruConnect provides a flexible serial interface. The serial protocol for issuing commands and receiving responses can be used locally via the UART interface or remotely via the BLE interface. The protocol is easy to use for both humans and machines alike.

TruConnect also allows data to be streamed directly between the UART and BLE interfaces.

The serial bus mode determines whether data is streamed, or which interface can send commands to TruConnect.

For a demonstration of serial bus modes, bus mode selection, and remote control of a TruConnect device, see the Bus Mode Selection and Remote Control application note.


UART Protocol

UART baud rate is determined by the ua b variable. The default is 115200.

UART flow control is determined by the ua f variable. The default is 0, no flow control.

The serial port settings, corresponding to the TruConnect defaults, are 115200 8N1 with NO hardware flow control:

See Getting Started, Opening a TruConnect Terminal.

Serial Bus Modes

A module running TruConnect can operate in any one of three distinct bus modes:

The diagram below shows a schematic representation of the three bus modes.

There are various ways to make TruConnect transition between bus modes including:

Manual and Automatic Bus Mode Selection

When a TruConnect device boots up, it may be desirable to control it via the UART interface, or by a remote BLE device.

To allow for either option to work without further configuration, TruConnect supports a choice of manual and automatic bus mode selection.

Bus mode selection depends on whether the mode_sel GPIO is configured. See the gfu (GPIO function) command.

mode_sel GPIOBus mode selectionDescription
configuredmanual
  • bus mode initializes to the value set by bu i
  • mode_sel GPIO determines if the bus is in STREAM mode or local COMMAND mode
  • if the bus is in STREAM mode, the remote device can use the mode characteristic to switch to remote COMMAND mode, if enabled. See sy r e
not configuredautomatic
  • if a remote device is connected: the bus is in STREAM mode
  • if NO remote device is connected: the bus is in local COMMAND mode
  • if the bus is in STREAM mode, the remote device can use the mode characteristic to switch to remote COMMAND mode, if enabled. See sy r e

The state diagrams below show the possible transitions.

Manual Bus Mode Selection

Automatic Bus Mode Selection

local COMMAND mode

To enter local COMMAND mode:

See Command Protocol for details of sending commands and handling responses.

STREAM mode

To enter STREAM mode:

In Stream mode, bytes or characters sent from the host to a serial interface are transparently pushed by TruConnect to the remote device via the wireless interface.

Conversely, bytes or characters received from a remote device are transparently pushed by TruConnect to a serial interface connected to the host.

The Getting Started example is a typical application that uses stream mode.

remote COMMAND mode

To enter remote COMMAND mode:

See Command Protocol for details of sending commands and handling responses.


Command Protocol

Both local COMMAND mode and remote COMMAND mode provide an asynchronous command interface that a host may use to send and receive control and setup information. Command mode is typically used by a host to configure TruConnect.

Command mode is the primary mode used to configure TruConnect. Grasping how command mode works, and the options provided, is the key to mastering the use of TruConnect. The serial interface is designed to cater for humans and machines alike, and the interface is configurable to suit the needs of both.

In Command mode, control, data and debug logs (if enabled) are interleaved.

Configuration

In command mode, TruConnect and the ACKme module effectively provides a slave interface to the host. The host is the master and TruConnect is the slave. The host initiates all transactions which follow the format of "host issues a command, TruConnect provides a response". TruConnect commands are used by the host to read and write TruConnect variables, send control information, and send and receive data across network connections.

The system command mode variable (sy c m) is provided for convenience to make it easy to switch between human mode and machine mode.

Setting sy c m to human or machine conveniently changes the value of each of the following variables to configure the desired command mode.

Human Friendly Command Mode

By default, the serial interface is configured to be human friendly with the following settings. See System Variables.

set sy c m human

is equivalent to:

set sy p all  -> Turn on all debug & informational prints
set sy c h 0  -> Disable response header
set sy c p 1  -> Turn on the user prompt
set sy c e 1  -> Turn on echo to see what you're typing

Machine Friendly Command Mode

To configure the serial interface for machine friendly operation, use the following settings. See System Variables.

set sy c m machine

is equivalent to:

set sy p 0    -> Turn off all debug & informational prints
set sy c h 1  -> Enable response header
set sy c p 0  -> Turn off the user prompt
set sy c e 0  -> Turn off echo

Command Format

Commands sent to TruConnect are formatted as shown in the following table. The <command name> is a TruConnect command issued by the host, and [variable name <argument>]\r\n is an (optional) TruConnect variable name and accompanying argument terminated by a carriage return and newline character. <command name> [variable name <argument>]\r\n

Response Format

Responses from TruConnect follow the format shown in the text below.

RXYYYYY\r\n
<response data>

where ...

Response Error Codes

CodeDescriptionFrom Commands
0Successall
1Command failedall
2Parse errorall
3Unknown commandall
4Too few argsall
5Too many argsall
6Unknown variable or optionall
7Invalid argumentall
8Timeoutcon
9Security mismatchcon

Log Format

If sy c p (system print level) is greater than 0, a log header together with one or more informational debug logs may be returned in addition to a response header and response data when a command is issued. Log headers follow the format shown in the table below.

LXYYYYY\r\n
<log message>

where ...

Packet Size Limit

TruConnect has a limitation on the size of BLE packets, related to the Tx UART FIFO size of 16 bytes. This packet size limit may become evident when sending bytes rapidly to a TruConnect BLE receiving device running at a lower BAUD rate than the transmitting BLE device. The workaround is to send no more than 15 bytes at once.