T-Deck: an ESP32-S3 dev board shaped like a M5Stack

Two boards, one ESP32-S3 and a satellite keyboard

The repository covers the LilyGO T-Deck and the T-Deck-Plus, and the hardware is what shapes every instruction in it. The board is an ESP32-S3 with a display, a trackball and a separate T-Keyboard that is an ESP32-C3, and the Arduino IDE section in the README shows a Tools menu with two board entries, T-Deck(ESP32S3) and T-Keyboard(ESP32C3), which is the first sign that the keyboard is a second board rather than a peripheral of the first. The repository's language is C, and the top level shows the shape of the project: an examples/ directory with the samples, a platformio.ini, a lib/ directory for the libraries that get copied into the Arduino libraries folder, firmware/, boards/, datasheet/, schematic/, data/ and a shell/ directory.

The documentation is bilingual, with an English README and a README_CN.MD, and the homepage for the hardware is lilygo.cc. The repository has no GitHub releases, and the last push was on 2026-09-29, so the artefacts are the example folders rather than tagged versions.

The Grove port on the Plus version is gone to the GPS

The News section carries two items that change what you can do with the hardware, and the first is a hardware limitation rather than a firmware one. T-Deck-Plus has assigned the pins on the Grove interface to the GPS module, so the Grove interface of the T-Deck-Plus cannot be used. That is not a configuration you can work around in software, and it means any plan that involves a Grove peripheral on the Plus version has to be reconsidered before you buy the board rather than after.

The second item is a software one, and it is the kind of detail that costs an afternoon if you hit it cold. T-Deck updated the TFT_eSPI ST7789 initialisation sequence on 20240726, and those changes have not been pushed to the TFT_eSPI upstream branch. The README's advice is to check whether the screen display is incorrect against the initialisation sequence in the warehouse, in other words against what the hardware shipped with.

There is also a pointer for the factory firmware of the newer version, which lives in the separate LilyGoLib repository rather than here.

The example set, and what each one exercises

The examples tree in the README lists what the board can do and, more usefully, which parts of it are fiddly. There is an ESP32C3 keyboard I2C slave example, a second one where the T-Deck reads from the keyboard, a LoRaWAN starter, a microphone example for noise detection, a touchpad example for reading touch coordinates, a GPS shield example, an lvgl example and a factory hardware unit test.

The example directory on disk adds more than the README lists, and the extras are the interesting ones. There is a HelloWorld, an I2SPlay, a SimpleTone, an SD directory, a LvglArduinoVNC_VGA example, and a second lvgl_example alongside the listed one. Two of those are worth pausing on. LvglArduinoVNC_VGA points at rendering the LVGL interface to a desktop display over a network connection rather than to the board's own screen, which is a useful way to develop a UI without reflashing. And the UnitTest example is the one to run first, because it is the factory hardware test, and the pin map is documented in it, in examples/UnitTest/utilities.h, under the Pins section of the README.

The shell/ directory has its own entry, with a screenshot of the T-Deck running it, and it is separate from the examples.

PlatformIO: pick one line in platformio.ini and compile

The PlatformIO path is the more mechanical of the two. Install Visual Studio Code and Python, then search for the PlatformIO plugin in the extension marketplace, install it, and restart Visual Studio Code, because the README says a restart is needed after the installation completes. Then select File, Open Folder and pick the T-Deck directory, open the platformio.ini file, and in the platformio column cancel the sample line for the example you do not want, making sure only one line stays valid. Click the check symbol in the lower left to compile, connect the board to the computer over USB, click the arrow to upload the firmware, and click the plug symbol to monitor serial output.

There is one optional extra step for the speaker demo. You can upload the assets contents using the Upload Filesystem Image entry in the PlatformIO menu, which is the step that puts the audio files onto the board's filesystem so the demo has something to play.

Arduino IDE, and a board package that must stay on 2.0.14

The Arduino IDE path is the one with a hard version constraint in it. The instruction is to install the Arduino IDE, then in Arduino Preferences, on the Settings tab, enter the ESP32 package index URL in the Additional boards manager URLs input box, which is https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json.

The version note is emphatic. The test phase is using 2.0.14, it is not certain that versions above 2.0.14 can run, and when the operation is abnormal you should downgrade to a version below 2.0.14. The README adds that as of 2024/08/02 TFT_eSPI does not work on versions higher than 2.0.14, with a link to the TFT_eSPI issue. So the board package is pinned, not merely recommended, and that is the single most likely thing to waste your time if you follow the steps without reading them.

The libraries then have to be copied by hand, all the folders in the T-Deck/lib directory, into the Arduino libraries folder, and the README is careful that you copy the folders inside lib, not the lib directory itself, and that you create the libraries directory if it does not exist. Then you select the board in Tools, plug in USB, and upload, with the note that if the upload fails you keep pressing the BOOT button, click RST, then click Upload, and press RST again to leave download mode.

Download mode, the trackball and the keyboard's six pin header

The Tips section is the accumulated knowledge of people who struggled, and it is the most useful part of the README. The first tip is a functional trade-off: if a microphone is used, the GPIO0 button cannot be used. The second and fourth are about getting the board into a state where it will accept a sketch. If the sketch cannot be uploaded you press down the middle of the trackball and then insert the USB, which puts the chip into download mode, then click upload. For the T-Deck specifically, the instructions are to connect the USB-C cable, toggle the switch to ON, press and hold the center trackball, press the left reset button, and upload the sketch, with a video link for the procedure and a fallback: if the upload still fails, check whether the resistor in issue 62 exists, remove it and test again.

The T-Keyboard is a separate board with its own programming interface, located at the 6Pin header on the side of the RST button, and the pin order starts from the top of the RST button and is TX, RX, BOOT, RST, GND, VCC, so an external USB to TTL adapter is needed to burn the keyboard firmware. For a TTL adapter without an automatic download circuit, you short the BOOT pin and GND before powering on, which puts the T-Keyboard into download mode, and after the burn you disconnect GND and BOOT before running the program.

There is also a specific compiler error with a specific fix, the fatal error: esp_vad.h: No such file or directory, with a link to the issue thread that discusses it.

Where the T-Deck board is the wrong choice

Two cases point elsewhere. The first is a T-Deck-Plus owner who needs the Grove interface, because those pins belong to the GPS module and the interface simply cannot be used on that version. No firmware change recovers it, and the fix is to choose a different board or a different peripheral.

The second is a developer who wants a finished product rather than a platform. What this repository gives you is a set of samples, a pin map and some hard-won notes about flashing, not a firmware you can put on a device and forget. There is no tagged release, the factory firmware for the newer version lives in a different repository entirely, and the Arduino path depends on a board package version that is known not to work above 2.0.14 for the display. If your goal is a working handheld, the T-Deck is an interesting platform with a real community of people writing these examples, but the friction is in the hardware and the vendor's toolchain, not in the code you would write on top of it.

Editorial conclusion

T-Deck fits a maker who has bought the board and wants working examples for the parts that are awkward to bring up, the TFT_eSPI display init, the trackball, the I2C keyboard and the ESP32-C3 half, and who will follow the version pins the README insists on. It does not fit someone who wants a finished product, since the repository is a set of samples rather than a firmware project, and it does not fit a T-Deck-Plus owner who needs the Grove interface, because those pins are taken by the GPS module. Before you flash anything, read the Arduino IDE step about board package version 2.0.14, because the README says TFT_eSPI does not work on higher versions, and use the LilyGoLib repository for the factory firmware of the newer version rather than expecting it here.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Xinyuan-LilyGO/T-Deck on GitHub