Displayio: PyPortal Titano backlight brightness setter is nonlinear

CircuitPython version

Adafruit CircuitPython 7.2.4 on 2022-03-31; Adafruit PyPortal Titano with samd51j20
Board ID:pyportal_titano

PWM frequency testing with 3.5"TFT FeatherWing:
Adafruit CircuitPython 7.2.0 on 2022-02-24; Adafruit Feather RP2040 with rp2040
Board ID:adafruit_feather_rp2040

Code/REPL

display.brightness = 0.4

Behavior

screen contents not visible

Description

As discovered in a Learning Guide example (https://github.com/adafruit/Adafruit_Learning_System_Guides/pull/2117), display brightness for the Titano only works for an off-to-bright range of 0.48 to 1.0, not the same as the typical range of other TFT displays of 0.05 to 1.0. The problem stems from the PWM frequency that controls the FAN5333 backlight LED current controller chip. The controller data sheet recommends limiting the PWM input frequency to less than 1kHz in order to maintain the full linear range. The displayio.display module (line 119 of https://github.com/adafruit/circuitpython/blob/main/shared-module/displayio/Display.c) appears to set the brightness PWM frequency to 50kHz, well beyond the maximum for the controller chip:

pwmout_result_t result = common_hal_pwmio_pwmout_construct(&self->backlight_pwm, backlight_pin, 0, 50000, false);

Since I don't have the skills to modify the core module and build CircuitPython, I conducted PWM frequency tests on the 3.5" TFT FeatherWing (#3651) (same display and FAN5333 backlight controller as the Titano) driven from pin D4 of an RP2040 Feather. When setting the PWM frequency to 50kHz, the brightness range nonlinearity of the Titano appeared. Reducing the frequency to < 1kHz produced the desired brightness range. A PWM frequency of 500Hz provided the best display brightness linearity response with a slightly visible screen at a brightness value of 0.01. Screen flickering was not seen for any tested PWM frequency. Nearby audio devices were unaffected.

Since displayio.Display.c's backlight PWM frequency setting impacts all boards with built-in TFT displays, further testing will be needed after some preliminary CircuitPython builds are available, particularly regarding screen flicker and on-board audio interference.

No changes to existing PyPortal Titano documentation are anticipated for the fix. However, some minor changes to the learning guides of a few TFT breakout boards using the same backlight controller will be required. Here's a list of known boards and impacts:

PID   Description              Impact
4444  PyPortal Titano          none
3651  3.5" TFT FeatherWing     learning guide
2441  PiTFT 3.5"               learning guide, driver?
2097  PiTFT 3.5".              learning guide, driver?
1932. 40-pin TFT friend        learning guide
1590  RA8875 TFT Driver Board  learning guide

Additional information

No response

adafruit / circuitpython