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.

Send commands to your wireless device using the Raw Serial Visualizer, Message Monitor Visualizer or build custom Interface Panel that sends commands when you click a button.

Send to TCP Command Handler with Blink User Interface

A simple user interface created with MegunoLink’s Interface Panel Visualizer. Click the buttons to send and receive commands over a wireless TCP Client Connection.

Finding your Wireless Device

MegunoLink can find your device by name if you advertise it with  mDNS.

Check out our getting started guide for Processing Serial Commands with an Arduino for a detailed walk through with our Serial Command handler. The serial command handler processes messages from the Arduino Serial port and is very similar to the TCP command handler, which processes wireless messages.

Serial Command Format

Commands start with a ‘!’ character and end with a carriage return (‘\r’) though both can be customized. Parameters can be included in the serial message and are separated using a space. Example commands:

  1. !SetPoint 4\r
  2. !StartMotor\r
  3. !TurnLEDsOn 1 2 3\r

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.

Arduino Library

You’ll need to install our Arduino library to use the TCPCommandHandler.

TCP Command Handler Reference

The TCPCommandHandler is implemented as a C++ template:
template <int MAX_CONNECTIONS = 1,
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

Declaration Maximum number of Connections Maximum number of Commands Maximum command length Maximum number of Variables Start of Message End of Message
TCPCommandHandler<> CmdHandler(Server); 1 (default) 10 (default) 30 characters (default) 10 (default) ! \r
TCPCommandHandler<2, 15> CmdHandler(Server); 2 15 30 characters (default) 10 (default) ! \r
TCPCommandHandler<1,12,20> CmdHandler(Server); 1 12 20 characters 10 (default) ! \r
TCPCommandHandler<1,10, 30, 15> CmdHandler(Server); 1 10 (default) 30 characters (default) 15 ! \r
TCPCommandHandler<> CmdHandler(Server, '#', '^'); 1 (default) 10 (default) 30 characters (default) 10 (default) # ^

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.


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
TCP Client with mDNS

Use the TCP Client connection to connect with the ESP8266/ESP32 program

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.

You can find the example Arduino sketch and MegunoLink project in Library Examples → Command Handler → WiFiBlink

MegunoLink WiFi Blink Project

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

Send to TCP Command Handler on ESP32/ESP8266

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

Arduino Sketch for ESP32/ESP8266

Start typing and press Enter to search