1. Introduction
This document serves as a comprehensive guide to help users set up the basic software development environment for applications utilizing the LILYGO T-Dongle-S3 hardware. It illustrates how to use Arduino, including the menu-based configuration wizard, compiling, and firmware download to the ESP32-S3 module.
The T-Dongle-S3 is a versatile development board designed for independent operation. It integrates an ESP32-S3 MCU, supporting both Wi-Fi and BLE communication protocols, and features a 0.96-inch IPS LCD ST7735 display.
At its core, the module utilizes the ESP32S3R8 chip, which combines Wi-Fi (2.4 GHz band) and Bluetooth 5.0 solutions on a single chip. It boasts dual high-performance cores and a variety of versatile peripherals. Built with 40 nm technology, the ESP32-S3 provides a robust, highly integrated platform, meeting demands for efficient power usage, compact design, security, high performance, and reliability.
LILYGO (Shenzhen Xin Yuan Electronic Technology Co., Ltd.) provides the essential hardware and software resources, empowering application developers to innovate with the ESP32-S3 series. The software development framework supports rapid development of Internet-of-Things (IoT) applications, offering Wi-Fi, Bluetooth, flexible power management, and other advanced system features.


2. Specifications
The LILYGO T-Dongle-S3 offers robust features for various development projects.

| Feature | Description |
|---|---|
| MCU | ESP32-S3 Xtensa LX7 microprocessor |
| Wireless Connectivity | Wi-Fi 802.11 b/g/n, Bluetooth 5.0 (RF frequency: BLE 2402-2480MHz, 2.4G Wi-Fi 2412-2462MHz) |
| Platform Support | Arduino-ide, PlatformIO-ide, Micropython |
| Onboard Functions | 16MB Flash, Boot button, TF card slot, Built-in Wi-Fi/Bluetooth highly sensitive ceramic antenna |
| Display | 0.96 inch ST7735 IPS LCD (Resolution: 80 x 160, 0.96 diagonal, Full color (65k), 4-Wire SPI interface, Working Power Supply: 3.3V) |
| Shell | Transparent |
| Interface | USB Type-A |
| Dimensions (L x W x H) | 58.6mm x 17.9mm x 8.7mm |
| USB Supply | 5V 500mA |


3. Getting Started & Setup
3.1. Preparation
Before you begin developing applications for the ESP32-S3, ensure you have the following:
- A personal computer (PC) running Windows, Linux, or macOS.
- A toolchain capable of building applications for the ESP32-S3.
- Arduino IDE, which includes the necessary API for ESP32-S3 and scripts to operate the toolchain.
- The LILYGO T-Dongle-S3 board itself and a compatible USB cable to connect it to your PC.
3.2. Software Installation
The quickest way to get started is by installing the Arduino Software (IDE).
3.2.1. Download Arduino Software
Download the Arduino IDE from the official website. Quick start guides are available for different operating systems:
- Windows: https://www.arduino.cc/en/Guide/Windows
- Linux: https://www.arduino.cc/en/Guide/Linux
- macOS: https://www.arduino.cc/en/Guide/MacOSX
For Windows, select the installer option for direct installation.
3.2.2. Install Arduino Software
Follow the on-screen prompts during installation. Ensure the following components are selected:
- Arduino software
- USB driver
- Create Start Menu shortcut
- Create Desktop shortcut
- Associate .ino files
Allow the installation to complete.
3.2.3. Download Git
Download and install Git, which is required for cloning the ESP32 Arduino core repository.
3.2.4. Pre-build Configuration & Cloning Repository
To set up the ESP32 core for Arduino:
- Right-click the Arduino IDE icon and select "Open file location" (or similar, to find the installation directory).
- Navigate to the `hardware` folder within the Arduino installation directory.
- Right-click in an empty space within the `hardware` folder and select "Git Bash Here" (if Git Bash is installed).
- In the Git Bash terminal, execute the following commands:
mkdir espressif
cd espressif
git clone --recursive https://github.com/espressif/arduino-esp32.git esp323.3. Connecting the Device
Once the software environment is set up, connect your T-Dongle-S3 board to your PC using a USB cable.

Verify that the board is visible under your PC's serial ports and that serial communication is functioning correctly. Upon connecting to power, the device's screen will briefly display an electronic label for approximately two seconds.
4. Operating Instructions
4.1. Uploading a Sketch (Test Demo)
To test your T-Dongle-S3, you can upload an example sketch from the Arduino IDE.
- Open the Arduino IDE.
- Navigate to File > Examples > WiFi > WiFiScan to open the WiFiScan example sketch.
- Before uploading, configure the board settings:
- Go to Tools > Board > ESP32 Arduino > ESP32S3 Dev Module.
- Set Upload Speed to
921600. - Set USB Mode to
Hardware CDC and JTAG. - Set USB CDC On Boot to
Disabled. - Set USB Firmware MSC On Boot to
Disabled. - Set USB DFU On Boot to
Disabled. - Set Upload Mode to
UARTO. - Set CPU Frequency to
240MHz (WiFi). - Set Flash Mode to
QIO 80MHz. - Set Flash Size to
4MB (32Mb). - Set Partition Scheme to
Default 4MB with spiffs (1.2MB APP/1.5MB SPIFFS). - Click the Upload button (right arrow icon) in the Arduino IDE to compile and upload the sketch to your T-Dongle-S3.
4.2. Serial Monitor
After uploading the sketch, you can monitor its output using the Serial Monitor:
- Go to Tools > Serial Monitor.
- Ensure the baud rate is set to
115200 baud. - You should see output similar to a WiFi scan, listing available networks.
4.3. SSC Command Reference
The T-Dongle-S3 supports various SSC (Serial Command) commands for testing and configuration. These commands are typically sent via the Serial Monitor or a terminal program.
| Command | Description | Example |
|---|---|---|
op | Set and query the Wi-Fi mode (STA, AP, STA+AP). Parameters: -Q (query mode), -S -o wmode (set mode, wmode=1 for STA, 2 for AP, 3 for STA+AP) | op -Qop -S -o 1 |
sta | Scan STA network interface, connect/disconnect AP, query status. Parameters: -S scan (scan APs), -Q (show status), -C [-s ssid] [-p password] (connect to AP), -D (disconnect) | sta -S scansta -C -s MyWiFi -p MyPassword |
ap | Set parameters for the AP network interface. Parameters: -S (set AP mode), -s ssid (set AP SSID), -p password (set AP password), -Q (show AP parameters) | ap -S -s MyAP -p APPasswordap -Q |
mac | Query the MAC address of the network interface. Parameters: -Q [-o mode] (mode=1 for STA, 2 for AP) | mac -Q -o 1 |
dhcp | Enable or disable the DHCP server/client. Parameters: -S [-o mode] (start DHCP), -E [-o mode] (end DHCP), -Q [-o mode] (show status) | dhcp -S -o 1dhcp -Q |
ip | Set and query the IP address of the network interface. Parameters: -Q [-o mode] (query IP), -S [-i ip] [-m mask] [-g gateway] [-o mode] (set IP) | ip -Q -o 1ip -S -i 192.168.1.100 -m 255.255.255.0 -g 192.168.1.1 |
reboot | Reboot the board. | reboot |
ram | Query the size of the remaining heap in the system. | ram |
5. Maintenance
To ensure the longevity and proper functioning of your T-Dongle-S3, consider the following maintenance tips:
- TF Card Slot: The device comes with a 'Virtual TF card' placeholder which has no memory. If you need to remove this placeholder, it is recommended to insert a common TF card to protect the USB-A interface from dust or damage. An ordinary TF card can be used normally with the TF card function.
- Cleaning: Keep the device clean and free from dust. Use a soft, dry cloth for cleaning. Avoid using liquids or abrasive cleaners.
- Storage: Store the T-Dongle-S3 in a cool, dry place away from direct sunlight, extreme temperatures, and humidity.
- Handling: The transparent plastic housing is quite soft and can scratch easily. Handle the device with care to maintain its aesthetic condition.

6. Troubleshooting
If you encounter issues with your LILYGO T-Dongle-S3, refer to the following common problems and solutions:
- Device Not Recognized by PC:
- Ensure the USB cable is securely connected to both the T-Dongle-S3 and your PC.
- Verify that the USB drivers for the ESP32-S3 are correctly installed (this is part of the Arduino IDE installation).
- Try a different USB port or cable.
- Firmware Upload Fails:
- Check that the correct board (ESP32S3 Dev Module) is selected in the Arduino IDE (Tools > Board).
- Confirm that the correct serial port is selected (Tools > Port).
- Ensure all board settings (Upload Speed, CPU Frequency, Flash Mode, etc.) match the recommended specifications in Section 4.1.
- If using Git, ensure the ESP32 Arduino core was cloned successfully and recursively.
- No Display Output / Incorrect Display:
- Verify that you have the T-Dongle-S3 model with an LCD if you expect a display.
- Ensure your code initializes the ST7735 LCD correctly.
- The screen briefly displays an electronic label on power-on; if this doesn't happen, check power supply and connection.
- Wi-Fi/Bluetooth Connectivity Issues:
- Check your code for correct Wi-Fi/Bluetooth initialization and credentials.
- Use the
op,sta, andapSSC commands (Section 4.3) to diagnose network settings and status. - Ensure the RF frequency range (BLE 2402-2480MHz, 2.4G Wi-Fi 2412-2462MHz) is compatible with your network environment.
- Meshtastic Compatibility:
- Note that this device does not include LoRa, which is typically required for Meshtastic. Therefore, it is generally not suitable for Meshtastic firmware.
- TF Card Not Functioning:
- Ensure you have replaced the 'Virtual TF card' placeholder with a standard memory TF card.
- Check that your code correctly initializes and accesses the TF card.
7. User Tips
Here are some practical tips and insights from other users to enhance your experience with the LILYGO T-Dongle-S3:
- Versatile Firmware Options: The T-Dongle-S3 is highly versatile. Users have successfully employed it with various firmwares such as USB Army Knife, Nerdminer, and Zerotrace for different projects. It's an excellent platform for open-source development.
- Expandability: The inclusion of a 4-pin Grove connector is a significant advantage, allowing for quick and easy expansion with various sensors and modules.
- Compact and Portable: Its small form factor makes it ideal for projects requiring portability or integration into tight spaces.
- Arduino Compatibility: The board works perfectly with the Arduino IDE, making it accessible for developers familiar with the Arduino ecosystem.
- Display Clarity: The 0.96-inch LCD screen is noted for its clarity and brightness, providing good visual feedback for projects.
- TF Card Slot: Remember to replace the 'fake' SD card placeholder with a regular memory card if you intend to use the TF card functionality. This also helps protect the USB-A interface.
- Handling: Be mindful that the transparent plastic casing can scratch easily. Handle the device with care if aesthetics are important to your application.
8. Warranty and Support
For specific warranty information, please refer to the purchase documentation or contact your retailer. LILYGO provides support and resources for their products to assist developers.
8.1. Additional Resources
- Official User Manual (PDF): A detailed user manual in PDF format is available for download. You can access it via this link: LILYGO T-Dongle-S3 User Manual (PDF).
- GitHub Repository: For more technical details, code examples, and community support, visit the official LILYGO T-Dongle-S3 GitHub repository: https://github.com/Xinyuan-LilyGO/T-Dongle-S3.

9. FCC Compliance Statement
FCC Caution:
Any changes or modifications not expressly approved by the party responsible for compliance could void the user's authority to operate the equipment.
This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation.
This transmitter must not be co-located or operating in conjunction with any other antenna or transmitter.
IMPORTANT NOTE:
This equipment has been tested and found to comply with the limits for a Class B digital device, pursuant to part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment generates, uses, and can radiate radio frequency energy and, if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the following measures:
- Reorient or relocate the receiving antenna.
- Increase the separation between the equipment and receiver.
- Connect the equipment into an outlet on a circuit different from that to which the receiver is connected.
- Consult the dealer or an experienced radio/TV technician for help.
FCC Radiation Exposure Statement:
This equipment complies with FCC radiation exposure limits set forth for an uncontrolled environment. This equipment should be installed and operated with a minimum distance of 20cm between the radiator and your body.