README

EPD
===

EPD is a linux kernel subsystem for controlling epaper displays.

For now, only Pervasive Display's COG G1 (based on EM027AS012) epaper display
is supported. A COG G2 (based on EM027AS013) device support will certainly be
added later on.

This subsystem is separated in two parts, the epaper controller (core.c) and the
epaper device drivers (e.g. epd_g1.c). The controller manages the userland
interface and manipulates the registered device driver, but remain hardware
agnostic.

Build
-----
Simply run "make" if compiling module on the target.

If you want to cross compile the module you can use:
make ARCH=<arch> CROSS_COMPILE=<cross_tuple> KERNDIR=<kernel_dir>

Where arch is the architecture of the target (e.g. arm) cross_tuple is the cross
compiler prefix (e.g. arm-unknow-linux-gnueabi-) and kernel_dir a path to the
kernel compiled for the target.

To have debug printks you can run make with "DEBUG=1". /!\ This is very verbose
for frame update.

Use it
------
Two modules are created in build/epd/. epd-therm.ko which handles on board i2c
temperature sensor, epd.ko is the epaper controller and epd-g1.ko is the COG
G1 device driver.

First load the platform spi, pwm and i2c drivers. Then the controller ("insmod
epd.ko"), then epd-therm.ko and finally the screen device driver epd-g1.ko.

If everything went well, two char device nodes has been created in /dev
(usually /dev/epdctl and /dev/epd0).

- /dev/epd0:
This is the epaper display framebuffer, it olds the image to be displayed for
screen id 0. When updating frame, write a xbm binary formatted image in it.

- /dev/epdctl:
This is the epaper controling file. It understands the following commands:
	- 'C<id>': clears the screen with id <id> into a blank one
	- 'B<id>': makes the screen with id <id> all black
	- 'W<id>': display the current image in framebuffer onto the screen with
	  id <id>

So basically updating a new image for first screen would need:
1) "cat /tmp/image >> /dev/epd0"
2) "echo -n "W0" >> /dev/epdctl"

RaspberryPI
-----------
This driver has been tested on a RPI-B booting a vanilla/mainline kernel. The
rpi device tree from this kernel has been modified to get this working. The
patch found in rpi/rpi-mainline.patch can be used. Moreover the kernel needs
the incoming pwm clock support that can be found in this patchset
(https://lkml.org/lkml/2015/12/6/74). Kernel from 4.5 have these patches .

This driver can also work with a linux kernel from rpi tree. A devicetree
overlay for this kernel can be built with "make rpi-devicetree". If your
kernel is older than 4.5.x you have to build a small userland program that will
set the pwm configuration register to correct values. This program can be built
with make "rpi-pwmconf". Then the following commands can be entered:

./pwmconf # Only if your kernel is older than 4.5.x
modprobe spi-bcm2835
modprobe i2c-bcm2708
modprobe pwm-bcm2835
insmod epd.ko
insmod epd-therm.ko
insmod epd-g1.ko

If you use a COG from Embedded Artist and the devicetree is used with
rpi-mainline.patch or the overlay has not been modified the pin connection is
as the following :

      RPI                  COG1
    +-------+
 1  | .   . | 2          +-------+
 3  | .   . | 4       1  | .   . | 2
 5  | .   . | 6       3  | .   . | 4
 7  | .   . | 8       5  | .   . | 6
 9  | .   . | 10      7  | .   . | 8
 11 | .   . | 12      9  | .   . | 10
 13 | .   . | 14      11 | .   . | 12
 15 | .   . | 16      13 | .   . | 14
 17 | .   . | 18         +-------+
 19 | .   . | 20
 21 | .   . | 22
 23 | .   . | 24
 25 | .   . | 26
 27 | .   . | 28
 29 | .   . | 30
 31 | .   . | 32
 33 | .   . | 34
 35 | .   . | 36
 37 | .   . | 38
 39 | .   . | 40
    +-------+

 +----------------+-----------+------------+
 |   Function     |  RPI pin  |  COG pin   |
 +----------------+-----------+------------+
 |     SDA        |      3    |     10     |
 |     SCL        |      5    |      9     |
 |    Border      |      8    |      8     |
 |     Busy       |     11    |      7     |
 |     PWM        |     12    |     11     |
 |   Panel On     |     15    |     13     |
 |   Discharge    |     16    |     14     |
 |     3v3        |     17    |      2     |
 |     Reset      |     18    |     12     |
 |     MOSI       |     19    |      4     |
 |     MISO       |     21    |      5     |
 |     SCLK       |     23    |      3     |
 |     SSEL       |     24    |      6     |
 |     GND        |     25    |      1     |
 +----------------+-----------+------------+


Quick test
----------
A quick test script can be found in test/epd-test.sh which can be used as
below:
./epd-test.sh [-c | -b | -w <image.xbm>]

	- "./epd-test.sh -c" cleans the screen into a blank one
	- "./epd-test.sh -b" cleans the screen into a full black one
	- "./epd-test.sh -w <image.xbm>" displays the ascii xbm formatted image
	  found in <image.xbm> (you can use something like gimp to generate such
	  images)

This script uses xxd, which comes with vim, in order to transform xbm ascii
images into xbm binary format.