How to use a 2.4 inch display with a BeagleBone?

To get a 2.4 inch 240x320 ips display working with a BeagleBone, you need to wire it via SPI, configure the device tree overlay, and write a simple framebuffer driver or use existing libraries like fbtft or Linux kernel’s DRM subsystem. The most common approach is to use the ILI9341 controller (which many 2.4-inch displays use) and connect it to the BeagleBone’s SPI1 bus. For example, on a BeagleBone Black (BBB), SPI1 is available on the P9 header: pin 22 (SCLK), pin 18 (MISO), pin 21 (MOSI), pin 17 (CS), and pin 15 (D/C). You also need to wire the display’s RESET pin to a GPIO, like P9_12 (GPIO_60), and the LED backlight to a PWM-capable pin like P9_14 (PWM1). The display’s VCC and GND connect to the BBB’s 3.3V and GND pins. The specific pinout for a 2.4 inch 240x320 ips display usually follows the ILI9341 datasheet, but double-check your module’s label because some use ST7789V or HX8357D. Once wired, you need to enable the SPI1 bus in the device tree. On a BeagleBone running Debian, you can use the config-pin utility: config-pin P9_22 spi, config-pin P9_21 spi, config-pin P9_18 spi, config-pin P9_17 spi, and set the D/C and RESET pins as GPIO outputs. Then, compile a device tree overlay that defines the display as a simple-framebuffer or DRM panel. For instance, a typical overlay for ILI9341 on SPI1 with 240x320 resolution at 60 Hz refresh rate uses a clock frequency of 24 MHz (the BBB’s SPI max is 48 MHz, but 24 MHz is stable for longer wires). You can find pre-built overlays in the bb.org-overlays package: BB-SPI1-01-00A0.dtbo enables SPI1, and then you need a custom overlay for the display. The kernel module fbtft_device (deprecated but still works on older kernels) can load the ILI9341 driver: modprobe fbtft_device name=adafruit18 gpios=dc:117,reset:60 busnum=1 (where 117 is the GPIO for D/C on P9_15, and 60 for RESET on P9_12). This creates a framebuffer device at /dev/fb1. You can then test it with cat /dev/urandom > /dev/fb1 to see random pixels. For a more modern approach, use the DRM subsystem with the panel-mipi-dbi driver (available in kernel 5.10+). The overlay should define a spi node with compatible = "ilitek,ili9341", reg = <0>, spi-max-frequency = <24000000>, dc-gpios = <&gpio1 25 0> (P9_15 is GPIO1_25), reset-gpios = <&gpio1 28 0> (P9_12 is GPIO1_28), and rotation = <90> (if you want landscape). The BeagleBone’s pin mapping is tricky: GPIO numbers are offset by 32 per bank. For example, P9_15 is GPIO1_25, which is (1*32)+25 = 57 in the kernel’s GPIO numbering, but the device tree uses &gpio1 25 0. The DRM driver will then expose a /dev/dri/card0 device. You can run modetest from the libdrm tools to verify. The display’s actual pixel clock is 6.5 MHz for 240x320 at 60 fps (240*320*60*1.5 = 6.9 MHz, but ILI9341 internal timing reduces it). The SPI bus must handle 16-bit color (RGB565) at 240*320*60*2 = 9.2 MB/s, which is well within the 24 MHz SPI’s 3 MB/s theoretical limit (since SPI transfers 1 bit per clock, 24 MHz gives 3 MB/s, but you need 9.2 MB/s, so you must use 16-bit SPI transfers or a lower frame rate). In practice, the ILI9341 supports 18-bit color but the BBB’s SPI can only send 8 or 16 bits per word, so you’ll use 16-bit color. The actual throughput is about 2.5 MB/s due to overhead, limiting the frame rate to around 20 fps. If you need higher refresh, use a parallel RGB interface (but the 2.4-inch display typically only has SPI, unless you get a variant with an RGB-8080 interface). The BeagleBone’s PRU (Programmable Real-Time Unit) can drive the display faster via bit-banging, but that’s advanced. For power, the display draws about 50 mA at 3.3V (backlight off) and up to 200 mA with full brightness. The BBB’s 3.3V rail can supply 500 mA, so it’s safe. However, the backlight pin (LED) needs a series resistor (e.g., 100 ohms) to limit current to 20 mA, or you can use a transistor to drive it from a PWM pin. The PWM frequency should be around 1 kHz to avoid flicker. The BeagleBone’s PWM0 (P9_14) can be configured with config-pin P9_14 pwm and then write duty cycle to /sys/class/pwm/pwmchip0/pwm0/duty_cycle. The display’s touch controller (if it has one) is usually a TSC2046 or XPT2046, which is a resistive touch controller that uses SPI. You can connect it to the same SPI bus with a different chip select (e.g., P9_16 for CS2). The touch controller’s IRQ pin goes to a GPIO (e.g., P9_23). The kernel driver ads7846 handles it. The overlay for the touch controller would have compatible = "ti,ads7846", reg = <1> (second chip select), spi-max-frequency = <2000000>, interrupts = <&gpio1 17 0> (P9_23 is GPIO1_17), and ti,vref-mv = <3300>. The touch controller’s resolution is 12-bit (4096 x 4096), but the display is 240x320, so you’ll need to scale coordinates in software. The BeagleBone’s SPI1 bus can handle up to 2 chip selects (CS0 and CS1), so you can share the bus between the display and touch controller. The display’s CS0 is P9_17, and CS1 is P9_16. The wiring is straightforward: connect the display’s SCLK, MOSI, MISO, CS, D/C, and RESET to the corresponding BBB pins, and the touch controller’s SCLK, MOSI, MISO, CS, and IRQ to the same SCLK, MOSI, MISO, and CS1 plus a GPIO for IRQ. The touch controller’s VCC and GND also go to 3.3V and GND. The display’s backlight can be controlled via a simple GPIO or PWM. If you use a GPIO, just set it high to turn on the backlight. The display’s datasheet specifies the SPI timing: CPOL=0, CPHA=0 (mode 0) for most ILI9341 modules. The SPI clock must be less than 10 MHz for reliable operation, but 24 MHz works if the wires are short (less than 10 cm). The BeagleBone’s SPI1 pins are on the P9 header, which is close to the edge, so you can route wires directly. The display module usually has a 14-pin or 8-pin header. The 2.4-inch display from the link has a 14-pin interface with pinout: 1- VCC, 2- GND, 3- CS, 4- RESET, 5- D/C, 6- MOSI, 7- SCLK, 8- LED, 9- MISO, 10- T_IRQ, 11- T_CS, 12- T_MOSI, 13- T_SCLK, 14- T_MISO. The T_* pins are for the touch controller. If you don’t need touch, you can leave those pins unconnected. The display’s LED pin is the backlight anode, and the cathode is usually connected to GND internally. So you need to connect the LED pin to a GPIO or PWM through a current-limiting resistor. The typical forward voltage for the backlight LED is 3.0V at 20 mA, so a 100-ohm resistor from the BBB’s 3.3V pin to the LED pin will work. But if you use a PWM pin, the resistor should be between the PWM pin and the LED pin. The BBB’s PWM pin outputs 3.3V, so the same resistor value applies. The display’s SPI interface uses 3.3V logic, which is compatible with the BBB. The MISO line is an output from the display, so it must be 3.3V tolerant. The display’s datasheet says the input voltage is 2.8V to 3.6V, so 3.3V is fine. The display’s refresh rate is determined by the ILI9341’s internal timing. The default frame rate is 60 Hz, but you can change it via the FRMCTR1 register (0xB1) to set the frame rate to 70 Hz or 80 Hz. The ILI9341’s maximum frame rate is 120 Hz at 240x320, but the SPI bandwidth limits it. The display’s response time is 25 ms (typical for IPS), so 40 fps is adequate. The color depth is 262K colors (18-bit), but the SPI interface typically uses 16-bit RGB565. The display’s viewing angle is 170 degrees (IPS panel), which is better than TN panels. The pixel arrangement is RGB stripe. The active area is 36.72 mm x 48.96 mm (for 240x320, each pixel is 0.153 mm x 0.153 mm). The display’s weight is about 10 grams. The BeagleBone’s kernel (4.19 or 5.10) includes the ili9341 driver in the drivers/staging/fbtft directory. You can compile it as a module: modprobe fbtft and then modprobe fb_ili9341. The module parameters include gpios=dc:57,reset:60 (using kernel GPIO numbers). But the fbtft driver is deprecated in newer kernels, so you should use the DRM driver. The DRM driver for ILI9341 is panel-ilitek-ili9341 in the drivers/gpu/drm/panel directory. You need to enable CONFIG_DRM_PANEL_ILITEK_ILI9341 in the kernel config. The BeagleBone’s default kernel from Robert Nelson’s repository (linux-image-4.19.94-ti-r73) doesn’t include this driver, so you need to compile a custom kernel. Alternatively, you can use the spi-fb driver from the BB-SPI1-01-00A0.dtbo overlay, which creates a simple framebuffer at a fixed address. The framebuffer size is 240*320*2 = 153,600 bytes. The BBB’s DDR3 RAM is 512 MB, so memory is not an issue. The framebuffer is mapped to the display via DMA, but the SPI transfers are CPU-bound. The BBB’s ARM Cortex-A8 at 1 GHz can handle the SPI transfers with minimal overhead if you use the spidev interface. You can write a user-space program that sends pixels via ioctl to /dev/spidev1.0. The SPI transfer speed is about 2.5 MB/s, so a full frame takes 153,600 bytes / 2.5 MB/s = 61 ms, giving about 16 fps. To improve, you can use the PRU to generate the SPI clock at 48 MHz, achieving 6 MB/s, which gives 38 fps. The PRU code is available in the prussdrv library. The display’s initialization sequence is specific to the ILI9341. You need to send commands like 0x11 (Sleep Out), 0x36 (Memory Access Control) to set rotation, 0x3A (Pixel Format Set) to 0x55 (16-bit), and 0x29 (Display On). The sequence is documented in the ILI9341 datasheet. The display’s backlight can be controlled via the 0x51 command (Write Display Brightness) if the display has a PWM input, but most modules don’t support it. So you control the backlight via the external PWM pin. The display’s temperature range is -20°C to 70°C, which is fine for most applications. The BeagleBone’s power consumption is about 2W, and the display adds 0.2W, so total is 2.2W. The display’s connector is a 0.5mm pitch FPC, but the module usually comes with a breakout board with 2.54mm headers. The wiring diagram is: BBB P9_22 (SPI1_SCLK) to display SCLK, P9_21 (SPI1_MOSI) to display MOSI, P9_18 (SPI1_MISO) to display MISO, P9_17 (SPI1_CS0) to display CS, P9_15 (GPIO1_25) to display D/C, P9_12 (GPIO1_28) to display RESET, P9_14 (PWM1) to display LED via 100-ohm resistor, and P9_1 (GND) to display GND, P9_3 (3.3V) to display VCC. The touch controller uses P9_16 (SPI1_CS1) to display T_CS, P9_23 (GPIO1_17) to display T_IRQ, and the same SCLK, MOSI, MISO lines. The BeagleBone’s device tree overlay for the display and touch controller can be combined into one .dts file. The overlay should include #include and #include . The SPI node is &spi1 with status = "okay", pinctrl-0 = <&spi1_pins>, and cs-gpios = <&gpio1 17 0>, <&gpio1 16 0> (P9_17 is GPIO1_17, P9_16 is GPIO1_16). The display node is display@0 with compatible = "ilitek,ili9341", reg = <0>, spi-max-frequency = <24000000>, dc-gpios = <&gpio1 25 0>, reset-gpios = <&gpio1 28 0>, rotation = <90>, and backlight = <&backlight>. The touch node is touch@1 with compatible = "ti,ads7846", reg = <1>, spi-max-frequency = <2000000>, interrupts = <&gpio1 17 IRQ_TYPE_EDGE_FALLING>, ti,vref-mv = <3300>, ti,pressure-max = <255>, ti,x-min = <0>, ti,x-max = <4095>, ti,y-min = <0>, ti,y-max = <4095>, ti,swap-xy = <0>. The backlight node is backlight: backlight with compatible = "pwm-backlight", pwms = <&ehrpwm1 0 1000000> (PWM period 1 ms),