display – LCD Output

[中文]

The display module drives the board LCD. Construct one ESP32Display (aliased as display.Display) and push frames to it with ESP32Display.write().

Camera Preview

import sensor, display

sensor.reset()
sensor.set_pixformat(sensor.RGB565)
sensor.set_framesize(sensor.QVGA)

lcd = display.ESP32Display()
while True:
    lcd.write(sensor.snapshot(), fit=True)

With fit=True, the source image is scaled to fit the panel while preserving the display driver’s default placement behavior. Create the display once and reuse it; repeatedly constructing the object reinitializes panel resources.

Position, Scale, and Crop

Use x and y for placement, x_scale and y_scale for explicit scaling, and roi to display only a source region:

img = sensor.snapshot()
lcd.write(
    img,
    x=20,
    y=10,
    x_scale=0.5,
    y_scale=0.5,
    roi=(40, 30, 160, 120),
    fit=False,
)

When fit=False, the explicit position and scale values control the output. The ROI is expressed in source-image coordinates as (x, y, width, height); reducing the ROI also reduces the amount of image data sent to the display pipeline.

Backlight and Cleanup

lcd = display.Display(backlight=80)
print("panel:", lcd.width(), "x", lcd.height())
lcd.backlight(30)
lcd.clear()
lcd.deinit()

Backlight values are percentages from 0 to 100. Call deinit() when an application permanently releases the display; do not write frames after the driver has been deinitialized.

See also

Runnable example: example/06-Peripherals/01-Display/lcd_preview.py.

Classes

class display.ESP32Display(width=..., height=..., refresh=..., *, backlight=...)

ESP32 display object for the board LCD.

Create and initialize the display.

Parameters:

  • width – requested display width; 0 uses board default.

  • height – requested display height; 0 uses board default.

  • refresh – target refresh rate in Hz.

  • backlight – initial backlight percentage, from 0 to 100.

deinit()

Release the display driver resources.

width()

Return the physical display width in pixels.

height()

Return the physical display height in pixels.

clear(display_off=...)

Clear the display.

Parameters:

display_off – True may turn the panel output off when supported by the board.

backlight(value=...)

Get or set backlight brightness.

Parameters:

value – None returns current brightness; otherwise set 0 to 100 percent.

write(image, *, x=..., y=..., x_scale=..., y_scale=..., roi=..., fit=...)

Draw an image on the display. x, y: destination top-left position in display pixels. x_scale, y_scale: optional manual scale factors.

Parameters:

  • image – source image, normally from sensor.snapshot().

  • roi – optional source rectangle (x, y, w, h).

  • fit – True scales the image to fit the display area.