BeagleBone Black and Watterott display

For a long time I had been aiming to connect some small display to any of my small computers, specially the BeagleBone. Well, some weeks ago I finally succeeded to get one up an running. The display is the Watterott MI0283QT-9A (https://github.com/watterott/MI0283QT-Adapter). It is well-known by the Raspberry Pi and the Beaglebone communities. It has a reasonable quality-price ratio and is very easy to use.

BeagleBone Black Debian console in Watterott LCDBeagleBone Black Debian console in Watterott LCD

I actually bought the version 2 of this adapter+LCD some time ago. It was accumulating dust in a shelf for several months, waiting for me to get some time to try it out. Then I saw a cool picture from Francesco D'Aluisio on Google+ showing the display connected to a BeagleBone. That encouraged me to try my own LCD. And all that happen around Christmas time so I thought... I will have a lot of time to play with this LCD.

Unfortunately, it seems that the version 2 does not work out of the box. At least mine didn't worked. I spend several days trying to make it work. Lots of frustration. Not even the kind help from Francesco D'Aluisio worked for me. Not even the neat write up (you can find here http://noisezero.blogspot.nl/2013/12/watterott-mi0283qt-9a-display-on.ht...) he published.

During my frustrating voyage, at some point I gave up with the SPI interface and tried the I2C. At least I'd got the test screen after several days watching that black display as the result for my desperate tries.

Test application for Watterott LCD adapter 2Test application for Watterott LCD adapter 2

Using the I2C I found out that the display worked and my last chance was to go deeper into the adapter board microcontroller firmware and look into the code, which by the way is open source. Good for Watterott. Unfortunately, the Xmas break was almost over and I couldn't get any far through that path.

So, out of my frustration I just bought the previous version of the adapter board. The one everybody else was using out there and then, everything worked flawless.

USING THE DISPLAY WITHOUT ANGSTROM

The write up from Francesco D'Aluisio covers everything you need to do in order to make this display work in your BeagleBone Black using the Angstrom distribution. That distribution is very good, compact and fast. However I decided I'll be using a different development environment (http://papermint-designs.com/community/node/391) and therefore I had to work this out in a slightly different way. I will describe what I did to make the display work on that environment.

You might remember (in case you read the article mentioned above) that I was following the instruction from Robert C Nelson. You can find those instructions here [http://eewiki.net/display/linuxonarm/BeagleBone]. Following the steps in that page you can bring up a full Debian system very easily, including a full kernel source tree configured for the BeagleBone.

The Watterott display (version 1) is supported by the fbtft driver from notro. There is an experimental driver for version 2 adapter but it didn't work for me when I tried. So the first thing we have to do is to compile the fbtft kernel drivers from notro (https://github.com/notro/fbtft/wiki). For doing that, you have to cd into linux-dev/KERNEL/drivers/video and then follow the instructions from notro's wiki. I reproduce them here for your convenience:

cd linux_dev/KERNEL/drivers/video
git clone https://github.com/notro/fbtft.git

Add to drivers/video/Kconfig:   source "drivers/video/fbtft/Kconfig"
Add to drivers/video/Makefile:  obj-y += fbtft/

After that, you can run make menuconfig and select the drivers in the new menu option we had just added under "Device Drivers>Graphics". Just activate everything as modules. It might happen that the option does not appear. In that case try to set and unset some of the options in that page (The AGP or DisplayPort support worked for me when that happen).

Then you need to recompile the driver. You have to run the following commands:

(cd linux_dev) 
./tools/rebuild.sh

This will recompile your kernel, effectively applying the changes you had just selected using the menuconfig interface. Please refer to this section on Robert C. Nelson guide (http://eewiki.net/display/linuxonarm/BeagleBone#BeagleBone-InstallKernel...) for the details to re-install your kernel and modules in your SDCard.

TESTING THE DISPLAY FIRST TIME

Now it is time to test the display. First thing we have to do is wire the display to the BeagleBone. These are the connections you need to wire.

BBB PIN LCD PIN
1 GND 1/2 GND
3 3.3V 3/4 Vcc
11 GPIO_30 6 Reset
12 GPIO_60 5 LED
17 SPI0_CS0 7 CS0
18 SPI0_D1 8 MOSI
21 SPI0_D0 9 MISO
22 SPI0_CLK 10 CLK

You can now boot the beaglebone pressing the Boot button to instruct the board to boot from the SDCard instead of booting from the internal Flash. Once booted we need to activate the SPI interface and load the driver for our LCD.

# echo BB-SPIDEV0 > /sys/devices/bone_capemgr.*/slots
# modprobe fbtft_device name=mi0283qt-9a busnum=1 cs=0  gpios=reset:30,led:60 debug=1 verbose=3 speed=32000000

You need to run this commands as root. The debug and verbose parameters will just produce additional information in the system log that might be useful in case something does not work as expected. Check it with dmesg and you should see how the SPI message gets activated and the framebuffer device is successfully created.

Now you should have a new /dev/fb1 device. Let's try it.

First we can show some pictures on the framebuffer, using the fbi application. You probably will have to install it with apt-get and copy some image into your Beablebone. Then you can run a command like this:

fbi -noverbose -autodown -T 1 -d /dev/fb1 test.jpg

This will show the image test.jpg in the framebuffer 1 disabling the caption and autoscaling the image down.

BeagleBone Black showing an image in Watterott LCDBeagleBone Black showing an image in Watterott LCD

You can also play a movie using mplayer.

mplayer -vo fbdev2:/dev/fb1 -vf scale=320:-3 BigBuckBunny_320x180.mp4

BeagleBone Black showing an video in Watterott LCDBeagleBone Black showing an video in Watterott LCD

ACTIVATING THE DISPLAY ON BOOT

Our display is working pretty well but, right now, we have to run quite some commands by hand just to activate it. It would be very nice to bring the display up at boot time. To do that we have two main options.

  • Option 1 is to convert our display into a cape so our EEPROM contains the proper device tree overlay to activate the SPI interface at boot time.
  • Option 2 is to change the boot arguments for our BeagleBone to force the load of a specific overlay.

We will be using Option 2 in this write up. Option 1 will probably become part of the TESTCape series that is on hold right now. So what we have to do is to edit the /boot/uboot/uEnv.txt file adding a line like:

optargs=text capemgr.enable_partno=BB-SPIDEV0 fbcon=map:01

Yes, the first thing we are doing is loading of the BB-SPIDEV0. This will ensure that our SPI interface is ready as early as possible, but we still have to load the kernel module to effectively activate the display. This requires the modification of two files:

/etc/modules

fbtft_device

/etc/modprobe.d/watterott.conf

options fbtft_device name=mi0283qt-9a busnum=1 cs=0 gpios=reset:30,led:60 speed=32000000 rotate=270

Note that now we had remove the verbose and debug parameters and we had added a rotate parameter, just for illustration purposes.

The other thing we do is to map our two framebuffers to alternative consoles. That way, console 1 (tty1) will be mapped to framebuffer 0 (the HDMI interface in the beaglebone). The second console will be mapped to framebuffer 1 (our SPI LCD). The third (tty3) again to fb0 (HDMI), and so on... If you plug a keyboard to the BBB and press ALT+F1 you will be using the HDMI display. If you press ALT+F2, you will be using the LCD... cool!. Note that the display will be blank until you activate it pressing the ALT+Fx key combination or until you execute any command that uses the framebuffer.

Also note that you can map the consoles after boot using the con2fb command

So, this is it. Now our display will be ready to be used after boot and we still can use the HDMI output, effectively having a dual head system. You can also disable HDMI in the optargs (for instance, to save power when running on batteries) and in that case your LCD will become /dev/fb0. This can be done with the following line on uEnv.txt

optargs=text capemgr.disable_partno=BB-BONELT-HDMI,BB-BONELT-HDMIN capemgr.enabl
e_partno=BB-SPIDEV0

Now that your framebuffer is up an running you can search the Internet for all the cool things you can do with a framebuffer device (starting X-Windows, using DirectFB and SDL, or play with the fbcon boot argument...). From this point on everything is general Linux stuff :)

CU
The picoFlamingo Team