Using the LCD3 cape on Beaglebone Black with Linux kernel 3.16.1

The Beaglebone Black is a palm-sized computer for electronics hobbyists, designed by Gerald Coley, charter member of Beagleboard.org.  Development is supported by an open source community, with the help of Texas Instruments (which manufactures the BBB’s embedded MPU, the AM3358).

If you’ve been struggling to get the Beaglebone LCD3 cape working with the mainstream Linux kernel releases from kernel.org, the first thing you need to know is that it can be done.  The key to making this work is to understand that dynamic cape loading isn’t yet supported in the mainline tree (but see Robert C. Nelson’s guide at elinux.org for a guide to building a special branch that does support dynamic cape load and unload.  Kernel 3.8+ works with the LCD3 cape).  There are a lot of people still working on cleaning up the code to meet kernel maintainers’ criteria for acceptance.  Until that happens, we’ll have to make do by cobbling together a custom devicetree source file to support devices which don’t yet run out of the box, using the mainline kernel source.

What works

  • Resistive touch screen using the AM3358 A/D converters
  • All five GPIO user buttons
  • GPIO-driven user LED
  • Backlight
  • And, of course, the TFT LCD itself

I’ll assume that you’re able to compile a Linux kernel, and have got around to doing so a few times for your BBB.  These instructions apply to the stable Linux kernel 3.16.1, but should be straightforward to apply to other (recent) releases which support the Direct Rendering Manager interfaces and ARM device trees.

I’d recommend that you install this newly compiled kernel onto an SD card filesystem, rather than use the BBB’s onboard eMMC storage.  Be warned that the kernel configuration file I’ve provided with this guide is taken from my own working system, which I use as a router – there’s a lot of firewall, bridging, etc., other networking-related modules built (and built-in) which may not be suitable for general use.

Steps

  • Power down and detach the LCD3 cape from your BBB.
  • Fetch and unpack a copy of the 3.16.1 stable kernel from https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.16.1.tar.xz.
  • Apply this patch to modify arch/arm/boot/dts/am335x-boneblack.dts and arch/arm/boot/dts/am335x-bone-common.dtsi, or fetch them from the links indicated.   You’d typically do cd linux-3.16.1 ; patch -Np1 ../lcd3-support-3.16.1.patch to apply this patch.
  • Copy this kernel configuration file over into the kernel directory tree root.
  • Run make ARCH=arm CROSS_COMPILE=arm-angstrom-linux-gnueabi- LOADADDR=0x80008000 uImage dtbs, etc. to build the kernel.  Alternately, if you’ve set up an in situ build environment on your BBB, you can copy this build script into the kernel directory tree root and run ./build.sh.  The script starts a complete build process starting with make menuconfig, to create a uImage-structured kernel and associated kernel modules.
  • Copy arch/arm/boot/dts/am335x-boneblack.dtb into the correct location for your BBB.
  • Restart your BBB to confirm that the kernel works for you.  You’ll want to take a look at the output of dmesg to check which devices were initialized.
  • Power off, and mount the LCD3 cape.
  • Power up.

Under the hood

The provided patch simply enables a number of device tree nodes, representing devices on the ARM system-on-a-chip (SOC).  The nodes that need to be exposed to the kernel to use the LCD3 cape are 1) the onboard A/D converter, 2) the enhanced high-resolution pulse width modulation subsystem (ehrpwmss), used for controlling the panel backlight,  3) general-purpose I/Os used to drive the user LED and provide interrupt-driven key events.

Note that the provided kernel configuration script enables a number of kernel features, the most important of which are

  • Support for touch panels using the AM3358 onboard A/D,
  • User input drivers for GPIO keys, and for building the evbug module (to aid debugging key press events), and
  • OMAP DSS DRM support.

After rebooting your BBB with this new kernel, the LCD3 cape should become available as a framebuffer device /dev/fb0.

To find out more: