Wireless Debug Display

This repository contains an example application designed for either ESP32-WROVER-KIT, ESP32-S3-BOX, ESP32-S3-BOX-3, or LILYGO T-DECK (selectable via menuconfig) which listens on a UDP socket for data. It then parses that data and if it matches a certain format, it will plot the data in a graph, otherwise it will print the data to a text log for display.

debug_display_box_compressed.mp4

Table of Contents

• Wireless Debug Display
  • Description
  • Use
    • Program
    • Configure
  • Sending Data to the Display
    • Commands
    • Plotting
    • Logging
  • Development
    • Environment
    • Build and Flash
  • Output
    • Console Logs:
    • Python script:
    • ESP32-WROVER-KIT
    • LILYGO T-DECK
    • ESP32-S3-BOX
    • ESP32-S3-BOX-3

Description

This code receives string data from a UDP server. It will parse that string data and determine which of the following three types of data it is:

• Commands: contain the prefix (+++) in the string.
• Plot data: contain the delimiter (::) in the string followed by a single value which can be converted successfully to a number. If the conversion fails, the message will be printed as a log.
• Log / text data: all data that is not a command and cannot be plotted.

They are parsed in that priority order.

Some example data (no commands) can be found in test_data.txt.

A couple python scripts are provided for sending data from a computer to your logger to showcase simple UDP socket sending, as well as automatic service discovery using mDNS.

• ./send_to_display.py: Uses simple UDP sockets to send messages or a file to the debug display.
• ./send_to_display_mdns.py: Uses python's zeroconf package to discover the wireless display on the network and then send messages or a file to the debug display. NOTE: zeroconf may not be installed / accessible within the python environment used by ESP-IDF.

Use

You must first program your hardware. Afterwards, you can configure it via a USB connection using its built-in CLI.

Program

Download the release programmer executable from the latest releases page for windows, macos, or linux - depending on which computer you want to use to perform the one-time programming. There are a few programmers pre-built for the ESP-BOX, the LilyGo T-Deck, or the ESP32-Wrover-Kit.

1. Download the programmer
2. Unzip it
3. Double click the exe (if windows), or open a terminal and execute it from the command line ./wireless-debug-display-<hardware>_programmer_v2.0.0_macos.bin, where hardware is one of esp-box or t-deck or wrover-kit.

Configure

To configure it, simply connect it to your computer via USB and open the serial port in a terminal (e.g. screen, PuTTY, etc.) at 115200 baud. Once there, you can use it as you would any other CLI - and the help command will provide info about the commands available.

Any SSID/Password you set will be securely saved in the board's NVS, which is managed by the ESP-IDF WiFi subsystem.

sta> help
Commands available:
 - help
	This help message
 - exit
	Quit the session
 - log <verbosity>
	Set the log verbosity for the wifi sta.
 - connect
	Connect to a WiFi network with the given SSID and password.
 - connect <ssid> <password>
	Connect to a WiFi network with the given SSID and password.
 - disconnect
	Disconnect from the current WiFi network.
 - ssid
	Get the current SSID (Service Set Identifier) of the WiFi connection.
 - rssi
	Get the current RSSI (Received Signal Strength Indicator) of the WiFi connection.
 - ip
	Get the current IP address of the WiFi connection.
 - connected
	Check if the WiFi is connected.
 - mac
	Get the current MAC address of the WiFi connection.
 - bssid
	Get the current BSSID (MAC addressof the access point) of the WiFi connection.
 - channel
	Get the current WiFi channel of the connection.
 - config
	Get the current WiFi configuration.
 - scan <int>
	Scan for available WiFi networks.
 - memory
	Display minimum free memory.
 - switch_tab
	Switch to the next tab in the display.
 - clear_info
	Clear the Info display.
 - clear_plots
	Clear the Plot display.
 - clear_logs
	Clear the Log display.
 - push_data <data>
	Push data to the display.
 - push_info <info>
	Push info to the display.

Sending Data to the Display

This display is designed to receive data from any other device on the network, though it is primarily intended for other embedded wireless devices such as other ESP-based systems. However, I have provided some scripts to help show how data can be sent from computers or other systems if you choose.

Assuming that your computer is also on the network (you'll need to replace the IP address below with the ip address displayed in the info page of the display if you don't use the mDNS version):

# this python script uses mDNS to automatically find the display on the network
python ./send_to_display_mdns.py --file <file>
python ./send_to_display_mdns.py --message "<message 1>" --message "<message 2>" ...
# e.g.
python ./send_to_display_mdns.py --file test_data.txt
python ./send_to_display_mdns.py --message "Hello world" --message "trace1::0" --message "trace1::1" --message "Goodbye World"

# this python script uses raw UDP sockets to send data to the display on the network
python ./send_to_display.py --ip <IP Address> --port <port, default 5555> --file <file>
python ./send_to_display.py --ip <IP Address> --port <port, default 5555> --message "<message 1>" --message "<message 2>" ... 
# e.g.
python ./send_to_display.py --ip 192.168.1.23 --file additional_data.txt
python ./send_to_display.py --ip 192.168.1.23 --message "Hello world" --message "trace1::0" --message "trace1::1" --message "Goodbye World"

Commands

There are a limited set of commands in the system, which are determined by a prefix and the command itself. If the prefix is found ANYWHERE in the string message (where messages are separated by newlines), then the message is determined to be a command.

PREFIX: +++ - three plus characters in a row

• Remove Plot: this command (RP: followed by the string plot name) will remove the named plot from the graph.
• Clear Plots: this command (CP) will remove all plots from the graph.
• Clear Logs: this command (CL) will remove all logs / text.

Plotting

Messages which contain the string :: and which have a value that successfully and completely converts into a number are determined to be a plot. Plots are grouped by their name, which is any string preceding the ::.

Logging

All other text is treated as a log and written out to the log window. Note, we do not wrap lines, so any text that would go off the edge of the screen is simply not rendered.

Development

You'll need to configure the build using idf.py set-target <esp32 or esp32s3> and then idf.py menuconfig to then set the Wireless Debug Display Configuration which allows you to set which hardware you want to run it on, as well as the WiFi Access Point connection information (ssid/password). It also allows customization of the port of the UDP server that the debug display is running.

Environment

This project is an ESP-IDF project, currently ESP-IDF v.5.4.

For information about setting up ESP-IDF v5.4, please see the official ESP-IDF getting started documentation.

Build and Flash

Build the project and flash it to the board, then run monitor tool to view serial output:

idf.py -p PORT flash monitor

(Replace PORT with the name of the serial port to use.)

(To exit the serial monitor, type Ctrl-].)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

Output

Console Logs:

Python script:

ESP32-WROVER-KIT

debug_display_kit_compressed.mp4

LILYGO T-DECK

ESP32-S3-BOX

debug_display_box_compressed.mp4

ESP32-S3-BOX-3