GX040HD-30MB-A1 LCD Panel

This repository provides a Linux kernel module and device tree overlays for integrating the GX040HD-30MB-A1 (or similar TL040HDS21CT2-B1503A) 4.0" 720x720 IPS LCD panel with the Raspberry Pi Compute Module 4 (CM4). The GX040HD-30MB-A1 IPS LCD panel features the Sitronix ST7703 LCD controller and the FocalTech FT6336U touch controller. It enables direct connection of the panel to the Pi’s MIPI DSI interface, supporting 4-lane operation and full RGB888 color. The LCD panel driver is based on the upstream Linux kernel module ST7703.

A few sources where the LCD panel can be purchased:

• https://www.alibaba.com/product-detail/Square-4-Inch-IPS-LCD-Screen_1601124668163.html
• https://chance-display.com/product/4-inch-720720-mipi-interface-touch-screen-square-ips-tft-lcd-module
• https://www.panelook.com/GX040HD-30MRB-A1HDMI-board-4-inch-Square-display-screen-30PINS-MIPI-720-720-IPS-HDMI-board-with-detail_181668.html

The repository includes build and installation instructions, and troubleshooting guidance for seamless deployment on Raspberry Pi OS with kernel version 6.12.25+rpt-rpi-v8 or compatible. This project is intended for developers, integrators, and hardware enthusiasts seeking to add high-resolution square LCD support to custom Raspberry Pi-based systems.

References:

• GX040HD Panel Specification
• ST7703 Datasheet
• Initialization Sequence
• FT6336U Datasheet
• Raspberry Pi Linux ST7703 Driver
• Raspberry Pi Linux edt-ft5x06 Driver
• Raspberry Pi Device Tree Documentation
• Linux DRM Panel Documentation

Hardware Specifications and Setup

• Model: GX040HD-30MB-A1
• Display Controller: Sitronix ST7703
• Size: 4.0 inch diagonal
• Resolution: 720 x 720 pixels
• Type: IPS LCD
• Interface: MIPI DSI 4-lane
• Pixel clock: 41.4 MHz
• Active area: 89.6 x 89.6 mm
• Touch Controller: FocalTech FT6336U
  • Interface: I2C0 - ID_SC/ID_SD (GPIO 0/1), address 0x48
  • Touch Points: Up to 2 simultaneous touches
  • Resolution: 720 x 720 (matches display)

Display Timing Parameters (based on the initialization sequence from vendor):

• HFP (Horizontal Front Porch): 80 pixels
• HSA (Horizontal Sync Active): 20 pixels
• HBP (Horizontal Back Porch): 80 pixels
• VFP (Vertical Front Porch): 30 lines
• VSA (Vertical Sync Active): 4 lines
• VBP (Vertical Back Porch): 12 lines

GPIO Connections:

• Display Reset: GPIO 23 (configurable in device tree)
• I2C Bus: I2C0 (ID_SC=GPIO 0, ID_SD=GPIO 1) - DSI interface bus
• Touch INT: GPIO 25 (interrupt, see touchscreen setup)
• Touch RST: GPIO 24 (reset, see touchscreen setup)
• Power supplies: VCC: 3.3V (main power) and IOVCC: 3.3V (I/O power)

DSI Configuration:

• Interface: DSI0 on Raspberry Pi (configurable in device tree)
• Lanes: 4 lanes (data lanes 0, 1, 2, 3)
• Format: RGB888 (24-bit color)

Build and Installation

# Build the kernel module
make all

# Install the kernel module
make install

# Build and install device tree overlay
make dto-all

# Load the module
make load

Reboot and check kernel messages

dmesg | grep -E "(st7703|dsi|panel|vc4)"

After successful setup, you should see

vc4-drm gpu: bound fe204000.dsi (ops vc4_dsi_ops [vc4])
vc4-drm gpu: bound fe700000.dsi (ops vc4_dsi_ops [vc4])
sitronix,st7703: panel found
vc4-drm gpu: [drm] Initialized vc4 0.0.0 for gpu on minor 1

Configuration

Add to /boot/firmware/config.txt:

display_auto_detect=0
dtoverlay=vc4-kms-v3d
dtoverlay=st7703-gx040hd

# IMPORTANT: Use i2c_vc (for I2C0/DSI), NOT i2c_arm (for I2C1)!
dtparam=i2c_vc=on
dtoverlay=ft6336u-gx040hd

For X11 desktop environments, create /etc/X11/xorg.conf.d/99-fbdev.conf:

Section "Device"
    Identifier "GX040HD"
    Driver "fbdev"
    Option "fbdev" "/dev/fb0"
    Option "SWCursor" "true"
EndSection

Section "Screen"
    Identifier "main"
    Device "GX040HD"
    Monitor "GX040HD Monitor"
EndSection

Section "Monitor"
    Identifier "GX040HD Monitor"
    Option "DPMS" "false"
EndSection

FT6336U Device Tree Properties

1. I2C Interface: Enables I2C0 bus (ID_SC/ID_SD - GPIO 0/1)
2. GPIO Configuration: Sets up interrupt and reset pins with pull-ups
3. Touch Device:
   • Compatible with focaltech,ft6236 driver (supports FT6336U)
   • I2C bus: I2C0 (DSI interface bus)
   • I2C address: 0x48
   • Touch resolution: 720x720
   • Interrupt on GPIO 25 (falling edge)
   • Reset on GPIO 24 (active low)

The overlay uses compatible = "focaltech,ft6236" because:

• FT6336U is register-compatible with FT6236
• The edt-ft5x06 driver explicitly supports FT6236
• FT6336U is not in the kernel's device tree bindings but works with FT6236 driver

Touch Coordinates

The overlay includes touchscreen-inverted-x and touchscreen-inverted-y properties. You may need to adjust these based on your display orientation.

Edit ft6336u-gx040hd-overlay.dts and modify:

touchscreen-inverted-x;     /* Remove if X-axis is correct */
touchscreen-inverted-y;     /* Remove if Y-axis is correct */
touchscreen-swapped-x-y;    /* Add if X and Y are swapped */

Backlight Brightness Control

The panel's backlight (8 white LEDs, 4S2P, 20mA per string per the panel datasheet) is driven by external LED sink ICs on the carrier board. Brightness is controlled with the Raspberry Pi's hardware PWM on GPIO18, wired to the sink ICs' DIM inputs. The overlay sets up a pwm-backlight device and links it to the panel, so DRM blanks/unblanks it together with the display.

# Backlight device (created by the overlay)
ls /sys/class/backlight/
# -> backlight-pwm

# Set brightness (0-255)
echo 128 | sudo tee /sys/class/backlight/backlight-pwm/brightness

# Read current/max brightness
cat /sys/class/backlight/backlight-pwm/brightness
cat /sys/class/backlight/backlight-pwm/max_brightness

Note: dtparam=audio=on must stay disabled in config.txt — the analog audio driver claims the same PWM peripheral.

Why not the panel's own PWM pin?

The GX040HD FPC exposes a "PWM" pin (pin 8) and the ST7703 supports backlight PWM output via SETIO/SETCABC/WRCTRLD/WRDISBV. This was investigated in depth: the driver delivers the complete, datasheet-correct enable sequence (verified at source, binary, and boot-log level; the silicon returns genuine ST7703 IDs 0x38/0x21), yet the module never drives the pin — in either PWM polarity, with any command ordering, on multiple panel units. The vendor's own init sequence contains no backlight commands either. Conclusion: on this module revision the PWM pin is not functional (likely not routed/bonded).

The driver still sends the ST7703 backlight sequence at init (harmless, and future module revisions may implement it), and if no backlight phandle is present in the device tree it falls back to registering a DCS backlight that sends WRDISBV over MIPI. On vc4, note that DCS commands are only reliable before video starts — runtime brightness changes over MIPI do not work.

Testing and Troubleshooting

# Check kernel module
modinfo panel-sitronix-st7703

# Monitor kernel messages
dmesg -w | grep -E "(st7703|dsi|panel|vc4)"

# Check if display is detected
modetest -M vc4

# List available displays
fbset -s

# Check DRM/KMS status
sudo dtoverlay -l

# Enable debug output
echo 8 > /sys/module/drm/parameters/debug

# Check display controller status  
cat /sys/kernel/debug/dri/0/state

# Check panel power state
cat /sys/class/drm/card0-DSI-1/status

# Check DSI interface
ls /dev/dri/

# Check framebuffer
ls /dev/fb*

Testing Touch Input

# Basic test with evtest
sudo apt-get install evtest
sudo evtest
# Select the touch device (usually /dev/input/event0)
# Touch the screen and observe events

# Test with libinput
sudo apt-get install libinput-tools
sudo libinput debug-events

# Calibration (if needed)
sudo apt-get install xinput-calibrator
xinput_calibrator