# BIGTREETECH-TouchScreenFirmware
**Repository Path**: bigtreetech/BIGTREETECH-TouchScreenFirmware
## Basic Information
- **Project Name**: BIGTREETECH-TouchScreenFirmware
- **Description**: support TFT35 V1.0/V1.1/V1.2/V2.0/V3.0, TFT28, TFT24 V1.1, TFT43, TFT50, TFT70
- **Primary Language**: C
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2021-11-06
- **Last Updated**: 2025-01-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# BigTreeTech TFT Touchscreen
[](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/graphs/contributors)
[](https://github.com/bigtreetech/bigtreetech-TouchScreenFirmware/actions)
Important information related to BigTreeTech's TFT touchscreen 3D printer controllers
## Table of Contents
- [Supported Screens](#supported-screens)
- [Marlin Dependencies](#marlin-dependencies)
- [Connect the TFT to the Mainboard](#connect-the-tft-to-the-mainboard)
- [Menus and Themes](#menus)
- [Update TFT Firmware](#update-tft-firmware)
- [Calibrate the Screen](#calibrate-the-screen)
- [Using the Configuration file](#using-the-configuration-file)
- [Customisation](#customisation)
- [Bootscreen and Icons](#bootscreen-and-icons)
- [Firmware](#firmware)
- [Troubleshooting](#troubleshooting)
- [Version History](#version-history)
- [Appendix](#appendix)
- [Embedded Gcode Thumbnails](#embedded-gcode-thumbnails)
- [TFT Screen Configuration and support for RRF](#tft-screen-configuration-and-support-for-rrf)
- [Setup of BTT TFT35 E3 V3 with MKS SGEN L Mainboards](#setup-of-btt-tft35-e3-v3-with-mks-sgen-l-mainboards)
- [Show more statistics at the end of the print](#show-more-statistics-at-the-end-of-the-print)
## Supported Screens
Only the TFT's listed below are currently supported. Trying to install the firmware on a TFT which is not supported can harm the hardware.
**BTT TFT**
BTT_TFT24_V1.1
BTT_TFT28_V1.0 and V3.0
BTT_TFT35_V1.0, V1.1, V1.2, V2.0, V3.0, E3_V3.0 and B1_V3.0
BTT_TFT43_V3.0
BTT_TFT50_V3.0
BTT_TFT70_V3.0
**MKS TFT** *Warning: BTT does not officially provide MKS TFT hardware support, MKS TFT is maintained by open source contributors, and BTT does not bear any risk of MKS TFT hardware using this firmware*
MKS_TFT28_V3.0 and V4.0
MKS_TFT32_V1.3 and V1.4
## Marlin Dependencies
Firmware source: https://github.com/MarlinFirmware/Marlin/releases
Minimum Marlin firmware version: 2.0.8.1
Distribution date: 2021-05-15
In order the TFT firmware is able to provide all of its functionalities/features, the following options must be enabled in Marlin firmware.
**General options which MUST be activated:**
`EEPROM_SETTINGS` (in Configuration.h)
`BABYSTEPPING` (in Configuration_adv.h)
`AUTO_REPORT_TEMPERATURES` (in Configuration_adv.h)
`AUTO_REPORT_POSITION` (in Configuration_adv.h)
`M115_GEOMETRY_REPORT` (in Configuration_adv.h)
`M114_DETAIL` (in Configuration_adv.h)
`REPORT_FAN_CHANGE` (in Configuration_adv.h)
**Options to support printing from onboard SD:**
`SDSUPPORT` (in Configuration.h)
`LONG_FILENAME_HOST_SUPPORT` (in Configuration_adv.h)
`AUTO_REPORT_SD_STATUS` (in Configuration_adv.h)
`SDCARD_CONNECTION ONBOARD` (in Configuration_adv.h)
**Options to support dialog with host:**
`EMERGENCY_PARSER` (in Configuration_adv.h)
`SERIAL_FLOAT_PRECISION 4` (in Configuration_adv.h)
`HOST_ACTION_COMMANDS` (in Configuration_adv.h)
`HOST_PROMPT_SUPPORT` (in Configuration_adv.h)
**Options to support M600 with host & (Un)Load menu: (Options to support dialog with host as pre requisite)**
`NOZZLE_PARK_FEATURE` (in Configuration.h)
`ADVANCED_PAUSE_FEATURE` (in Configuration_adv.h)
`PARK_HEAD_ON_PAUSE` (in Configuration_adv.h)
`FILAMENT_LOAD_UNLOAD_GCODES` (in Configuration_adv.h)
**Options to fully support Bed Leveling menu:**
`Z_MIN_PROBE_REPEATABILITY_TEST` (in Configuration.h)
`G26_MESH_VALIDATION (in Configuration.h)` (in Configuration.h)
`Z_STEPPER_AUTO_ALIGN` (in Configuration_adv.h)
## Connect the TFT to the Mainboard
**Do the following, to be able to use the touchmode of your screen.**
1. Connect the 5pin serial cable according to the manual of your mainboard.
2. Define a serial port in Marlin, to activate the port used by the TFT.
3. Make sure the same BAUDRATE is defined in Marlin and the firmware of your TFT (config.ini)
In case one of the three points above is not done right, "No printer attached" will be shown at the top of the screen in touchscreen mode. This is because the TFT can not "see" the mainboard through the serial cable.
**Do the following, to be able to use the Marlin emulation mode of your screen.**
A: In case your TFT does **not** have an EXP connector at all (TFT28 v1 for example), you can not use the Marlin emulator mode.
B: In case your mainboard provides **EXP1 and EXP2**, you have to connect 2 ribbon cables connecting EXP1 and EXP2 of the mainboard to EXP1 and EXP2 of the TFT. In the Marlin firmware of your mainboard, make sure that **ONLY** the "`REPRAP_DISCOUNT_FULL_GRAPHIC_SMART_CONTROLLER`" is activated in Configuration.h and that all other controllers are **De**activated (especially the "`CR10_STOCKDISPLAY`").
C: In case you have an **"E3" mainboard** which provides a **single EXP connector**, you have to connect 1 ribbon cable connecting EXP of the mainboard to **EXP3** of the TFT. In case your TFT does **not** provide an EXP3 connector but only two 10pin connectors (TFT24 v1.1 for example) you will need a "Y-split" cable with one 10pin connector on one side (for the mainboard) and two 10pin connectors on the other side (for the TFT). In the Marlin firmware of your mainboard, make sure that **ONLY** the "`CR10_STOCKDISPLAY`" is activated in Configuration.h and that all other controllers are **De**activated (especially the "`REPRAP_DISCOUNT_FULL_GRAPHIC_SMART_CONTROLLER`").
## Menus
| Status Screen DISABLED | Status Screen ENABLED |
| :----------------------------------------------------------: | :----------------------------------------------------------: |
|  |  |
| In config.ini define: General Settings
Enable Status Screen
# Select the Main Screen flavour
# Options: [Enable: 1, Disable: 0]
**status_screen: 0** | In config.ini define: General Settings
Enable Status Screen
# Select the Main Screen flavour
# Options: [Enable: 1, Disable: 0]
**status_screen: 1** |
## Themes
| Unified Menu Theme | The Round Miracle Theme by **[Acenotass](https://github.com/Acenotass)** |
| :----------------------------------------------------------: | :----------------------------------------------------------: |
|  |  |
| Use firmware, icons, and fonts from the [`Copy to SD Card root directory to update - Unified Menu Material theme`](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/Copy%20to%20SD%20Card%20root%20directory%20to%20update/THEME_Unified%20Menu%20Material%20theme) folder | Use firmware, icons, and fonts from the [`Copy to SD Card root directory to update - The Round Miracle theme`](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/Copy%20to%20SD%20Card%20root%20directory%20to%20update/THEME_The%20Round%20Miracle%20Menu%20Material%20theme) folder |
| Hybrid Red Material Theme by **[AntoszHUN](https://github.com/AntoszHUN)** | Hybrid Mono Material Theme by **[bepstein111](https://github.com/bepstein111)** |
| :----------------------------------------------------------: | :----------------------------------------------------------: |
|  |  |
| Use firmware, icons, and fonts from the [`Copy to SD Card root directory to update - Hybrid Red Menu Material theme`](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/Copy%20to%20SD%20Card%20root%20directory%20to%20update/THEME_Hybrid%20Red%20Menu%20Material%20theme) folder | Use firmware, icons, and fonts from the [`Copy to SD Card root directory to update - Hybrid Mono Menu Material theme`](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/Copy%20to%20SD%20Card%20root%20directory%20to%20update/THEME_Hybrid%20Mono%20Menu%20Material%20theme) folder |
| Rep Rap Firmware Dark Theme by **[xPew](https://github.com/xPew)** | |
| :----------------------------------------------------------: | ------------------------------------------------------------ |
|  |  |
| Use firmware, icons, and fonts from the [`Copy to SD Card root directory to update - Rep Rap Firmware Dark theme`](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/Copy%20to%20SD%20Card%20root%20directory%20to%20update/THEME_Rep%20Rap%20Firmware%20Dark%20theme) folder | |
## Update TFT Firmware
The TFT firmware update includes up to four elements and is done in three steps:
### **ELEMENTS:**
**element 1:** The firmware binary (`BIGTREE_TFT*_V*.*.*.bin`). Example: `BIGTREE_TFT35_V3.0.27.bin`:
- `BIGTREE_TFT_35`: model
- `V3.0`: hardware version
- `27`: software version
Exception: For the MKS TFT28 the binary file name must be `MKSTFT28.bin`.
Attention TFT35 owners. There are currently three different kinds of firmware available: V3.0, E3_V3.0 and B1_V3.0. Please make sure to use the firmware which matches your TFT screen.
**element 2:** Fonts and Icons (in the `TFT*` or `MKS` folder):
For BTT TFTs, the ROOT FOLDER for fonts and icons is TFT*, where * is the size of the TFT (example: TFT24, TFT35, TFT50, etc).
Fonts and icons folder structure:
- `TFT*/font`: includes the fonts in .fon format and a readme.md
- `TFT*/bmp`: includes the icons in .bmp format and a readme.md
For MKS TFTs the ROOT FOLDER for fonts and icons must be renamed to "MKS".
Fonts and icons folder structure:
- `MKS/font`: includes the fonts in .fon format and a readme.md
- `MKS/bmp`: includes the icons in .bmp format and a readme.md
**element 3:** The config.ini or (the renamed) config_rrf.ini file
Attention RepRap Firmware users. You have to make your changes using the config_rrf.ini file and rename it to config.ini before you upload it to the TFT.
**element 4 (optionally):** One or several language file(s)
### **STEPS:**
**step 1:** Copy your self compiled **firmware** or the BIGTREE_TFT*_V*.*.*.bin, plus the **TFT*` folder** of your preferred Material theme as well as the **config.ini** to the root of a blank SD card that is <8GB and formatted as FAT32:
**Optionally**, copy one or several language.ini file(s) from [`Copy to SD Card root directory to update/Language Packs`](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/Copy%20to%20SD%20Card%20root%20directory%20to%20update/Language%20Packs) folder onto the SD card. Doing so will allow you to switch between English and the uploaded language(s), using the corresponding Language function of the TFT. We recommend to upload the minimum amount of languages, to keep the memory usage low. The language.ini file can be edited to change the text shown on the TFT.
**step 2:** Place the SD card with the `BIGTREE_TFT*_V*.*.*.bin`, the`TFT*` folder and the config.ini into the TFT's SD card reader and reset your TFT (or optionally - power cycle your printer) to start the update process.
⚠️ Failing to update your icons & fonts will result in missing icons and/or unreadable text ⚠️
## Update Process shown on TFT Screen
A successful update looks like this on the screen:
... and the name of the elements on the SD card changes to this:
In case one or several parts of the update failed, an error will be shown. Follow the information on the screen to update the missing or outdated elements.
⚠️ Errors during the update can not be ignored and must be solved before using the TFT ⚠️
After the update is done and the files are renamed, it is possible to reuse them again. To do so, change the name of the element(s) to the pre-update name and start the update process again.
**step3:** Remove the SD card from the TFT and restart the printer.
Tip: Format the SD card after the firmware update in case you would like to print from it.
## Calibrate the Screen
Sometimes a calibration will be executed automatically after a firmware update, showing a white screen with a red dot in the upper right corner and the text: Touch Screen Calibration - Please click on the red dot. To calibrate the screen press with your finger or a stylus the red dot in the upper left corner, then the red dot in the upper right corner and then the red dot in the lower right corner. Even the screen asks you to press the red dot, press the black dot in the middle of the screen to finish the calibration. Repeat the process in case the message: "Adjustment failed, please try again" is shown.
## Using the Configuration file
Attention RepRap Firmware users. You have to make your changes using the config_rrf.ini file and rename it to config.ini before you copy it to the TFT.
The Firmware can be modified by changing the **config.ini** (or the renamed config_rrf.ini) file from: [`Copy to SD Card root directory to update`](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/Copy%20to%20SD%20Card%20root%20directory%20to%20update) using a simple text editor (make sure to use UTF encoding).
Once saved, it can be uploaded without the need to upload the firmware or the TFT folder again, as long as the firmware and the config file are from the same version.
### Editing the configuration file
To edit the **config** file follow the instruction here: [Detailed Instructions here](config_instructions.md)
### Updating Firmware Configuration
To update the Firmware configuration:
1. Edit the settings like described above
2. Copy the **config.ini** file to the root of the SD card. (The SD card capacity should be less than or equal to 8GB and formatted as FAT32)
3. Insert the SD card into the TFT's SD card slot and restart the printer or press the reset buttion of the TFT.
4. The TFT will update and store the configuration from the configuration file.
5. Make sure to remove the SD card from the TFT and restart the printer.
6. On the TFT click on Menu - Settings - Feature and navigate to the last page. Click on
"Reset default settings ..."
7. Restart the printer to finish the update
## Customisation
### Bootscreen and Icons
See [Customisation guides](https://github.com/bigtreetech/BIGTREETECH-TouchScreenFirmware/tree/master/readme/) for detailed information.
### Firmware
View full instructions
- Setup Visual Studio Code with PlatformIO instructions
- Click on the PlatformIO icon (①) and then click on Open Project (②):
- Find the BIGTREETECH firmware source directory , then click Open:
- After opening the project, edit
platformio.ini and change the default_envs to one that matches your TFT model and version:
;BIGTREE_TFT35_V1_0
;BIGTREE_TFT35_V1_1
;BIGTREE_TFT35_V1_2
;BIGTREE_TFT35_V2_0
;BIGTREE_TFT35_V3_0
;BIGTREE_TFT35_E3_V3_0
;BIGTREE_TFT28_V1_0
;BIGTREE_TFT28_V3_0
;BIGTREE_TFT24_V1_1
;MKS_TFT32_V1_3
;MKS_TFT32_V1_4
;MKS_TFT32_V1_4_NOBL
;MKS_TFT28_V3_0
;MKS_TFT28_V4_0
;MKS_TFT28_NEW_GENIUS
[platformio]
src_dir = TFT
boards_dir = buildroot/boards
default_envs = BIGTREE_TFT35_V3_0
- Click the check mark (✓) at the bottom of VSCode or press
Ctrl+Alt+B (Windows) / Ctrl+Option+B (macOS) to compile.
- A
BIGTREE_TFT*_V*.*.*.bin file will be generated in the hidden .pio\build\BIGTREE_TFT*_V*_* folder. Follow the update process outlined in the About TFT Firmware section above to update your TFT to the latest version.