SERDISPLIB
==========

Written by                  Wolfgang Astleitner (mrwastl@users.sourceforge.net)

Project's homepage:         http://serdisplib.soureforge.net
Latest version available:   http://sourceforge.net/projects/serdisplib/


See the file COPYING for license information.


DISCLAIMER
----------
THIS IS EXPERIMENTAL SOFTWARE AND HARDWARE. USE AT YOUR OWN RISK.
THE DEVELOPER(S) OF THIS SOFTWARE AND HARDWARE CAN NOT BE HELD LIABLE UNDER ANY CIRCUMSTANCES FOR 
DAMAGE TO HARDWARE OR SOFTWARE, LOST DATA, OR OTHER DIRECT OR INDIRECT DAMAGE RESULTING FROM THE 
USE OF THIS SOFTWARE OR HARDWARE. IF YOU DO NOT AGREE TO THESE CONDITIONS, YOU ARE NOT PERMITTED 
TO USE OR FURTHER DISTRIBUTE THIS SOFTWARE OR TO USE ANY TEMPLATES FOR BUILDING HARDWARE PRESENTED HERE.


HISTORY
-------
see separate file 'HISTORY'


DESCRIPTION
-----------
This is a library with support for certain serial and parallel lc-displays connected 
to the parallel port (and also serial port with i2c-displays).


Supported displays / controllers
--------------------------------
--> look at http://serdisplib.sourceforge.net/index.html#displays


IOCTL vs. DIRECT-IO
-------------------
The default output-method uses 'ioctl'-calls using device names (eg: /dev/parport0).
serdisplib also supports using direct-IO (using port-addresses).
direct-IO is only available on architectures supporting it.

ioctl:
  +  not restricted to root-only (users qualified for eg. /dev/parport0 may control a display connected to it)
  +  universal (usable with more unix-derivats)
  -  slower than direct-IO

direct-IO:
  +  faster
  -  root-only
  -  i386-compliant architectures only (*bsd-support planned)



INSTALLATION AND CONFIGURATION
------------------------------

NOTA BENE: on some systems you'll have to use 'gmake' instead of 'make'


1.  unpack the tarball to some directory

2a. enter ./configure to generate Makefiles

   or if you use a RedHat/Fedora-based/compliant linux-distribution:
   
2b. enter rpmbuild -tb serdisplib-<version>.tar.gz to generate three RPMs:
    serdisplib-<version>.<arch>.rpm         ... library files
    serdisplib-devel-<version>.<arch>.rpm   ... header files and static library
    serdisplib-tools-<version>.<arch>.rpm   ... tools (testserdisp, multidisplay)

    eg.: rpmbuild -tb serdisplib-1.96.tar.gz   on an x86-arch will generate:
    
    * serdisplib-1.96.i386.rpm, serdisplib-devel-1.96.i386.rpm, serdisplib-tools-1.96.i386.rpm
    
    
    RPM-install these files and you're done with installing serdisplib

    
    ATTENTION: if you have installed a pre-RPM-version of serdisplib, 
               uninstall/remove that before installing the RPM-version!
               (/usr/local (make install) vs. /usr (RPM-install) problem!)


3.  to build the library and the tools, enter:

    make

4.  to install the library and the tools:

    make install

    this will install the shared and static library into /usr/local/lib/
    and the include-files 'serdisp_control.h' and 'serdisp_parport.h' to /usr/local/include/serdisplib
    tools (only 'testserdisp' and 'multidisplay' for now) will be installed into /usr/local/bin

    if you want different paths, set DRIVERLIB_PATH and/or DRIVERINCLUDE_PATH at the beginning of the Makefile
    eg:
    DRIVERLIB_PATH=/opt/serdisplib/lib/
    DRIVERINCLUDE_PATH=/opt/serdisplib/include
    DRIVERBIN_PATH=/opt/serdisplib/bin
    
    or simply
    INSTALL_PATH=/opt/serdisplib (DRIVERLIB_PATH, DRIVERINCLUDE_PATH, DRIVERBIN_PATH will be set relative to it)

    ('serdisplib' will always be appended to DRIVERINCLUDE_PATH)



Annotations:
------------
* multidisplay requires libgd. if libgd is not installed, autoconf (./configure) will not include multidisplay

* GIF-support is included in recent versions of libgd only!
  autoconf (./configure) will automatically detect missing GIF-support and disable GIF-specific code-segments

* solaris 10:
  autoconf should manage to find most of the binaries / required libraries.
  if not so, adapt 'configure.in' and run 'autoconf'



DISPLAY NAME STRINGS SUPPORTED (case insensitive)
-------------------------------------------------

name          aliases           description
------------- ----------------- -------------------------------------------------
OPTREX323                       optrex 323 displays
PCD8544                         displays with on-glass controller pcd8544
LPH7366                         pcd8544-based displays with backlight
LPH7690                         96x60, pcd8544-compliant command set
NOKIA7110     SED1565           nokia 7110 displays
ERICSSONT2X   E///T2X           ericsson t2x displays
LSU7S1011A    ALPS              ALPS LSU7S1011A
T6963                           generic for displays with Toshiba T6963 controller
TLX1391                         display Toshiba TLX1391 (128x128, T6963 controller)
SED133X       SED1330, SED1335  generic for displays with SED1330/SED1335 controller
NEC21A        SKYPER            nec21a pager (skyper) display module
LPH7508                         LPH7508 display module with display module kit by pollin
HP12542R                        Hyundai HP12542R display module with display module kit by pollin
N3510I        N3530             driver for Nokia 3510i/3530 displays (S1D15G14-based)


TESTING
-------
serdisplib contains a test program called 'testserdisp'. (it is automatically built if you compiled serdisplib
using 'make', 'make all', or 'make testserdisp')


at the prompt enter: 'testserdisp -h

this will show all options supported by testserdisp.

at least -n <display name> is needed (supported display names: look at table above)

testserdisp will show a test picture and you get a prompt. enter 'help' to see all test commands available.


information:
it is not required to install serdisplib prior to be able to use testserdisp. 
just enter 'src/testserdisp' instead of 'testserdisp' at the prompt where you compiled the library.



MULTIDISPLAY
------------
multidisplay is a tool for displaying pictures and text (and even both combined).

at the prompt enter: 'multidisplay -h' for help

examples:
  display an image:          multidisplay -n nokia7110 -f pic.jpg
  display some text:         multidisplay -n sed1330 -o "WIRING=1" -M 'serdisplib is the win'
  use a different font:      multidisplay -n sed1330 -o "WIRING=1" -F tiny -M 'tiny font'
  use truetypefont, size 16: multidisplay -n nokia7110 -F font.ttf:16 -M 'test'

  NOTA BENE:  
  option -c (executing a command and display result) is dangerous and should be handled with care
  for security concerns, -c is only executed when combined with -y
  
  example:
    display load average:    multidisplay -n sed1330 -c "uptime |sed -e 's/.*load.average..//'" -y

there will be a separate documentation for multidisplay in a later release.
for now, multidisplay is a tiny tool to play around with


information:
it is not required to install serdisplib prior to be able to use multidisplay. 
just enter 'tools/multidisplay' instead of 'multidisplay' at the prompt where you compiled the library.

multidisplay will only be compiled if libgd is installed (at least libgd version 2)



API-DOCUMENTATION
-----------------
--> doc/docs/index.html 
or
--> look at http://serdisplib.sourceforge.net/docs/index.html



OPTIONS AND WIRING
------------------
--> look at http://serdisplib.sourceforge.net/docs/options.html



VDR-GRAPHLCD SUPPORT
--------------------
since graphlcd 0.1.2-pre5 graphlcd uses serdisplib if installed. user action (make-flags, includes, ...) is no longer needed
graphlcd needs no longer be recompiled for using serdisplib!!

also have a look at  docs/DRIVER.serdisp included in graphlcd-base



KNOWN PROBLEMS
--------------
 - serial port damn slow on solaris and when using USB->RS232 adapters.

please mail to my address if you find bugs!



TODO
----
* better documentation
* more comments in source code

* more displays/controllers


PLANNED DISPLAYS (or: 'display queue')
----------------
* Palm PDAs (via RS232)
* Nokia 128x128 colour displays
* KS0108-based displays
* Ericsson R520
* Ericsson R320
...



CONTRIBUTORS (alphabetically sorted)
------------
* daniel badberg ... testing, bug reports
* reuben bond    ... testing, bug reports, chardisp (generate text using serdisplib. to be released)
* alan carvalho  ... bug report in makefile
* andreas regel  ... testing of t6963c-driver

and all others who helped me with different questions (c, electronics, proof-reading, ...), especially:
* andreas fierlinger
* michael fuereder

this list is not up-to-date and will be reworked/extended in a later release of serdisplib.

Have fun!

Wolfgang Astleitner <mrwastl@users.sourceforge.net>
