1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README.txt Sun Nov 24 21:31:11 2013 +0000
1.3 @@ -0,0 +1,192 @@
1.4 +Introduction
1.5 +------------
1.6 +
1.7 +The ben-pcf8833 distribution provides some programs that run on the Ben
1.8 +NanoNote to control a "Nokia 6100" LCD using the Nuelectronics "Color LCD &
1.9 +Joystick Shield". To connect the shield to the Ben, the 8:10 port which is
1.10 +typically employed to access microSD cards is instead used to hold a suitable
1.11 +breakout board that exposes the 8:10 port's connectors to other circuits.
1.12 +These connectors are in turn connected to specific connectors on the shield
1.13 +via some level shifter components as follows:
1.14 +
1.15 +Sniffer UBB Shifters Shield
1.16 +------- ---- ---------- ------
1.17 +DAT2 DAT2 A1 (#2) B1 8 (BACKLIGHT)
1.18 +CD DAT3 A2 (#1) B2 10 (SS/CS)
1.19 +CMD CMD A1 (#1) B1 9 (RESET)
1.20 +VCC VDD LV HV VIN
1.21 +CLK CLK A4 (#1) B4 13 (SCLK/CLK)
1.22 +GND GND GND GND GND
1.23 +DAT0 DAT0 A3 (#1) B3 11 (MOSI/SEND)
1.24 +DAT1 DAT1
1.25 +
1.26 +Here, two level shifters are used and are labelled #1 and #2 above. The
1.27 +VCC/VDD and GND connections from the Ben are connected to the LV and GND
1.28 +connections respectively on the level shifters.
1.29 +
1.30 +In addition to the Sniffer or UBB connections, additional connections for 5V
1.31 +power and ground must be connected as follows:
1.32 +
1.33 +5V Supply Shifters
1.34 +----------- ----------
1.35 +5V HV
1.36 +GND GND
1.37 +
1.38 +The 5V output of an Arduino Duemilanove board was successfully used, as it
1.39 +normally would be with the shield, but any regulated 5V supply should be
1.40 +suitable.
1.41 +
1.42 +Collecting Images for Display
1.43 +-----------------------------
1.44 +
1.45 +Before building the bitmap program, some images with the following specific
1.46 +properties are required:
1.47 +
1.48 +Width: 132 pixels
1.49 +Height: 132 pixels
1.50 +
1.51 +To save you the effort of finding suitable images, some example files are
1.52 +included in this software distribution.
1.53 +
1.54 +An image preparation program then needs to be run on a list of image filenames
1.55 +to produce suitable source files that can be incorporated into the built
1.56 +program. This program should be run automatically when building, meaning that
1.57 +you can skip forward to the "Building the Software" section, but to use other
1.58 +images or to customise the software you will need to consult the following
1.59 +instructions.
1.60 +
1.61 +The image preparation program can be found in the tools directory and is
1.62 +called bitmap.py. This program is written in Python and needs the Python
1.63 +Imaging Library, available in Debian as the python-imaging package and in
1.64 +other GNU/Linux distributions under other names. It is also available from the
1.65 +following location:
1.66 +
1.67 +https://pypi.python.org/pypi/PIL
1.68 +
1.69 +Images are prepared for the program as follows (and this is normally done by
1.70 +the Makefile automatically):
1.71 +
1.72 +python tools/bitmap.py bitmaps examples/*.JPG
1.73 +
1.74 +Here, two JPEG files will be loaded, internally converted (the files are not
1.75 +changed), and the bitmap data written out to two files:
1.76 +
1.77 +bitmaps.c
1.78 +bitmaps.h
1.79 +
1.80 +Since the Makefile and bitmap program reference these files, it is recommended
1.81 +that the "bitmaps" basename be retained when running the bitmap.py program.
1.82 +
1.83 +The bitmap.py program also supports other common image formats such as PNG.
1.84 +
1.85 +Building the Software
1.86 +---------------------
1.87 +
1.88 +Before building the software, it will probably be necessary to edit the
1.89 +Makefile to specify the locations of the cross-compilation toolchain and of
1.90 +libubb. Obtaining a toolchain and libubb is currently beyond the scope of this
1.91 +document.
1.92 +
1.93 +The programs are built as follows:
1.94 +
1.95 +make
1.96 +
1.97 +Running the Software
1.98 +--------------------
1.99 +
1.100 +On the Ben, the programs can be deployed together with libubb in a particular
1.101 +directory and invoked as follows:
1.102 +
1.103 +LD_LIBRARY_PATH=. ./spin
1.104 +LD_LIBRARY_PATH=. ./bitmap
1.105 +
1.106 +Alternatively, the library search path can be configured properly and the
1.107 +programs installed in such a way that merely typing the name of the programs
1.108 +is enough to run them.
1.109 +
1.110 +Hardware: Color LCD & Joystick Shield
1.111 +-------------------------------------
1.112 +
1.113 +This board provides a "Nokia 6100" display and a joystick (currently unused):
1.114 +
1.115 +http://shieldlist.org/nuelectronics/colorlcd-joystick
1.116 +
1.117 +Nuelectronics do not seem to exist any more, but a similar product is
1.118 +documented on the Sparkfun site:
1.119 +
1.120 +https://www.sparkfun.com/products/9363
1.121 +
1.122 +A more appropriate board for the Ben might be the following:
1.123 +
1.124 +https://www.sparkfun.com/products/11062
1.125 +
1.126 +Since it runs at 3.3V, it would probably be possible to use this particular
1.127 +board directly with the Ben, leaving out the level shifters/converters
1.128 +entirely.
1.129 +
1.130 +Note that with all boards providing LCD panels, careful inspection and/or
1.131 +research is necessary to determine which display controller is actually being
1.132 +used. Annoyingly, product descriptions tend to omit such information.
1.133 +
1.134 +Hardware: 4-channel I2C-safe Bi-directional Logic Level Converter - BSS138
1.135 +--------------------------------------------------------------------------
1.136 +
1.137 +Since the Arduino shield described above operates at 5V whereas the Ben
1.138 +operates at 3.3V, some level shifters are required. The following product was
1.139 +used for such purposes:
1.140 +
1.141 +https://www.adafruit.com/products/757
1.142 +
1.143 +Since five signal lines are required for the communication, two such level
1.144 +shifters are needed (two multiplied by four lines). There are other products
1.145 +providing more lines, but when choosing a replacement it is important to check
1.146 +that SPI usage and that 3.3V inputs and 5V outputs can be supported. The above
1.147 +product supports SPI and I2C communication as well as bidirectional
1.148 +conversion.
1.149 +
1.150 +Hardware: 8:10 Port Breakout Board
1.151 +----------------------------------
1.152 +
1.153 +To connect the Ben NanoNote to the E-Paper Display module, a suitable breakout
1.154 +board is required to expose the connections inside the 8:10 slot. To achieve
1.155 +this, the Sparkfun microSD Sniffer has been used:
1.156 +
1.157 +https://www.sparkfun.com/products/9419
1.158 +
1.159 +This board is apparently intended for eavesdropping on communications between
1.160 +a "host" device with a microSD slot and a microSD-based device that can be
1.161 +inserted into a slot mounted on the board (instead of being inserted directly
1.162 +into the host device). However, the board-mounted slot can be ignored and the
1.163 +exposed connections routed to the display board instead.
1.164 +
1.165 +Another board that achieves the same purpose is the Universal Breakout Board
1.166 +(UBB):
1.167 +
1.168 +http://en.qi-hardware.com/wiki/UBB
1.169 +
1.170 +The UBB is somewhat more difficult to work with as its connectors are very
1.171 +small and, compared to the microSD Sniffer, awkward to attach things to. The
1.172 +microSD Sniffer employs connectors situated around holes with 0.1 inch
1.173 +spacing, meaning that commonly available connection headers can be soldered
1.174 +onto the board.
1.175 +
1.176 +Although the labelling of the connections is different between the microSD
1.177 +Sniffer and UBB (see above), the layout appears to be identical.
1.178 +
1.179 +Contact, Copyright and Licence Information
1.180 +------------------------------------------
1.181 +
1.182 +The author can be contacted at the following e-mail address:
1.183 +
1.184 +paul@boddie.org.uk
1.185 +
1.186 +Copyright and licence information can be found in the docs directory - see
1.187 +docs/COPYING.txt and docs/LICENCE.txt for more information.
1.188 +
1.189 +Much of the effort in understanding and documenting the PCF8833 controller was
1.190 +done by James P. Lynch and is described in the following document:
1.191 +
1.192 +http://www.sparkfun.com/tutorial/Nokia%206100%20LCD%20Display%20Driver.pdf
1.193 +
1.194 +It appears that most subsequent efforts have drawn from this work, and thanks
1.195 +are therefore due to the author for his generosity in sharing his findings.