Display for Orange Pi Zero

After figuring out the GPIO pin names of the Orange Pi Zero expansion port it is relatively easy to configure any TFT display as a FBTFT device attached over the SPI bus, as long as you know the name of the chip used to drive the LCD screen. Here is a list of all the chips supported by the Linux kernel out of the box.

The display I have is very similar to this 3.2″ Waveshare touch-screen display that uses the ILI9340 LCD driver (PDF) chip. It was only a matter of specifying the two GPIO pins used for DC (Data or Command) and RST (Reset) in addition to the SPI port.

  • H2+ port PA00 maps to GPIO 0, connected to RST
  • H2+ port PA03 maps to GPIO 3, connected to DC
  • H2+ SPI bus 1 is connected to the display module SPI pins.

The following command can be used to load the FBTFT device with the required configuration:

$ sudo modprobe fbtft_device custom name=fb_ili9340 gpios=dc:3,reset:0 speed=16000000 busnum=1 rotate=90

And then map the console output to the newly created framebuffer device:

$ con2fbmap 1 8

where 8 stands for /dev/fb8.

Here is the display running htop:

3.2″ TFT LCD Display for Orange Pi Zero Over SPI

Permanent Setup

Create a new file /etc/modules-load.d/fbtft.conf with the following content:


Create another file /etc/modprobe.d/fbtft.conf with the configuration for the fbtft_device device:

options fbtft_device custom name=fb_ili9340 gpios=dc:3,reset:0 speed=16000000 busnum=1 rotate=90

Finally, edit /boot/armbianEnv.txt to map the console output to the framebuffer device during the boot, by appending the following:



  1. Mark Birss says:

    Does your lcd screen output the kernel messages during boot up or just show login prompt ?

    Have you been able to set led screen brightness using pwm ?

    im using other small screen the adafruit22a

    • Kaspars says:

      It does show a few messages after the fb_ili9340 module is loaded and before the login screen.

      adafruit22a seems to be using the hx8340bn TFT driver chip which has a slightly different SPI init sequence. Did you get it working?

      • Mark Birss says:

        Your gpio pinout guide was most helpful

        I do get kernel messages if I use the serial debug port (RX – middle one) as GPIO 5 for the LED pin, but it does not always finish booting up with login prompt. (unstable for some reason) I have disabled the serial console and enabled pwm in the fex file

        I also currently cant get PWM screen brightness to work on this GPIO 5 either like with a Raspberry Pi


        When I use GPIO 7 i mostly only see the login prompt

        Where did you buy your screen ?

        My 320×480 screen does not work correctly either (only part of screen shows)

  2. Jiří Šmejkal says:

    Does this work or all models of Orange pi, or just with this one ? : )

    • Kaspars says:

      It should work with almost all single board computers since they all have SPI ports. You only need to know the pin mapping in the Linux kernel.

  3. Denis says:

    Is it possible to run Android OS on Orange Pi Zero and use this display?

  4. Jake says:

    Quiet simplified presentation.
    I was wondering if the same method can be applied for the 3.5 inch touch screen LCD module here.

  5. Serg_io says:

    Have you measured refresh rate?

  6. Agge says:

    Thanks a lot for the instructions.

    I managed to get a waveshare 3.5 A clone work by doing it like this:

    modprobe fbtft_device custom name=fb_ili9486 gpios=dc:18,reset:2 speed=16000000 busnum=1 rotate=90

    But with the “Armbian_5.25_Orangepizero_Ubuntu_xenial_default_3.4.113” image the boot halts just after starting to load kernel when I point the vt to fb8


    "con2fbmap 1 8" works ! strange

    • Kaspars says:

      Thanks for sharing that Agge! Are you saying that supplying the extraargs argument it doesn’t work while using con2fbmap it does? Are you able to see any errors messages during the boot over UART? Did you add a space before the extraargs parameter in /boot/armbianEnv.txt?

      • Agge says:

        Should there be a space before extraargs ?
        Have to look into that tonight.

        The uart halts just when kernel starts booting well halts. So no output from it

        • Kaspars says:

          Yes, there should be a space before extraargs. It probably halts at that line because of a formatting error.

    • Miguel says:

      Hey. I’m having exactly the same issue. The screen image in my tft seems to be very unstable. It gets stuck very often, did you sorted the problem out at the end ?

  7. PeMi says:

    have ili9340 2,4″ display at home, and pi zero with ext board on the way, looking to build a “internet radio” and “spotify connect” player by connecting external speakers – anyone has experience with this? any good tips on what software to use? Ideal internet radios as playlist of strem-urls, so just need some nice simple ui maybe? to control vlc? or any tips?

    and how to provide the spotify connect functionality (to show “play on xy”)? maybe even provide controls for this too?

  8. MrShark says:

    hi, do you think can be used with this module?

    can’t find the chipset on that page, but it seems to work with standard raspbian.

  9. Karthik says:

    Hey, your guide is very helpful for LCD display with Armbian OS. I am trying to do the same with Lubuntu Image available on Orange pi zero website.
    What would be the procedure to configure the same for 3.2 TFT LCD

    • Kaspars says:

      It should be exactly the same as long as you know the TFT chip name, I think. Did you try it already?

      • Karthik says:

        where to add the following line:


        I don’t see any config.txt or env.txt at /boot/ location

        • Kaspars says:

          Does it work when you manually run the con2fbmap 1 8 command after doing sudo modprobe fbtft_device ...? It should be working before you add it permanently to the boot file.

  10. Tobi says:

    Hi, I’ve managed to get the kumantech 3.5 inch screen kinda working. But unfortunately it stops working a few seconds after booting. It hangs and doesn’t update the screen anymore.

    I’m testing it with a waveshare 3.2 inch display right now and this display hangs after a while, too. But this time it took several minutes before it stopped working.

    Do you have any idea what’s going wrong here?

    I’m on the latest Armbian Ubuntu xenial image.

    • Kaspars says:

      I’ve had the same issue before but I’m not sure how to solve it. You could try lowering the SPI bus speed setting speed=16000000.

  11. Graham Harris says:

    Hi, I am trying to use this via a 26-pin RasPi GPIO Extension board- ie one of those T-shaped adapters that breaks out all the GPIO pins onto a breadboard.

    My challenge is that the labelling on that doesn’t closely match anything else.

    Could you please explicitly say which OrangePi Zero GPIO pins you have mapped to each of the ili9341 pins?


    • Kaspars says:

      My particular display connects to the SPI bus #1 (PA15 is MOSI, PA16 is MISO, PA14 is CLK and PA13 is CS) and two additional pins at PA00 and PA03 for RST and DC. Please note that physical pin numbers are different from the pin names in the Linux kernel and the GPIO numbers that are mapped to those pins. See the expansion port table on this page for how they’re all mapped together.

  12. Fred says:

    Nice!, it worked as well on the orange pi one, on bus SPI0 with a few changes:
    Both SPI modules are desactivated by default during the dtb fixup so in u-boot I’d to set: ‘setenv param_spidev_spi_bus 0’ before booting to have it activated and it worked.

  13. tonispax says:

    hello Kaspars,

    First it all thank you for this great tuto and review. I’d like to send you 2 suggestions:

    1st is to say that to follow your tips, we need to use a “hand builded image” of Armbian (https://github.com/armbian/build) instead of the pre-compiled available images on site.

    2nd is to use this command:
    modprobe fbtft_device custom name=fb_ili9340 gpios=dc:3,reset:0 speed=16000000 busnum=1 rotate=90 bgr=1

    This LCD (ili9340) or fbtft, in my case, was with blue and red colors swapped, and bgr=1 make it right again.

    Congrats again and best wishes,

  14. Hello
    Im getting this error executing the modprobe command on an orange pi zero:

    modprobe: ERROR: could not insert ‘fbtft_device’: Invalid argument

    Im using the prebuilt Arbian Jessie distro. Any idea what can be happening?

  15. RH says:

    Hey Kaspars!

    First off thank you for a awesome guide, I have one question though, do you know how to get the pi to output the framebuffer of the video not the console? As mines just outputting the console at the moment not whats actually going on.

    Thanks :)


  16. Bob says:

    Can you use the display in gui mode? When it’s no gui it works fine. But after upgrading system to some GUI desktop environment, display goes black…? Anyone had similar issues?

  17. DoubleHP says:

    Random tips :

    – orange pi zero all have 2 SPI bus: one in the main GPIO port, and one for the flash on the back side. If you don’t have the plus model, you can unsolder the FLASH and use the port. FLASH is port 1, so, GPIO is port 1. This is very important when you follow tutorials written for other opis

    – before you start following a tutorial, you need to understand which kernel you are using. If the turial is written after jan 2017, and mentions adding an overlay in armbianEnv.txt, then it’s for kernel 4; if the tuto is before feb 2018, and does not mention altering armbianEnv.txt for SPI compatibility, author is using kernel 3. This is critical.

    – I got adressable LEDs working on both kernels, 3 and 4. Easier on 4.

    – SPI LCDs work only on kernel 3; I have spend days on kernel 4, just forget them; drivers exist, but they are broken.

    – con2fbmap is required only on kernel 3

    – to get X working, you need to create /etc/X11/xorg.conf.d/99-fbturbo.conf

    – check your FB number with a command like this: dmesg | grep ili | grep graphics | grep -i fb . I have seen people using 0, 1 and 8.

    Now, I have ili9486 working perfectly fine … with image Armbian_5.35_Orangepizero_Ubuntu_xenial_default_3.4.113 (kernel 3.4.113).

  18. First of all, thank you very much for sharing. The display I use is waveshare ILI9486 4inch TFT shield compatibility for arduino. The problem of this shield is SPI config switch is set to ICSP as default. In fact, the switch must not be placed in the side of ICSP. I have wasted my time for not caring about this fact.

    Another problem is that fbtft is not available on latest armbian. So, I had to use Debian jessie 3.4 from Armbian Archive Storage, because fbtft_device is gone in linux kernel 5.4 (fbtft wiki).

    Finally, it worked well with this command.

    $ sudo modprobe fbtft_device custom name=fb_ili9486 gpios=dc:3,reset:0,led:6 speed=16000000 busnum=1 rotate=90
    $ con2fbmap 1 8

Leave a Reply