View source for Framebuffer driver for SH1106

[[File:Framebuffer_console_on_SH1106.JPG|thumb|400px|right]]
If you want to ditch ZPUI and use the ZeroPhone screen from your own code, you might want to use a framebuffer. This is how to compile and install FBTFT drivers for the SH1106 and drive the screen, all using a Raspberry Pi Zero.

'''Warning: this article describes compiling your own kernel modules. You might not *have* to do that in the future, that is, when Raspberry Pi finally gets a kernel that contains the fb_sh1106 driver.''' You definitely do not need to compile anything if you're using a SSD1306 screen (the official ZeroPhone screen is SH1106, so if you're using a ZeroPhone you didn't yourself assemble with a SSD1306 screen, you most likely have SH1106.)

If you have the fb_sh1106 driver available (can check with "modinfo fb_sh1106"), skip to the [[#Loading the driver|Loading the driver]] section.

<spoiler text="Full command-line">
 sudo apt-get update
 sudo apt-get dist-upgrade
 #If the dist-upgrade command has installed a new kernel, reboot, then continue from the next line
 sudo apt-get install git bc raspberrypi-kernel-headers
 git clone --depth=1 https://github.com/raspberrypi/linux
 cd linux/
 wget https://github.com/torvalds/linux/commit/079306e979d7f8bb1081ce43c7fc1fa8c1d45d55.patch
 git apply 079306e979d7f8bb1081ce43c7fc1fa8c1d45d55.patch
 sed 's/u32 \*curves/unsigned long *curves/' drivers/staging/fbtft/fb_sh1106.c
 cp /usr/src/linux-headers-4.9.59+/Module.symvers .
 cp /usr/src/linux-headers-4.9.59+/.config .
 make oldconfig
 #Press 'm' when asked on what to do with the SH1106 driver and any FBTFT-related drivers. Press 'n' or 'm' (whatever you want) for any unrelated modules that might pop up.
 make modules_prepare
 make M=drivers/staging/fbtft
 sudo cp drivers/staging/fbtft/*.ko /lib/modules/4.9.59+/kernel/drivers/staging/fbtft/
 sudo depmod -a
 sudo service zpui stop
 sudo modprobe fbtft_device custom name=fb_sh1106 gpios=reset:5,dc:6 speed=32000000
 dmesg|tail -n30
</spoiler>

==Preparing for compiling stuff==

 sudo apt-get update
 sudo apt-get dist-upgrade
 #If the dist-upgrade command has installed a new kernel, reboot, then continue from the next line
 sudo apt-get install git bc raspberrypi-kernel-headers

==Getting sources==

I wish I could say "apt-get install raspberrypi-kernel-sources", however, they're *still* available only from Github, not from Raspbian repositories.

 git clone --depth=1 https://github.com/raspberrypi/linux
 cd linux/

==Applying the SH1106 driver initial commit==

'''This instruction was tested on: 4.9.59+ kernel'''

The commit that added the driver was made later than the 4.9.59 release, which is what the article is written for. You might not need it if you're running later versions of Raspbian, Raspbian Testing or other Raspberry Pi OSes.

[https://github.com/torvalds/linux/commit/079306e979d7f8bb1081ce43c7fc1fa8c1d45d55 Here's the commit in question], you can wget it with:
 wget https://github.com/torvalds/linux/commit/079306e979d7f8bb1081ce43c7fc1fa8c1d45d55.patch
Apply it with:
 git apply 079306e979d7f8bb1081ce43c7fc1fa8c1d45d55.patch
However, it's not done yet. FBTFT has changed between the 4.9.59+ release and when the commit was created. Specifically, the set_gamma function signature has changed. Run this command-line to patch it:
 sed 's/u32 \*curves/unsigned long *curves/' drivers/staging/fbtft/fb_sh1106.c

==Preparing the kernel module compilation==

In order to build the kernel modules, we need to get .config and Module.symvers files. 

 cp /usr/src/linux-headers-4.9.59+/Module.symvers .
 cp /usr/src/linux-headers-4.9.59+/.config .

==Compiling and installing the driver==

 make oldconfig
Press 'm' when asked on what to do with the SH1106 driver and any FBTFT-related drivers. Press 'n' or 'm' (whatever you want) for any unrelated modules that might pop up.
 make modules_prepare
 make M=drivers/staging/fbtft

If nothing has failed by this point, the driver should be ready! Now, let's copy it into the module directory:

 sudo cp drivers/staging/fbtft/*.ko /lib/modules/4.9.59+/kernel/drivers/staging/fbtft/

We also need to register it with the system, so that modprobe knows about it:

 sudo depmod -a

==Loading the driver==

If you're doing this on ZeroPhone, do know that ZPUI won't be accessible to you after loading the driver (and until you reboot, unless somebody writes instructions on unbinding devices). Thus, you might want to enable the USB port before doing this, for example. 

Before loading, stop ZPUI:

 sudo service zpui stop

Load the module:

 sudo modprobe fbtft_device custom name=fb_sh1106 gpios=reset:5,dc:6 speed=32000000

At this moment, the screen should flicker or something (it might not flicker, though). To see if anything has failed along the way (the module won't always fail to load upon error):

 dmesg|tail -n30

==Testing if it works==
[[File:Images_on_SH1106_framebuffer.JPG|thumb|400px|right]]
# You should get a new framebuffer device - likely, /dev/fb1
# With "sudo con2fbmap 1 1", you should get a Linux console on the screen
# You can output images to the screen with "fbi":
 sudo fbi -T 1 -d /dev/fb1 -a /home/pi/ZPUI/splash.png

==TODO==

# Figure out how to unbind the SPI device after unloading the driver: [https://lwn.net/Articles/143397/ useful link 1]