Cloning the serial port via Telnet.
- This module allows you to do "debugging over the air". So if you already use ArduinoOTA, this is a helpful extension for wireless development. Use
TelnetSpyinstead ofSerialto send data to the serial port and a copy to a Telnet connection. - There is a circular buffer which allows to store the data while the Telnet connection is not established. So it's possible to collect data even when the WiFi and Telnet connections are not yet established.
- It's also possible to create a Telnet session only if it is neccessary: then you will get the already collected data as far as it is still stored in the circular buffer. Data sent from Telnet terminal to ESP8266 / ESP32 will be handled as data received by serial port.
- It is also possible to use more than one instance of TelnetSpy. For example - To send control information on the first instance and data dumps on the second instance.
- Now a rudimentary implementation of the telnet NVT protocol (see RFC854) is included. You can use this functions in PuTTY via its menu "Special Command" i.e. for restarting the ESP.
Add the following line to your sketch:
#include <TelnetSpy.h>
TelnetSpy LOG;
Add the following line to your initialisation block void setup():
LOG.begin();
Add the following line at the beginning of your main loop void loop():
LOG.handle();
- void setPort(uint16_t portToUse)
- void setWelcomeMsg(const char* msg) / void setWelcomeMsg(const String& msg)
- void setRejectMsg(const char* msg) / void setRejectMsg(const String& msg)
- void setMinBlockSize(uint16_t minSize)
- void setCollectingTime(uint16_t colTime)
- void setMaxBlockSize(uint16_t maxSize)
- bool setBufferSize(uint16_t newSize)
- uint16_t getBufferSize()
- void setStoreOffline(bool store)
- bool getStoreOffline()
- void setPingTime(uint16_t pngTime)
- bool setRecBufferSize(uint16_t newSize)
- uint16_t getRecBufferSize()
- void setSerial(HardwareSerial* usedSerial)
- bool isClientConnected()
- void setCallbackOnConnect(void (*callback)())
- void setCallbackOnDisconnect(void (*callback)())
- void disconnectClient()
- void clearBuffer()
- void setFilter(char ch, const char* msg, void (*callback()) / void setFilter(char ch, const String& msg, void (*callback())
- char getFilter()
- void setCallbackOnNvtBRK(void (*callback)())
- void setCallbackOnNvtIP)(void (*callback)())
- void setCallbackOnNvtAO)(void (*callback)())
- void setCallbackOnNvtAYT)(void (*callback)())
- void setCallbackOnNvtEC)(void (*callback)())
- void setCallbackOnNvtEL)(void (*callback)())
- void setCallbackOnNvtGA)(void (*callback)())
- void setCallbackOnNvtWWDD(void (*callback)(char command, char option))
Change the port number of this Telnet server. If a client is already connected, it will be disconnected.
Default: 23
void setPort(uint16_t portToUse)
Change the message which will be sent to the Telnet client after a session is established.
Default: "Connection established via TelnetSpy.\n"
void setWelcomeMsg(const char* msg)
void setWelcomeMsg(const String& msg)
Change the message which will be sent to the Telnet client if another session is already established.
Default: "TelnetSpy: Only one connection possible.\n"
void setRejectMsg(const char* msg)
void setRejectMsg(const String& msg)
Change the amount of characters to collect before sending a Telnet block.
Default: 64
void setMinBlockSize(uint16_t minSize)
Change the time (in ms) to wait before sending a Telnet block if it's size is less than (defined by setMinBlockSize).
Default: 100
void setCollectingTime(uint16_t colTime)
Change the maximum size of the Telnet packets to send.
Default: 512
void setMaxBlockSize(uint16_t maxSize)
Change the size of the ring buffer. Set it to 0 to disable buffering. If buffering is disabled, the system's debug output (see setDebugOutput) cannot be send via telnet, it will be send to serial output only. Changing size tries to preserve the already collected data. If the new buffer size is too small, only the latest data will be preserved. Returns false if the requested buffer size cannot be set.
Default: 3000
bool setBufferSize(uint16_t newSize)
This function returns the actual size of the ring buffer.
uint16_t getBufferSize()
Enable / disable storing new data in the ring buffer if no Telnet connection is established. This function allows you to store important data only. You can do this by disabling storeOffline for sending unimportant data.
Default: true
void setStoreOffline(bool store)
Get actual state of storing data when offline.
bool getStoreOffline()
If no data is sent via TelnetSpy, the detection of a disconnected client has a long timeout. Use setPingTime to define the time (in ms) without traffic after which a ping aka a chr(0) is sent to the Telnet client to detect a disconnect earlier. Use 0 as parameter to disable pings.
Default: 1500
void setPingTime(uint16_t pngTime)
Change the size of the receive buffer. Set it to 0 to disable buffering in TelnetSpy (there is still a buffer in the underlayed WifiClient component). Returns false if the requested buffer size cannot be set.
- If the receive buffer is used and it is full, additional received data will be lost. But all telnet NVT protocol data and the "filter character" is still handled (see "setFilter" and the NVT callbacks below).
- If no receive buffer is used and the received characters are not retrieved by your app, the handling of the NVT protocol and the "filter character" will not work. If no receive buffer is used, you cannot receive the code 0xff (it will be lost because of a limitation of the WiFiAPI).
Default: 64
bool setRecBufferSize(uint16_t newSize);
This function returns the actual size of the receive buffer.
uint16_t getRecBufferSize()
Set the serial port you want to use with this object (especially for ESP32) or NULL if no serial port should be used (Telnet only).
Default: Serial
void setSerial(HardwareSerial* usedSerial)
This function returns true if a Telnet client is connected.
bool isClientConnected()
This function installs a callback function which will be called on every Telnet connect of this object (except rejected connect tries). Use NULL to remove the callback.
Default: NULL
void setCallbackOnConnect(void (*callback)())
This function installs a callback function which will be called on every Telnet disconnect of this object (except rejected connect tries). Use NULL to remove the callback.
Default: NULL
void setCallbackOnDisconnect(void (*callback)())
This function disconnects an active client connection.
void disconnectClient()
This function clears the transmit buffer of TelnetSpy, so all waiting data to send via a telnet connection will be discard.
void clearBuffer()
20. void setFilter(char ch, const char* msg, void (*callback()) / void setFilter(char ch, const String& msg, void (*callback())
This function allows to filter the character given by "ch" out of the receiving telnet data stream. If this character is detected, the following happens:
- If a "msg" is given (not NULL), this message will be send back via the telnet connection.
- If the "callback" is set (not NULL), the given function is called.
void setFilter(char ch, const char* msg, void (*callback())
void setFilter(char ch, const String& msg, void (*callback())
This function returns the actual filter character (0 => not set).
char getFilter()
This function installs a callback function which will be called whenever the telnet command "BRK" (Break) is received. Use NULL to remove the callback.
Default: NULL
void setCallbackOnNvtBRK(void (*callback)())
This function installs a callback function which will be called whenever the telnet command "IP" (Interrupt Process) is received. Use NULL to remove the callback.
Default: 1 (=> ESP.restart will be called)
void setCallbackOnNvtIP(void (*callback)())
This function installs a callback function which will be called whenever the telnet command "AO" (Abort Output) is received. Use NULL to remove the callback.
Default: 1 (=> disconnectClient of TelnerSpy will be called)
void setCallbackOnNvtAO(void (*callback)())
This function installs a callback function which will be called whenever the telnet command "AYT" (Are you there) is received. Use NULL to remove the callback.
Default: NULL
void setCallbackOnNvtAYT(void (*callback)())
This function installs a callback function which will be called whenever the telnet command "EC" (Erase Character) is received. Use NULL to remove the callback.
Default: NULL
void setCallbackOnNvtEC(void (*callback)())
This function installs a callback function which will be called whenever the telnet command "EL" (Erase Line) is received. Use NULL to remove the callback.
Default: NULL
void setCallbackOnNvtEL(void (*callback)())
This function installs a callback function which will be called whenever the telnet command "GA" (Go Ahead) is received. Use NULL to remove the callback.
Default: NULL
void setCallbackOnNvtGA(void (*callback)())
This function installs a callback function which will be called whenever the telnet commands "WILL", "WON'T", "DO" or "DON'T" are received. Use NULL to remove the callback.
Default: NULL
void setCallbackOnNvtWWDD(void (*callback)())
Add the following lines to your sketch:
TelnetSpy SerialAndTelnet;
#define SERIAL SerialAndTelnet
// #define SERIAL Serial
Replace Serial with SERIAL in your sketch. Now you can switch between serial only and serial with Telnet by only changing the comments of the defines.
- To connect to the Telnet server you have to:
- Establish the WiFi connection.
- Execute
SerialAndTelnet.begin(WhatEverYouWant).
💡 Note: The order is not important.
-
Everything you do with
Serial, you can do withTelnetSpytoo. But remember: Transfering data also via Telnet will need more performance than the serial port only. So time critical things may be influenced. -
It is not possible to establish more than one Telnet connection at the same time. But it's possible to use more than one instance of TelnetSpy.
-
If you have problems with low memory, you may reduce the value of the
define TELNETSPY_BUFFER_LENfor a smaller ring buffer on initialisation. -
Usage of
void setDebugOutput(bool)to enable / disable of capturing of os_print calls when you have more than one TelnetSpy instance: That TelnetSpy object will handle this functionality where you usedsetDebugOutputat last. On default, TelnetSpy has the capturing of OS_print calls enabled. So if you have more instances the last created instance will handle the capturing.
This library is open-source and licensed under the MIT license.
Do whatever you like with it, but contributions are appreciated!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent