The ili9341 display platform allows you to use ILI9341 (datasheet, Aliexpress) displays with ESPHome. As this is a somewhat higher resolution display and may require pins beyond the typical SPI connections, it is better suited for use with the ESP32.


ILI9341 display

# Example minimal configuration entry
  - platform: ili9341
    model: TFT 2.4
    cs_pin: 14
    dc_pin: 27
    led_pin: 32  ### see note below ###
    reset_pin: 33

    lambda: |-
      it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!");

Configuration variables:

  • model (Required): The model of the display. Options are:

    • M5STACK

    • TFT 2.4

    • TFT 2.4R (ILI9342)

  • cs_pin (Optional, Pin Schema): The CS pin.

  • dc_pin (Required, Pin Schema): The DC pin.

  • reset_pin (Optional, Pin Schema): The RESET pin.

  • led_pin (Optional, Pin Schema): The display’s backlight pin. Note: Connect to a PWM-capable pin to switch/dim the display’s backlight or save a pin by connecting it through a 3.3K resistor to the +3V supply.

  • rotation (Optional): Set the rotation of the display. Everything drawn in the lambda: will be rotated per this option. One of (default), 90°, 180°, or 270°.

  • lambda (Optional, lambda): The lambda to use for rendering the content on the display. See Display Rendering Engine for more information.

  • update_interval (Optional, Time): The interval to re-draw the screen. Defaults to 5s.

  • auto_clear_enabled (Optional, boolean): Whether to automatically clear the display in each loop (‘’true’’, default), or to keep the existing display content (must overwrite explicitly, e.g., only on data change).

  • pages (Optional, list): Show pages instead of a single lambda. See Display Pages.

  • id (Optional, ID): Manually specify the ID used for code generation.

  • color_palette (Optional): The type of color pallet that will be used in the ESP’s internal 8-bits-per-pixel buffer. This can be used to improve color depth quality of the image. For example if you know that the display will only be showing grayscale images, the clarity of the display can be improved by targeting the available colors to monochrome only. Options are:

    • NONE (default)


Configuration examples

To utilize the color capabilities of this display module, you’ll likely want to add a color: section to your YAML configuration; please see color for more detail on this configuration section.

To use colors in your lambda:

  - id: my_red
    red: 100%
    green: 3%
    blue: 5%


    lambda: |-
      it.rectangle(0,  0, it.get_width(), it.get_height(), id(my_red));

To bring in color images:

  - file: "image.jpg"
    id: my_image
    resize: 200x200
    type: RGB24


    lambda: |-
      it.image(0, 0, id(my_image));

To configure a dimmable backlight:

# Define a PWM output on the ESP32
  - platform: ledc
    pin: 32
    id: gpio_32_backlight_pwm

# Define a monochromatic, dimmable light for the backlight
  - platform: monochromatic
    output: gpio_32_backlight_pwm
    name: "ILI9341 Display Backlight"
    id: back_light
    restore_mode: ALWAYS_ON

See Also