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:

Baud rate: 115200
Date: 8 bit
Parity: none
Stop: 1 bit
Flow control: none

See Getting Started, Opening a TruConnect Terminal.

Serial Bus Modes

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

local COMMAND mode --- TruConnect commands are issued via the serial UART interface (the remote COMMAND interface is disabled)
STREAM mode --- data is transferred directly between the serial UART interface and the wireless BLE interface
remote COMMAND mode --- TruConnect commands are issued via the wireless BLE interface (the local COMMAND interface is disabled)

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

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

Assert a GPIO (manually via a push button or using a microcontroller)
Issue the str command (when the module is in either local or remote command mode)
Set the TruConnect mode characteristic (using a remote BLE host such as an iOS/Android/Windows app or another TruConnect module)

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 GPIO	Bus mode selection	Description
configured	manual	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 configured	automatic	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:

if manual bus mode is selected, either:
- boot the module with the bu i (bus mode initialization) variable set to command
- assert/toggle the mode_sel GPIO --- see the gfu (GPIO function) command
if automatic bus mode is selected:
- disconnect any remote device

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

STREAM mode

To enter STREAM mode:

if manual bus mode is selected, either:
- boot the module with the bu i (bus mode initialization) variable set to stream
- with the module in local COMMAND mode, assert/toggle the mode_sel GPIO --- see the gfu (GPIO function) command.
if automatic bus mode is selected:
- connect remote device
issue the str (stream) command

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:

Set the BLE mode characteristic to REMOTE_COMMAND_MODE.
- For remote control via a tablet or phone, see Communicating via BLE, TruConnect Services and Characteristics.
- For remote control via another TruConnect device, see the rbmode command.
- The device to be controlled must have remote access enabled. See sy r e. Note: It is only possible to enter remote COMMAND mode with a remote host using the BLE interface, and only if the module is in STREAM 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 ...

R denotes a Response header.
X is the error code (response error codes are listed below).
YYYYY is the response data length in bytes including a trailing \r\n. The response data length is zero if no data is available, or >2 (including \r\n) if data is available.
<response data>. If the response data length is >0, the <response data> is the data returned from TruConnect in response to the command.

Response Error Codes

  0 = Success                    
  1 = Command failed             
  2 = Parse error                
  3 = Unknown command            
  4 = Too few args               
  5 = Too many args              
  6 = Unknown variable or option 
  7 = Invalid argument

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

L denotes a Log header.
X is the log level.
YYYYY is the log message length in bytes including a trailing \r\n. Log messages are always >2 bytes in length and including terminating \r\n characters.
<log message>. The log message returned by TruConnect in response to the command.

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.