ESP8266 and ESP32 TCP Command Handler

Overview

The TCP Command Handler is an Arduino library to decode and dispatch commands sent over a wireless TCP connection. It supports Espressif micros based on the ESP32 and ESP8266 chipsets such as SparkFun’s ESP32 Thing and ESP8266 Thing, the Wemos D1 mini and D32 Pro.

When the library receives a command it can either:

1. Call a function in your Arduino sketch
2. Update a variable

Connect to an ESP8266 or ESP32 running the TCP Command Handler by creating a TCP/IP connection to your device with the Connection Manager. Our article on talking to an ESP32 over WiFi has a detailed walk-through.

Using the TCP Command Handler

To use the serial command handler in your program you need to:

1. #include "TCPCommandHandler.h" to make the library available to your program
2. Include the Arduino WiFi library:
   • #include "WiFi.h" on the ESP32
   • #include "EspWiFi.h" on the ESP8266
3. Create a WiFiServer Server(23/*server port*/); variable
4. Create a TCPCommandHandler<> CmdHandler(Server); variable
5. In your setup function, add the commands you want to handle:
   • To call a function when a command is received use CmdHandler.AddCommand(F("CommandName"), Cmd_FunctionToCall)
   • To update a variable when a command is received use CmdHandler.AddVariable(F("CommandName"), VariableName)
6. Implement the command functions. Each must take a single CommandParameter reference, even if it isn’t used.
7. Call CmdHandler.Process() in your main loop function to receive and decode commands

The MegunoLink Interface Panel and Message Monitor visualizers can both be used to send commands.

You’ll also need to connect to your WiFi network and initialize the Server in your setup function. Check out the example below for more detail, or our article how do I connect to a wireless network with the ESP32? for a easier way to manage your network credentials.

TCP Command Handler Reference

The TCPCommandHandler is implemented as a C++ template:
template <int MAX_CONNECTIONS = 1,
int MAX_COMMANDS = 10, int CP_SERIAL_BUFFER_SIZE = 30,
int MAX_VARIABLES=10>
class TCPCommandHandler(…)

It uses a fixed size arrays to store:

• the state of each active connection (1, by default)
• command names and functions to call (up to 10, by default)
• variable names and the variables they map to (up to 10, by default)

The default values can be changed using the template arguments.

Although the TCP Command Handler can support multiple connections, only one active connection is supported by default. Once the number of available slots is exhausted further connections will be rejected until once of the active connections is released. Each connection reserves its own serial buffer, along with additional state to manage the TCP connection. So reserving space for too many active connections can consume a lot of memory. Typically 1 or 2 slots is sufficient.

TCP Command Handler construction

The TCPCommandHandler constructor takes three arguments. The first is required; the remaining two are optional:
TCPCommandHandler(WiFiServer &Server, char StartOfMessage = '!', char EndOfMessage = '\r')

• Server is the TCP server that the command handler should listen to. It can be on any port but should be initialized (Server.begin()) before the command handler’s Process() function is called,
• StartOfMessage is the character that the command handler looks for to mark the start of a new message. By default it is a ‘!’. Whenever the command handler encounters the start character it will discard whatever it has so far and begin building a new message. So you need to make sure the start character will never be found in the message itself.
• EndOfMesasge is the character that marks the end of a message. By default it is a carriage return (‘\r’). When the end character is found, the command handler tries to match the command it has received and call the matching function. You need to make sure the end character is never found as part of the message itself.

Example TCP Command Handler declarations

Commands, Variables and the Default Handler

Commands, variables and the default handler are configured for the TCP Command Handler in the same way as the Serial Command Handler.

Briefly, in void setup(), call:

• CmdHandler.AddCommand(F("CommandName"), Cmd_HandlerFunction); and the TCP Command Handler will call Cmd_HandlerFunction whenever it receives CommandName.
• CmdHandler.AddVariable(F("VariableName"), Variable); and the command !VariableName Value\r will update Variable to Value.
• CmdHandler.SetDefaultHandler(UnknownMessageHandler); and the function void UnknownMessageHandler() will be called whenever a command is received that doesn’t match any of the registered commands.

Please refer to the Serial Command Handler documentation for more details including function signatures for Cmd_HandlerFunction and working with parameters.

Example

This example accepts commands to adjust the blink rate of an LED. On the ESP8266 it uses the built-in LED; on the ESP32 you have to connect an LED between Pin 23 and ground via a 330 ohm resistor.

The program connects to a WiFi access point (ConnectToWiFi()) and sets up a TCP server on port 23. It advertises itself using mDNS so that MegunoLink can find the device’s IP address (AdvertiseServices()). The MakeMine function appends a semi-unique number to the device name “MyDevice” so you can distinguish between several blinking devices on the same WiFi network.

Use MegunoLink’s TCP Client connection to connect to the TCP Server on the ESP Device. This example advertises its IP address using mDNS, so to open a connection:

• Add a TCP Client connection in the Connection Manager
• Select the mDNS option
• Choose _n8i-mlp._tcp as the service
• Choose the device from the host list
• Click Connect

The sketch responds to the commands:

• !OnTime nnn\r\n: changes the time the LED spends on to nnn ms.
• !OffTime nnn\r\n: changes the time the LED spends off to nnn ms.
• !ListAll\r\n: reports the current LED on and off time.

Once you’ve opened a connection, use the Set buttons to change the blink rate and List Config to display the current configuration in the serial monitor.

MegunoLink WiFi Blink Project

This MegunoLink project uses an Interface Panel visualizer to send commands to the WiFiBlink sketch.

Send commands to an ESP32/ESP8266 WiFi device using a TCP Client connection

Arduino Sketch for ESP32/ESP8266