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.

Interface Modes

The WiConnect serial interface may be used in any of three different modes.

• Command Mode provides an asynchronous command interface that a host may use to send and receive control and data information. Command mode is typically used by a host to configure WiConnect, however it may also be used by simple hosts that need ultimate master/slave control over information sent to, and received from the module.
• Stream Mode provides a streaming interface that transparently connects a WiConnect serial interface (UART or SPI) with a network stream such as a UDP or TCP client or server. Stream mode provides a simple 1-1 connection between a physical serial interface and a network stream. 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.
• Packet Mode Packet mode enables complex connections between multiple serial interfaces and network streams.

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.

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 Format

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

Response Format

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

RXYYYYY\r\n
<response data>

where ...

• R denotes a Response header. NOTE! If the module is operating in Safe Mode, R is replaced with S.
• 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 WiConnect 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
  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 ...

• 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\ncharacters.
• <log message>. The log message returned by WiConnect in response to the command.

Stream Mode

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

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, which is planned for an upcoming release of WiConnect, will provide the option to connect one or more serial interfaces to one or more network streams for ultimate data multiplexing flexibility!