Tontec 3.5″ TFT


Update 28/12/2014: I have new post that should now be used for setting up the display and touch screen. It uses the pre-build kernel from Notro rather than my kernel as it will be kept more up to date.

Update 05/12/2014: Noralf has now included my patches in his master branch of fbtft driver. He will release a new kernel including this driver soon. For more information visit his wiki here. Of course you can still follow the guide below if you wish to get roll your own kernel. It is also useful as a reference for getting the touch screen working.


I received this device as a birthday present last weekend. I was keen to get it going so I downloaded the off the manufactures web site and began running through the user manual. After about 20 minutes I had the screen working :-) I soon realized that the software (“driver”) was quite lame and ran completely in userland (no place for a hardware driver to run). So I took to google and started searching for spi based LCD frame buffer drivers and came across the excellent fbtft driver by Notro. Reading through the documents in the wiki I soon discovered that the Tontec 3.5″ device was not supported by this driver. So no stranger to some kernel hacking I decided to add support for it.

Adding Support to fbtft

First up I forked the code to my own github account. I then set about trying to locate some datasheets for the screen. This proved very tricky so I gave up and decided to reverse engineer the lame driver that came with it. Browsing the code I came across some references to ili9481, great there might be some light at the end of the tunnel as fbtft already had support for this device. After some initial tests I found it was not as simple as using the existing ili9481 driver. The main differences were the gpio control pins, the device register width, SPI mode and the initial state of the backlight. For the gpio assignments this was taken from the user manual. The other items were worked out from the tontec source code.

Building a custom kernel

Before I begin let me explain my setup. I will be using a relatively low end laptop running Ubuntu Linux. Building the kernel (or any other large code base) on the Pi is insane as it would take an age and when your hacking you want to get testing changes as quickly as possible. So all steps below will be run on the PC unless stated otherwise.

Before beginning the build we need to enable the fbtft drivers (while we at we should also enable the touch screen driver). To enable the drivers we need to run “make menuconfig”.

Using the menu is quite simple. Cursor up, down, left, right, enter and spacebar are the only keys you need to use. So once it is up and running navigate to the following sections (*=built in, m=module, select using spacebar):-

  • Device Drivers —>
    • Input device support —>
      • [*] Touchscreens —>
        •  <*> ADS7846/TSC2046/AD7873 and AD(S)7843 based touchscreens
    • [*] SPI support —>
      • <*> BCM2708 SPI controller driver (SPI0) {changed from M to *, gets around modules blacklist problem}
    • Graphics support —>
      •  Console display driver support —>
        • [*] Framebuffer Console Rotation
      • <*> Support for small TFT LCD display modules —>
        • <*> FB driver for the ILI9481 LCD Controller
        • <*> FB driver for the ILI9486 LCD Controller
        • <*> Module to for adding FBTFT devices

Once you have selected the options about exit the menu and save the changes when prompted.

Now we also need to edit the arch/arm/march-bcm2708/bcm2708.c board config file to replace the spidev for our tontec35 driver. Without making the change it won’t be possible for the fbtft driver to claim the SPI port. While we are editing in this area we will also add the config for the touch screen driver (ads7846).

Fisrt open up the file arch/arm/mach-bcm2708/bcm2708.c and find the section that looks like this:

Then replace it with the following and save changes:

We also need to add some header files to the top of this file of the kernel will fail to build.


Ok now its time to build the kernel.

Now you should have a file (fbtft-kernel.tgz) that you can transfer to the RapsberryPi. As I am using Linux and the Pi is also running Linux is simply transfer it using scp. There are many other ways to get the file to your Pi I will let you work it out. But for now here is how I do it:

Once the file has been transferred you need to install it on the Pi. So login to the Pi (either on the console or via ssh). Then perform the following:

Ok almost there. Now we also need to edit /boot/cmdline.txt to tell the kernel to use the new framebuffer for console output. We basically add “ fbtft_device.rotate=90 fbcon=map:10 fbcon=font:VGA8x8” before the “rootwait” parameter. Note: This should be one line and is probably displayed wrapped in the browser and your text editor.

Example for models with ili9486 displays:

Example for models with ili9481 displays. The key difference is the* part:

Once you have saved the cmdline.txt and exited your editor you also need to edit /boot/config.txt to tell the RPi what kernel to load. Open up the file and look for a line beginning with “kernel=”. If this line does not exist add one somewhere in the file like this (added to the bottom of the file):

Once you have saved the config.txt file you can try out the TFT. Type “sudo reboot” to restart your Pi. When it comes backup you should now see the console output on your TFT.

Note: If you installed the software provided by Tontec you will want to disable/remove it before your reboot. If you don’t then there might be some strange behaviour as the kernel driver and userspace application both try and control the screen. The easiest way to disable it is to comment out the line in “/etc/init.d/lcd” that reads “sudo /home/pi/mzl350i-pi-ext/src/mzl350i”.

Pre-built kernel

I am aware that most people probably won’t want to roll your own kernel out so I have uploaded a copy of my kernel here for your convenience. You can follow the following procedure on your Pi to install it:

Update 04/12/2014: Added a new kernel image. This image now supports both the ili9481 and the ili9486 displays in the same image. It also adds spi-bcm2708 drivers into the kernel instead of being a module. This enables the screen to start up quicker and removes the need to edit the modules blacklist files. See above for details about selecting correct display in cmdline.txt.

Touch Screen

The kernel image described above also includes support for the touch screen. To confirm it works please install the following packages:

You can confirm that the driver is loaded using the dmesg command.

From the above we can see that the touch screen has been added to input0. This will translate to “/dev/input/event0” as a device node. You can confirm that touching the screen generates events using the evtest program.

You can also try the ts_test and ts_calibrate. These use libts and have some basic graphics.

I am yet to try X-Windows. Once I have more information on this I will update the page.


Thanks for reading. Feel free to leave comments or questions below.



Tontec 3.5″ TFT — 38 Comments

  1. Hi

    Really great blog post! I also had issues with the driver but was not clever enough to reverse engineer fbtft support.

    I contacted Tontec and they sent me some updated FBTFT source with support for there display. They told me there are two types of display using the ili9481 (Boards dated before july 2014) and ili9486 for newer boards.



  2. Hi Jon

    I found a typo above. line 33 of your setting up the build environment code reads

    ln -s ../../../driver/video/fbtft/fbtft.h .

    But it should read

    ln -s ../../../drivers/video/fbtft/fbtft.h .



    • Hi David,

      Thanks very much for your comments. You must of caught me between updates. I have been running through it here in work and found quite a few little mistakes. I had also forgotten to add the include files to the top bcm2708.c. I have also nicked your “–depth 1” for the git clones. It speeds things up quite a lot.

      I have also been working on an alternative patch that uses the ili9481 and ili9486 drivers instead of adding another driver for the board. Out of curiosity which model do you have?



      • I now have both types of board as I have 2 projects :-) Decided to get another board now their are drivers.

        Very happy to test your dual driver patch, was just about to try to compile your touch settings into the original Tontec source, but think I will wait for your new combined patch.

        Out of interest what development environment do you use when doing kernal type development? I use visual studio in a windows environment but on the PI I just use vi and make. Do you use a debugger or just write to std out or logs?

  3. When i execute sudo tar zxvf fbtft-kernel-0.1.tgz -C /
    i get the following error ( i pasted the last 2 lines )


    • lib/modules/3.12.33+/modules.symbols.bin
      tar: Exiting with failure status due to previous errors

      • What were the previous errors?
        They should of been printed during the extraction at some point.
        Maybe you can try it without the ‘v’ option:

        This should then just display any errors during the extraction.
        Also make sure you have enough disk space on the SD card. Check space with the “df -h” command.

      • Hi I have confirmed the errors. These are being caused by the writing of the kernel image to the /boot partition. The /boot partition is FAT32 and does not support unix file permissions. The following errors can be ignored

        I have also updated the kernel image. See “Pre-built kernel” section for more information.



  4. Thanks for a great post. I tried what was suggested by downloading the Pre-built kernel and followed the instructions but I must have messed up somewhere as I just got a blank screen. I will have another go.

    • Hi John,

      I discovered from David’s blog (see comment from him) that there are 3 different version of the board floating around.
      Mine is: MZ9486-PI-EXT and this is what the kernel is currently built for. You can see the board version on the back of the PCB. What version do you have?
      Also not mentioned in my post is that the SPI module needs to be loaded. So check “/etc/modprobe.d/raspi-blacklist.conf” and make sure yo have commented out the blacklist line for “spi-bcm2708”. The file should look like this:



      • Hi Jon

        Thanks for the reply. I have the 9486 too, I was using the image for that one from the link David gave.

        I was doing it on small SD over SSH and I had the pi running the GUI so may have run out of memory or disk and not noticed. I have copied the image now onto a bigger SD will try again and make sure I change spi-bcm2708.


        • Hi John,

          I have now updated my kernel image to build in the spi-bcm2708 driver to the kernel. So it no longer needs to commented out in the black list file. The new image now also support both the ili9481 and ili9486 devices. Choosing the device is done by adding additional parameters to the /boot/cmdline.txt file. See full article for further details.


  5. Hi, I have used your kernel and I have got touch working now on the tontec screen, many thanks, but when I start X, the display switches back to the HDMI monitor. Touch still works on the tontec display rather like a mouse trackpad. I thought there may be a way to set the display for X using xprofile but I can’t find any further info that works on the pi. Are you aware of any links that may help?


    • Hi John,

      I have not tried X windows yet. But I have seen that you need to specify the frame buffer before starting. Do you boot directly into X or start it manually?
      If the latter then try this:

      See here for more details:


  6. Hi Jon,

    Thank you for the easy to follow post. I received my Pi B+ this week and i cannot wait to get the touchscreen working.

    Following the instructions i got bumped quite in the beginning:

    When i was going through the

    # run kernel menu config
    make menuconfig:
    ADS7846/TSC2046/AD7873 and AD(S)7843 based touchscreens

    the list was empty for me. I have redone the steps just in case i missed something but no luck.

    I keep trying to get around this, but just in case, do you have any suggestion?


    • Hi Greg,

      Sorry for the late response things are quite hectic at the moment.
      When you run “make menuconfig” do you see a cursor based blue screen?
      Are you trying this on a Linux PC (not raspberry pi)?

      You could try the pre-built kernel it might be a little easier.


      • Hi Jon,

        Thanks for trying to help.
        Yes, i do see a cursor based blue screen and i can navigate through the options, though the touchscreen submenu is just empty.

        Device Drivers —> Input device support —> [*] Touchscreens —> EMPTY list

        I’m trying this with Debian 7.7 on a laptop.

        Let me give a shot with your pre-built kernel and get back to you here.


        • HI,

          Works perfectly with the pre-built kernel, i can see the console and the touchscreen also works.

          • Hi guys,

            I’m no expert rather just lucky, but i managed to get the X to load on the touchscreen.

            1, sudo apt-get install xserver-xorg-video-fbdev
            2, sudo nano /usr/share/X11/xorg.conf.d/99-fbdev.conf
            2.1 paste:
            Section “Device”
            Identifier “myfb”
            Driver “fbdev”
            Option “fbdev” “/dev/fb1”

            2.2 save and exit
            3. startx

            this works for me, the source is from (as Jon mentioned before) here: “”


          • Hi again,

            i got stuck now, i’m a noob here so i can only report what i found:
            Im experiencing some touch calibration issues even after calibration:

            1, the top, right, bottom, left 20-30 pixels are non sensitive
            2, when i move my finger :
            right -> the mouse moves down
            up -> left
            down -> right
            left -> up

            i guess this is adjustable somewhere and i assume this has something t do with the screen rotation in the cmdline.txt


  7. Hi Jon,
    I have followed all the steps using your kernel, but there is no image on the TFT display, I pluged the HDMI cable and I can see that the touch is working but the TFT is just black.

    Do you know how can I make the TFT show the image? Or maybe I’m just missing something.


    • Hi Keraz,

      First are you using the pre-built kernel?

      If so which board do you have? Please tell me the model number printed on the back of the LCD PCB.



  8. Hi Greg,
    did you find out, or anybody knows how to fix touch screen?
    I do have similar problem. just in my case if I touch:
    top-left corner mouse moves to bottom-right;
    top-right is OK;
    bottom-left is OK;
    bottom-right corner mouse moves to top-left;

    I did had problem were X didn’t load after kernel changes (I used pre-build kernel). But yours post how to start X helped. but now I have similar problem as I described already. It feels like touch screen needs calibration..

    thx for replay.

      • It Works!! google you my god!

        Section XCalibraton on the bottom of this post:

        Just were says:

        “Run sudo nano /etc/X11/xorg.conf.d/99-calibration.conf and copy the… ”

        I had no such path so I crated using:

        sudo mkdir /etc/X11/xorg.conf.d && sudo nano /etc/X11/xorg.conf.d/99-calibration.conf

        and paste (in my case, yours can be different):

        Section “InputClass”
        Identifier “calibration”
        MatchProduct “ADS7846 Touchscreen”
        Option “Calibration” “3930 89 3920 141”
        # Option “SwapAxes” “1”

        Hope someone find this useful.

        • Hi Minde,

          Thank you for the information. I am putting together a new post that includes information from you and Greg. The post will be a more complete setup guide using the pre-built kernel from Notro’s fbtft project.



  9. Awesome work!
    I have one problem though. When I use the touchpanel the screen goes black after a while. This happens immediately when I use a finger but only after a while when using a stylus. When it goes black I can’t do anything but restarting the Pi.
    It happens when I run for example ts_test but it happens quicker when I run X (works fine to start it with “FRAMEBUFFER=/dev/fb1 startx”).
    Anyone else had this problem? Could this be a configuration problem (the CPU goes up to close to 100%) or is my Tontec broken?

    Thanks in advance!
    / Fredrik

  10. Hi Jon,

    Brilliant instructions, I’m a complete noob but “father Xmas” bought my kids a load of raspberry Pi’s and the tontec screens so I’ve had to try and get them working. Managed to follow your pre-built kernel instructions Greg’s post to get it working on X. But still have a few issues. opening some programmes and games in particular the sizing of the windows are wrong and off the screen and therefore unplayable. Any thoughts on where additional adjustment can be made?
    Also, is there a way to toggle between the 2 displays, sometimes using the tontec but other times using the monitor, or even better automatically allow both displays. Where is the easiest place to change this as and when needed?

    Apologies in advance for idiot’s questions, I’ve got a lot of learning to do!



    • Hi Sunny,

      Thank you for your comments. Regarding the window positioning: this could be caused by the applications being to big for the physical screen resolution. There is not much that can be done about that without modifying the source of each application and adjusting the sizes. Some SDL based games might be able to run in full screen mode (possible try “alt+enter” on the keyboard to force them into full screen if supported).

      Being able to toggle between the 2 displays would be quite tricky (but not impossible). You could configure X for dual head but this might cause more issues due to the 2 screens having totally different resolutions (clone mode in particular). It might be easier to create a script that renames or moves the 99-*.conf files you have created for the touch screen. This would also depend on how you start X (boot directly into X or manually start from the command line). There are several ways I can think of to do this but would require a bit of experimentation. By far the easiest way might be to have 2 SD cards (one for each screen option).

      To be honest these little screens are not really ideal for replacing monitors. There best used for custom projects/applications that are designed to run within the resolution.

      I hope this is in some way helpful. If you want to bounce some ideas off me that is fine.



      • Hi Jon,

        Thanks for the quick response, people like you are really inspirational as part of the amazing Linux community with incredible knowledge and a passion to pass on solutions to all and sundry. Keep up the good work!

        Re. the limitations of the screen. I’m now getting that, originally I bought them totally blind (as well as the pi’s) thinking it was a quick way to get my younger ones into it without sitting them at a monitor but you’re clearly right. It’s fine for scratch and the programming side but not fit for surfing, even retro gaming etc. I think I’ll go back to basics for them and maybe play around with one myself.
        Simple solution having 2 SD cards for each display but in the fullness of time I’ll have a play with trying something more adventurous.
        Thanks again, you’re a linux hero :-)

  11. Hi Jon,

    Been trying to get this screen working for about 3 months now. The driver ‘supplied’ by Tonec does only half the job, as you’re well aware (and inefficiently too, it seems). Though my project doesn’t nessecarily require a functioning touchscreen, without it I need to rely on a wireless keyboard/mouse that is not only frustrating to use but cannot be used simultaneously with a wireless adaptor. Presumably they both draw too much power when used together. Powered USB hubs seem to be out of the question too. This is somewhat debilitating as you can probably imagine.

    Anyways, to say your custom kernel and guide has been a bright beacon of hope would be an understatement. That being said I’m still having problems. The lcd remains blank (I removed tonec’s script in init.d, as you suggested, after noticing the display ceased to update after touching the screen) and as someone mentioned before, (what I’m guessing are) the top left and bottom right quarters seem to imply I’m touching a location in the opposite corner. Any help would be appreciated.


    • Hi Sean,

      Thanks for your comments. This page is a little outdated compared to a newer post I created a few weeks ago ( The new post uses a different kernel provided by Notro (author of the fbtft driver) that includes my changes for the tontec displays. It also includes more complete instructions for getting X and the touch screen working. Please give it a try and let me know how you get on.



  12. Sir
    Can I use same procedure for Adafruit piTFT 2.8″ resistive display or some changes are needed? can you please suggest it? I think the controller for piTFT is quite same and compatible (fbtft driver supports piTFT). I can not use display driver provided from adafruit since I am using Yocto to build LINUX.