Serial Interface

WiConnect provides a flexible serial interface. It supports various serial protocols and modes, and is easy to use for both humans and machines alike. WiConnect supports two serial protocols, UART and SPI.

UART Protocol

A single or dual UART is available for use by the host MCU. If a host can support two UARTs, one UART may be used for control and data communication, and the other used for debug logging. If a single UART is available, control, data and debug logs (if enabled) are interleaved.

SPI Protocol

SPI provides a higher speed communications interface for higher bandwidth applications such as audio and video. Full support for a serial-SPI communications interface will be added in an upcoming release of WiConnect.

Sending Commands and Streaming Data

A WiConnect module connects a host system to a network via Wi-Fi.

First the WiConnect module is configured to connect to the network and to other hosts on the network. Then the WiConnect module allows the local host to communicate with other hosts by exchanging data.

To exchange data with other hosts, you can stream data transparently between the Wi-Fi interface and the local serial interface.

Alternatively, you use WiConnect commands to mediate the exchange of data.

WiConnect commands can be issued via:

The local serial interface and the remote terminal are mutually exclusive: connecting a remote terminal disables the local serial interface to the command parser.

The local serial interface can either stream data, or send commands and receive responses. It cannot do both simultaneously.

Note: to guarantee that no characters are dropped when using the local serial interface, uart.flow must be turned on. This applies at any baud rate.

The HTTP RESTful API interface is available at all times, if the HTTP server is running and the RESTful API is enabled.

Access to the WiConnect command parser is determined by:

Serial Bus Mode

Serial bus mode concerns the local UART serial interface.

A module running WiConnect can operate in two distinct local serial bus modes, determined by the bus.mode variable:

WiConnect commands can also be issued via the local serial interface when in STREAM mode:

The diagram below shows a schematic representation of access to the command parser via the serial interface and the Wi-Fi interface.

Note that this diagram illustrates access to the command parser only. Access via WiConnect commands to Wi-Fi ports and other module features is unaffected by serial bus mode or remote terminal status.

Command configuration and protocols are as described in Command Mode and Command Protocol, whether commands are issued via the UART in COMMAND mode or COMMAND breakout, via the remote terminal, or via the HTTP RESTful API.

In STREAM mode, you can stream data between the UART and the Wi-Fi interface, as described in Stream Mode.

As the STREAM mode + Remote Terminal case in the above diagram suggests, you can stream data to a remote host, and at the same time issue commands to the WiConnect module via the remote terminal or the HTTP Server RESTful API. A command issued to the command parser blocks commands from other interfaces until it is completed.

The state diagram below shows the transitions between serial bus modes.

Rebooting to COMMAND mode

To reboot to COMMAND mode, set the bus.mode variable to command, save, and reboot:

set bus.mode command
save
reboot

COMMAND breakout from STREAM mode

To issue commands in STREAM mode, send the breakout character sequence specified by the bus.stream.cmd_seq. This is by default $$$.

Alternatively, set up a GPIO to enter command mode by enabling the bus.stream.cmd_gpio GPIO function.

On switching from STREAM mode to local COMMAND mode, WiConnect responds with Command Mode Start.

You can then issue any WiConnect commands.

You can set bus.mode to command and save, so that on the next reboot the WiConnect module starts in local COMMAND mode.

When you have entered local COMMAND mode from STREAM mode via a breakout sequence or GPIO, you can return to STREAM mode by issuing the exit command.

Rebooting to STREAM mode

To switch to STREAM mode from command mode, set the bus.mode variable to stream and reboot:

set bus.mode stream
save
reboot

Exit from COMMAND Breakout

When you have entered local COMMAND mode, or remote COMMAND mode, from STREAM mode via a breakout sequence or GPIO, you can return to STREAM mode by issuing the exit command. WiConnect responds with Command Mode Stop. For example:

Sequences and CommandsDescription

$$$
ver
...
exit


Break out of STREAM mode
Issue some WiConnect commands

Return to STREAM mode

Using the Remote Terminal

When the remote terminal is enabled and connected via telnet, the local command interface is disabled. However the UART can still stream to the Wi-Fi interface if the module is in STREAM mode. When a WiConnect module is in COMMAND mode and a remote terminal is connected, disconnecting the remote terminal switches back to COMMAND mode. You can then issue commands via the local serial interface.

Enabling and Connecting the Remote Terminal

Enable the remote terminal with remote_terminal_enabled:

set remote_terminal.enabled 1
save
reboot

Then connect a remote device via telnet to the WiConnect module. The default port is 2000. The host IP or name depends on the WiConnect configuration.

For details, see the Wi-Fi Remote Terminal application note.

Command Mode

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

Note: When controlling WiConnect via an MCU, we suggest using machine mode, described below.

Configuration

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

The variable system.cmd.mode is provided for convenience to make it easy to switch between human mode and machine mode. Setting system.cmd.mode 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 the system variable documentation.

set system.print_level all       -> Turn on all debug & informational prints
set system.cmd.header_enabled 0  -> Disable a response header
set system.cmd.prompt_enabled 1  -> Turn on the user prompt
set system.cmd.echo on           -> 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. Detailed information about these settings is available in the system variable documentation.

set system.print_level 0         -> Turn off all debug & informational prints
set system.cmd.header_enabled 1  -> Enable a response header (described below)
set system.cmd.prompt_enabled 0  -> Turn off the user prompt
set system.cmd.echo off          -> Turn off character echo

Command Protocol

WiConnect commands are formatted as shown below. <command name> <arguments>\r\n where:

In the case of the get and set commands, the arguments are in the form: <variable name> <arguments> where:

The command is terminated by a carriage return and newline character (\r\n).

Response Format

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

RXYYYYY\r\n
<response data>

where ...

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
  8 = Serial command line buffer overflow

Log Format

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

Stream Mode

As depicted in the following diagram, stream mode provides a transparent connection between a serial port and a network stream such as a UDP or TCP client or server. It is perfect for implementing applications such as a wireless serial port.

Bytes or characters sent from the host to a serial interface are transparently pushed by WiConnect to a network stream via a wireless interface. Conversely, bytes or characters received by a network stream (from a remote server) via a wireless interface are transparently pushed by WiConnect to a serial interface connected to the host. A wireless serial port is a typical application that uses stream mode.

Stream mode is used primarily by host applications that can handle asynchronous data (with the optional use of hardware flow control). It is perfectly suited to applications that only need to use a single network stream at any one time.

Configuration

The simplest way to setup an ACKme module to use Stream mode is to do all the WiConnect configuration first using command mode, then reboot into stream mode. Configuration involves just a few simple steps: - Setup a wireless and network interface to use with stream mode e.g. wlan interface and TCP client. This typically requires setting up the wireless interface and network stream to auto-connect, or enable connection using a GPIO control pin. - Set the serial bus.mode to stream. - Then save and reboot the module.

Both the wlan and softap interfaces have an auto-start on bootup capability using the wlan.auto_join.enabled and softap.auto_start variables. The TCP server has auto-start capability using the tcp_server.auto_start variable. Network clients can be started using a GPIO or manually by breaking out of stream mode as described below.

Breaking out of Stream Mode

When the serial bus is in Stream mode, commands are disabled and every character sent to the serial port is automatically forwarded to a network stream. There are two ways to break out of stream mode and enable command mode entry temporarily. The first method is to send a character sequence, configurable with the bus.stream.cmd_seq, after 3 seconds of inactivity on the serial interface. By default, the stream break out sequence is $$$. The other option available to break out of stream mode is to use a GPIO configurable with the bus.stream.cmd_gpio variable. When you're done entering commands, return to stream mode by simply issuing the exit command.

Packet Mode

Packet mode is planned for an upcoming release of WiConnect. Packet mode enables complex connections between multiple serial interfaces and network streams.