examples/common/m5stack-tft/repo/README.md

   1
   2 ### TFT library for ESP32
   3
   4 ---
   5
   6 **This library must be built with the esp-idf release/v4.0 branch.**
   7
   8 ESP-IDF 4.0 is currently in beta and instructions are found [here](
   9 https://docs.espressif.com/projects/esp-idf/en/v4.0-beta1/get-started/index.html)
  10 ---
  11
  12 #### Features
  13
  14 * Full support for **ILI9341**, **ILI9488**, **ST7789V** and **ST7735** based TFT modules in 4-wire SPI mode.
  15 * **18-bit (RGB)** color mode used
  16 * **SPI displays oriented SPI driver library** based on *spi-master* driver
  17 * Combined **DMA SPI** transfer mode and **direct SPI** for maximal speed
  18 * **Grayscale mode** can be selected during runtime which converts all colors to gray scale
  19 * SPI speeds up to **40 MHz** are tested and work without problems
  20 * **Demo application** included which demonstrates most of the library features
  21
  22
  23 * **Graphics drawing functions**:
  24   * **TFT_drawPixel**  Draw pixel at given x,y coordinates
  25   * **TFT_drawLine**  Draw line between two points
  26   * **TFT_drawFastVLine**, **TFT_drawFastHLine**  Draw vertical or horizontal line of given length
  27   * **TFT_drawLineByAngle**  Draw line on screen from (x,y) point at given angle
  28   * **TFT_drawRect**, **TFT_fillRect**  Draw rectangle on screen or fill given rectangular screen region with color
  29   * **TFT_drawRoundRect**, **TFT_fillRoundRect**  Draw rectangle on screen or fill given rectangular screen region with color with rounded corners
  30   * **TFT_drawCircle**, **TFT_fillCircle**  Draw or fill circle on screen
  31   * **TFT_drawEllipse**, **TFT_fillEllipse**  Draw or fill ellipse on screen
  32   * **TFT_drawTriangle**, **TFT_fillTriangle**  Draw or fill triangle on screen
  33   * **TFT_drawArc**  Draw circle arc on screen, from ~ to given angles, with given thickness. Can be outlined with different color
  34   * **TFT_drawPolygon**  Draw polygon on screen with given number of sides (3~60). Can be outlined with different color and rotated by given angle
  35 * **Fonts**:
  36   * **fixed** width and proportional fonts are supported; 8 fonts embedded
  37   * unlimited number of **fonts from file**
  38   * **7-segment vector font** with variable width/height is included (only numbers and few characters)
  39   * Proportional fonts can be used in fixed width mode
  40   * Related functions:
  41     * **TFT_setFont**  Set current font from one of embeded fonts or font file
  42     * **TFT_getfontsize**  Returns current font height & width in pixels
  43     * **TFT_getfontheight**  Returns current font height in pixels
  44     * **set_7seg_font_atrib**  Set attributes for 7 segment vector font
  45     * **getFontCharacters**  Get all font's characters to buffer
  46 * **String write function**:
  47   * **TFT_print**  Write text to display
  48     * Strings can be printed at **any angle**. Rotation of the displayed text depends on *tft_font_rotate* variable (0~360)
  49     * if *font_transparent* variable is set to 1, no background pixels will be printed
  50     * If the text does not fit the screen/window width it will be clipped ( if *text_wrap=0* ), or continued on next line ( if *text_wrap=1* )
  51     * Two special characters are allowed in strings: *\r* CR (0x0D), clears the display to EOL, *\n* LF (ox0A), continues to the new line, x=0
  52     * Special values can be entered for X position:
  53       * *CENTER*  centers the text
  54       * *RIGHT*   right justifies the text horizontaly
  55       * *LASTX*   continues from last X position; offset can be used: *LASTX+n*
  56     * Special values can be entered for Y:
  57       * *CENTER*  centers the text verticaly
  58       * *BOTTOM*  bottom justifies the text
  59       * *LASTY*   continues from last Y position; offset can be used: *LASTY+n*
  60   * **TFT_getStringWidth** Returns the string width in pixels based on current font characteristics. Useful for positioning strings on the screen
  61   * **TFT_clearStringRect** Fills the rectangle occupied by string with current background color
  62 * **Images**:
  63   * **TFT_jpg_image**  Decodes and displays JPEG images
  64     * Limits:
  65       * Baseline only. Progressive and Lossless JPEG format are not supported
  66       * Image size: Up to 65520 x 65520 pixels
  67       * Color space: YCbCr three components only. Gray scale image is not supported
  68       * Sampling factor: 4:4:4, 4:2:2 or 4:2:0
  69     * Can display the image **from file** or **memory buffer**
  70     * Image can be **scaled** by factor 0 ~ 3  (1/1, 1/2, 1/4 or 1/8)
  71     * Image is displayed from X,Y position on screen/window:
  72       * X: image left position; constants CENTER & RIGHT can be used; *negative* value is accepted
  73       * Y: image top position;  constants CENTER & BOTTOM can be used; *negative* value is accepted
  74   * **TFT_bmp_image**  Decodes and displays BMP images
  75     * Only uncompressed RGB 24-bit with no color space information BMP images can be displayed
  76     * Can display the image **from file** or **memory buffer**
  77     * Image can be **scaled** by factor 0 ~ 7; if scale>0, image is scaled by factor 1/(scale+1)
  78     * Image is displayed from X,Y position on screen/window:
  79       * X: image left position; constants CENTER & RIGHT can be used; *negative* value is accepted
  80       * Y: image top position;  constants CENTER & BOTTOM can be used; *negative* value is accepted
  81 * **Window functions**:
  82   * Drawing on screen can be limited to rectangular *window*, smaller than the full display dimensions
  83   * When defined, all graphics, text and image coordinates are translated to *window* coordinates
  84   * Related functions
  85     * **TFT_setclipwin**  Sets the *window* area coordinates
  86     * **TFT_resetclipwin**  Reset the *window* to full screen dimensions
  87     * **TFT_saveClipWin**  Save current *window* to temporary variable
  88     * **TFT_restoreClipWin**  Restore current *window* from temporary variable
  89     * **TFT_fillWindow**  Fill *window* area with color
  90 * **Touch screen** supported (for now only **XPT2046** controllers)
  91   * **TFT_read_touch**  Detect if touched and return X,Y coordinates. **Raw** touch screen or **calibrated** values can be returned.
  92     * calibrated coordinates are adjusted for screen orientation
  93 * **Read from display memory** supported
  94   * **TFT_readPixel**  Read pixel color value from display GRAM at given x,y coordinates
  95   * **TFT_readData**  Read color data from rectangular screen area
  96 * **Other display functions**:
  97   * **TFT_fillScreen**  Fill the whole screen with color
  98   * **TFT_setRotation**  Set screen rotation; PORTRAIT, PORTRAIT_FLIP, LANDSCAPE and LANDSCAPE_FLIP are supported
  99   * **TFT_invertDisplay**  Set inverted/normal colors
 100   * **TFT_compare_colors**  Compare two color structures
 101   * **disp_select()**  Activate display's CS line
 102   * **disp_deselect()**  Deactivate display's CS line
 103   * **find_rd_speed()**  Find maximum spi clock for successful read from display RAM
 104   * **TFT_display_init()**  Perform display initialization sequence. Sets orientation to landscape; clears the screen. SPI interface must already be set up, *tft_disp_type*, *tft_width*, *tft_height* variables must be set.
 105   * **HSBtoRGB**  Converts the components of a color, as specified by the HSB model to an equivalent set of values for the default RGB model
 106   * **TFT_setGammaCurve()** Select one of 4 Gamma curves
 107 * **compile_font_file**  Function which compiles font c source file to font file which can be used in *TFT_setFont()* function to select external font. Created file have the same name as source file and extension *.fnt*
 108
 109
 110 * **Global variables**
 111   * **tft_orientation**  current screen orientation
 112   * **tft_font_rotate**  current font rotate angle (0~395)
 113   * **tft_font_transparent**  if not 0 draw fonts transparent
 114   * **tft_font_forceFixed**  if not zero force drawing proportional fonts with fixed width
 115   * **tft_text_wrap**  if not 0 wrap long text to the new line, else clip
 116   * **tft_fg**  current foreground color for fonts
 117   * **tft_bg**  current background for non transparent fonts
 118   * **tft_dispWin** current display clip window
 119   * **tft_angleOffset**  angle offset for arc, polygon and line by angle functions
 120   * **tft_image_debug**  print debug messages during image decode if set to 1
 121   * **tft_cfont**  Currently used font structure
 122   * **tft_x**  X position of the next character after TFT_print() function
 123   * **tft_y**  Y position of the next character after TFT_print() function
 124   * **tft_tp_calx**  touch screen X calibration constant
 125   * **tft_tp_caly**  touch screen Y calibration constant
 126   * **tft_gray_scale**  convert all colors to gray scale if set to 1
 127   * **tft_max_rdclock**  current spi clock for reading from display RAM
 128   * **tft_width** screen width (smaller dimension) in pixels
 129   * **tft_height** screen height (larger dimension) in pixels
 130   * **tft_disp_type**  current display type (DISP_TYPE_ILI9488 or DISP_TYPE_ILI9341)
 131
 132 ---
 133
 134 Full functions **syntax and descriptions** can be found in *tft.h* and *tftspi.h* files.
 135
 136 Full **demo application**, well documented, is included, please **analyze it** to learn how to use the library functions.
 137
 138 ---
 139
 140 #### Connecting the display
 141
 142 | ESP32 pin | Display module | Notes |
 143 | - | - | - |
 144 | Any output pin | MOSI | SPI input on Display module |
 145 | Any pin | MISO | SPI output from Display module, optional |
 146 | Any output pin | SCK | SPI clock input on Display module |
 147 | Any output pin | CS  | SPI CS input on Display module |
 148 | Any output pin | DC  | DC (data/command) input on Display module |
 149 | Any output pin | TCS  | Touch pannel CS input (if touch panel is used) |
 150 | Any output pin | RST  | **optional**, reset input of the display module, if not used **pullup the reset input** to Vcc |
 151 | Any output pin | BL  | **optional**, backlight input of the display module, if not used connect to +3.3V (or +5V) |
 152 | GND | GND  | Power supply ground |
 153 | 3.3V or +5V | Vcc  | Power supply positive |
 154
 155 **Make sure the display module has 3.3V compatible interface, if not you must use level shifter!**
 156
 157 ---
 158
 159 To run the demo, attach ILI9341, ILI9488 or ST7735 based display module to ESP32. Default pins used are:
 160 * mosi: 23
 161 * miso: 19
 162 *  sck: 18
 163 *   CS:  5 (display CS)
 164 *   DC: 26 (display DC)
 165 *  TCS: 25 (touch screen CS)
 166
 167 **Custom PINS can be defined in `idf.py menuconfig` in Components -> TFT Display menu**
 168 ---
 169
 170 #### Display Kits
 171
 172 Predefined display configurations are available that will set pins, display size, and inversion properly for the specified kit.
 173
 174 Access these through the `idf.py menuconfig` in Components->TFT Display
 175
 176 Configurations are available for:
 177
 178     "ESP-WROVER-KIT v3 Display (ST7789V)"
 179     "ESP-WROVER-KIT v4.1 Display (ILI9341)"
 180     "Adafruit TFT Feather Display"
 181     "M5Stack TFT Display"
 182
 183 ---
 184
 185 #### Other config notes
 186
 187 Touch screen can be enabled in Components -> TFT Display as well.
 188
 189 Using *idf.py menuconfig* **select tick rate 1000** ( → Component config → FreeRTOS → Tick rate (Hz) ) to get more accurate timings
 190
 191 ---
 192
 193 #### Installing as Library
 194 This repository is intended to be installable as a component library using the ESP-IDF 4.0 build system.
 195
 196 It is recommended though that you first follow the [demo instructions](#building-the-demo) below to build this repository as a standalone example to validate your hardware and have a basis to learn the library features.
 197
 198 When you are ready to incorporate it into your existing project, it is recommended to:
 199
 200 ```shell
 201 mkdir -p externals
 202 git submodule add https://github.com/jeremyjh/ESP32_TFT_library.git externals/ESP32_TFT_library
 203 ```
 204
 205 In your project's root CMakeLists.txt add the components folder to `EXTRA_COMPONENT_DIRS` - make sure this is before the project() config e.g.
 206
 207 ```cmake
 208 cmake_minimum_required(VERSION 3.5)
 209
 210 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 211     set(EXTRA_COMPONENT_DIRS
 212             externals/ESP32_TFT_library/components)
 213
 214 project(hello-world)
 215 ```
 216
 217 In your own components/<my-component>/CMakeLists.txt or main/CMakeLists.txt add `tft` and `spiffs` (if you are using spiffs) as `REQUIRES` e.g.
 218
 219 ```cmake
 220 set(SOURCES tft_demo.c)
 221 idf_component_register(
 222         SRCS ${SOURCES}
 223         INCLUDE_DIRS
 224           ${CMAKE_CURRENT_LIST_DIR}
 225           $ENV{IDF_PATH}/components
 226         REQUIRES
 227             tft
 228             spiffs
 229 )
 230 ```
 231
 232 ---
 233
 234 #### Building the Demo
 235
 236 Clone the repository to your esp folder (same level as esp-idf, as explained [in instructions](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html)).
 237
 238 `git clone https://github.com/jeremyjh/ESP32_TFT_library.git`
 239
 240 Execute `idf.py menuconfig` and configure your Serial flash config and other settings. Included *sdkconfig.defaults* sets some defaults to be used.
 241
 242 Navigate to **Components -> TFT Display** and set **display and pin** options or select a pre-defined display configuration for a kit.
 243
 244 To enable **Wifi** in the demo (recommended - gets time from NTP), select **TFT Display DEMO Configuration** from the top-level menu and select those options.
 245
 246 Make and flash the example.
 247
 248 `idf.py build && idf.py -p <PORT> flash monitor`
 249
 250 Deploy the SPIFFS image as below to make the image and font examples work.
 251
 252 ---
 253
 254 #### Prepare **SPIFFS** image
 255
 256 *The demo uses some image and font files and it is necessary to flash the spiffs image.*
 257
 258 **To flash already prepared image to flash** execute:
 259
 260 `ESPPORT=<PORT> make copyfs`
 261
 262 ---
 263
 264 You can also prepare different SFPIFFS **image** and flash it to ESP32.
 265
 266 The example partition file reserves 1MB for SPIFFS.
 267 If you change the spiffs partition size, update the SPIFFS configuration as well.
 268
 269 `idf.py menuconfig`
 270 Navigate to **Components -> TFT SPIFFS** and set **SPIFFS** options.
 271
 272 Files to be included on spiffs are already in **components/spiffs_image/image/** directory. You can add or remove the files you want to include.
 273
 274 Then execute:
 275
 276 `make makefs`
 277
 278 to create **spiffs image** in *build* directory **without flashing** to ESP32
 279
 280 Or execute:
 281
 282 `ESPPORT=<PORT> make flashfs`
 283
 284 to create **spiffs image** in *build* directory and **flash** it to ESP32
 285
 286 ---
 287
 288
 289 ---
 290
 291 **Example output:**
 292
 293 ```
 294
 295 I (0) cpu_start: App cpu up.
 296 I (312) heap_init: Initializing. RAM available for dynamic allocation:
 297 I (319) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
 298 I (325) heap_init: At 3FFBB0B8 len 00024F48 (147 KiB): DRAM
 299 I (331) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
 300 I (338) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
 301 I (344) heap_init: At 40091F94 len 0000E06C (56 KiB): IRAM
 302 I (350) cpu_start: Pro cpu start user code
 303 I (144) cpu_start: Starting scheduler on PRO CPU.
 304 I (0) cpu_start: Starting scheduler on APP CPU.
 305
 306 ==============================
 307 TFT display DEMO, LoBo 09/2017
 308 ==============================
 309
 310 SPI: display device added to spi bus (2)
 311 SPI: attached display device, speed=8000000
 312 SPI: bus uses native pins: false
 313 SPI: display init...
 314 OK
 315 SPI: Changed speed to 26666666
 316
 317 ---------------------
 318 Graphics demo started
 319 ---------------------
 320 I (2815) [TFT Demo]: Time is not set yet. Connecting to WiFi and getting time over NTP.
 321 I (2845) wifi: wifi firmware version: ee52423
 322 I (2846) wifi: config NVS flash: enabled
 323 I (2846) wifi: config nano formating: disabled
 324 I (2846) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
 325 I (2856) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
 326 I (2890) wifi: Init dynamic tx buffer num: 32
 327 I (2890) wifi: Init data frame dynamic rx buffer num: 32
 328 I (2890) wifi: Init management frame dynamic rx buffer num: 32
 329 I (2894) wifi: wifi driver task: 3ffc83d8, prio:23, stack:4096
 330 I (2899) wifi: Init static rx buffer num: 10
 331 I (2903) wifi: Init dynamic rx buffer num: 32
 332 I (2907) wifi: Init rx ampdu len mblock:7
 333 I (2911) wifi: Init lldesc rx ampdu entry mblock:4
 334 I (2916) wifi: wifi power manager task: 0x3ffcd844 prio: 21 stack: 2560
 335 I (2922) [TFT Demo]: Setting WiFi configuration SSID LoBoInternet...
 336 I (2951) phy: phy_version: 359.0, e79c19d, Aug 31 2017, 17:06:07, 0, 0
 337 I (2951) wifi: mode : sta (24:0a:c4:11:a4:0c)
 338 I (3073) wifi: n:11 0, o:1 0, ap:255 255, sta:11 0, prof:1
 339 I (3731) wifi: state: init -> auth (b0)
 340 I (3734) wifi: state: auth -> assoc (0)
 341 I (3738) wifi: state: assoc -> run (10)
 342 I (3776) wifi: connected with LoBoInternet, channel 11
 343 I (5827) event: ip: 192.168.0.21, mask: 255.255.255.0, gw: 192.168.0.1
 344 I (5828) [TFT Demo]: Initializing SNTP
 345 I (6331) [TFT Demo]: System time is set.
 346 I (6331) wifi: state: run -> init (0)
 347 I (6332) wifi: n:11 0, o:11 0, ap:255 255, sta:11 0, prof:1
 348 I (6344) wifi: flush txq
 349 I (6344) wifi: stop sw txq
 350 I (6344) wifi: lmac stop hw txq
 351 E (6344) wifi: esp_wifi_connect 836 wifi not start
 352
 353
 354 I (8441) [SPIFFS]: Registering SPIFFS file system
 355 I (8441) [SPIFFS]: Mounting SPIFFS files system
 356 I (8441) [SPIFFS]: Start address: 0x280000; Size 1024 KB
 357 I (8447) [SPIFFS]:   Work buffer: 2048 B
 358 I (8451) [SPIFFS]:    FDS buffer: 384 B
 359 I (8456) [SPIFFS]:    Cache size: 2048 B
 360 I (8500) [SPIFFS]: Mounted
 361
 362 ==========================================
 363 Display: ILI9488: PORTRAIT 240,320 Color
 364
 365      Clear screen time: 60 ms
 366 Send color buffer time: 228 us (240 pixels)
 367        JPG Decode time: 287 ms
 368     BMP time, scale: 5: 422 ms
 369     BMP time, scale: 4: 431 ms
 370     BMP time, scale: 3: 430 ms
 371     BMP time, scale: 2: 434 ms
 372     BMP time, scale: 1: 442 ms
 373     BMP time, scale: 0: 335 ms
 374
 375 ==========================================
 376 Display: ILI9488: LANDSCAPE 320,240 Color
 377
 378      Clear screen time: 57 ms
 379 Send color buffer time: 301 us (320 pixels)
 380 I (126333) event: station ip lost
 381        JPG Decode time: 286 ms
 382     BMP time, scale: 5: 422 ms
 383     BMP time, scale: 4: 431 ms
 384     BMP time, scale: 3: 433 ms
 385     BMP time, scale: 2: 435 ms
 386     BMP time, scale: 1: 444 ms
 387     BMP time, scale: 0: 260 ms
 388
 389 ==========================================
 390 Display: ILI9488: PORTRAIT FLIP 240,320 Color
 391
 392      Clear screen time: 60 ms
 393 Send color buffer time: 228 us (240 pixels)
 394        JPG Decode time: 287 ms
 395     BMP time, scale: 5: 420 ms
 396     BMP time, scale: 4: 430 ms
 397     BMP time, scale: 3: 429 ms
 398     BMP time, scale: 2: 436 ms
 399     BMP time, scale: 1: 446 ms
 400     BMP time, scale: 0: 338 ms
 401
 402 ==========================================
 403 Display: ILI9488: PORTRAIT FLIP 240,320 Color
 404
 405      Clear screen time: 60 ms
 406 Send color buffer time: 228 us (240 pixels)
 407        JPG Decode time: 287 ms
 408     BMP time, scale: 5: 420 ms
 409     BMP time, scale: 4: 430 ms
 410     BMP time, scale: 3: 429 ms
 411     BMP time, scale: 2: 436 ms
 412     BMP time, scale: 1: 446 ms
 413     BMP time, scale: 0: 338 ms
 414
 415
 416 ```
 417
 418 ---
 419
 420 ### Tested on
 421
 422 ESP32-WROVER-KIT v3, ST7789V controller, 240x320
 423 ![Tested on](https://raw.githubusercontent.com/loboris/MicroPython_ESP32_psRAM_LoBo/master/Documents/disp_wrower-kit.jpg)
 424
 425 2.4" 240x320 ILI9341 conroller with Touch panel from eBay
 426 ![Tested on](https://raw.githubusercontent.com/loboris/MicroPython_ESP32_psRAM_LoBo/master/Documents/disp_ili9341.jpg)
 427
 428 3.5" 320x480 ILI9844 controller with Touch panel from BuyDisplay
 429 ![Tested on](https://raw.githubusercontent.com/loboris/MicroPython_ESP32_psRAM_LoBo/master/Documents/disp_9488.jpg)
 430
 431 1.8" 128x160 ST7735 conroller from eBay
 432 ![Tested on](https://raw.githubusercontent.com/loboris/MicroPython_ESP32_psRAM_LoBo/master/Documents/disp_7735.jpg)
 433