Cannot set brightness in framebufferio.FramebufferDisplay

[jmangum]

CircuitPython version and board name

Adafruit CircuitPython 10.0.3 on 2025-10-17; Adafruit-Qualia-S3-RGB666 with ESP32S3

Code/REPL

#
# Qualia ESP32-S3 RGB666 40p TFT Display Backlight Test
# Borrowed one of the learn guide display examples (color bars display)
#
import time
import displayio
import busio
import board
import dotclockframebuffer
from framebufferio import FramebufferDisplay
import random

print("\nQualia Backlight Test\n")

# 4-inch square RGB-666 TFT with capacitive touch settings
displayio.release_displays()
tft_pins = dict(board.TFT_PINS)
tft_timings = {
    "frequency": 16000000,
    "width": 720,
    "height": 720,
    "hsync_pulse_width": 2,
    "hsync_front_porch": 46,
    "hsync_back_porch": 44,
    "vsync_pulse_width": 2,
    "vsync_front_porch": 16,
    "vsync_back_porch": 18,
    "hsync_idle_low": False,
    "vsync_idle_low": False,
    "de_idle_high": False,
    "pclk_active_high": False,
    "pclk_idle_high": False,
}
init_sequence_tl040hds20 = bytes()
board.I2C().deinit()
#i2c = busio.I2C(board.SCL, board.SDA)
i2c = busio.I2C(board.SCL, board.SDA, frequency=100_000)
tft_io_expander = dict(board.TFT_IO_EXPANDER)
#tft_io_expander['i2c_address'] = 0x38 # uncomment for rev B
dotclockframebuffer.ioexpander_send_init_sequence(i2c, init_sequence_tl040hds20, **tft_io_expander)
i2c.deinit()
fb = dotclockframebuffer.DotClockFramebuffer(**tft_pins, **tft_timings)
#display = FramebufferDisplay(fb, auto_refresh=False, brightness=0.5) # If you use this line you get "unexpected keyword argument 'brightness'"
display = FramebufferDisplay(fb, auto_refresh=False)

bitmap = displayio.Bitmap(256, 7*64, 65535)
# Create a TileGrid to hold the bitmap
tile_grid = displayio.TileGrid(bitmap, pixel_shader=displayio.ColorConverter(input_colorspace=displayio.Colorspace.RGB565))

# Create a Group to hold the TileGrid
group = displayio.Group()

group.append(tile_grid)

# Add the Group to the Display
display.root_group = group

display.auto_refresh = True

for i in range(256):
    b = i >> 3
    g = (i >> 2) << 5
    r = b << 11
    for j in range(64):
        bitmap[i, j] = b
        bitmap[i, j+64] = b|g
        bitmap[i, j+128] = g
        bitmap[i, j+192] = g|r
        bitmap[i, j+256] = r
        bitmap[i, j+320] = r|b
        bitmap[i, j+384] = r|g|b

blist = [0.5,0.1,0.0,1.0]
while True:
    display.brightness = random.choice(blist)
    print('display.brightness:',display.brightness)
    time.sleep(1)
    display.auto_refresh = False
    group.x = random.randint(0, 32)
    group.y = random.randint(0, 32)
    display.auto_refresh = True
    pass

Behavior

display.brightness: 1.0
display.brightness: 1.0
display.brightness: 1.0
...

Description

• Display brightness not settable.
• Setting display.brightness to any value always leaves variable set to 1.0.
• Initializing FramebufferDisplay with brightness=0.5 (or any value) results in error unexpected keyword argument 'brightness'

Additional information

Could not find a workaround.

[dhalbert]

On the Qualia board, the display backlight is controlled by a set of jumpers and possible PWM on pin A1, if you solder a jumper closed. See https://learn.adafruit.com/adafruit-qualia-esp32-s3-for-rgb666-displays/pinouts#step-3155525. Also see https://learn.adafruit.com/adafruit-qualia-esp32-s3-for-rgb666-displays/backlight-settings for electrical information.

The actual backlight on/off is controlled in the I/O expander, and supported in the Qualia library. There is a shortage of pins and we had to use an expander for that.

[jmangum]

Thank you @dhalbert. I had not appreciated that one had to solder the PWM jumper to simply set the backlight intensity (not PWM control it).

[dhalbert]

to simply set the backlight intensity (not PWM control it).

You are actually controlling the intensity with PWM. PWM is pulse width modulation. So the narrower the pulses the lower the average voltage. Your eyes average the on/off cycles and perceive it as intensity.

[dhalbert]

I am going to leave this open because maybe we want to raise an error on attempts to set the brightness, or take an optional PWM pin. @tannewt you may have a comment.

[jmangum]

I kind of wondered if the behaviour to my trying to set the brightness using display.brightness was not optimal. The brightness parameter is in the directory, but produces an error when set.

[tannewt]

Looks like DotClockFramebuffer needs to take in PWM pin for the backlight. It implements the brightness functions for the FramebufferDisplay but doesn't do anything meaningful for them. I bet I punted on it when I added it.

circuitpython/shared-bindings/dotclockframebuffer/DotClockFramebuffer.c

Lines 296 to 302 in fa4caf8

	static float dotclockframebuffer_framebuffer_get_brightness_proto(mp_obj_t self_in) {
	return 1.0f;
	}
	static bool dotclockframebuffer_framebuffer_set_brightness_proto(mp_obj_t self_in, mp_float_t value) {
	return false;
	}

[dhalbert]

See also adafruit/Adafruit_CircuitPython_Qualia#12. Not sure how to do the division of labor on this functionality.