This is a "plugin" for the Video Disk Recorder (VDR).

Written by                   Carsten Siebholz (c.siebholz AT t-online de>
From 0.0.8 on maintained by  Andreas 'powARman' Regel (andreas.regel AT powarman de)
     T6963 driver by         Andreas 'powARman' Regel (andreas.regel AT powarman de)
     KS0108 driver by        Andreas 'randy' Weinberger (vdr AT smue org)
     SED1520 driver by       Andreas 'randy' Weinberger (vdr AT smue org)
     SED1330 driver by       Roland Praml (praml.roland AT t-online de)
     GU140X32F driver by     Andreas Brachold
     GU256X64-372 driver by  Andreas 'randy' Weinberger (vdr AT smue org)
     Framebuffer driver by   Stephan Skrodzki (skrodzki AT stevekist de)
     serdisplib driver by    Wolfgang Astleitner (mrwastl AT users.sourceforge net)
     Image driver by         Andreas 'powARman' Regel (andreas.regel AT powarman de)
     GU256X64c-3xx0 driver by Ralf Mueller (ralf AT bj-ig de)


Project's homepage:          http://www.powarman.de/
               before 0.0.8: http://c.siebholz.bei.t-online.de/

Latest version available at: http://www.powarman.de/vdr_graphlcd.htm/
               before 0.0.8: http://c.siebholz.bei.t-online.de/


See the file COPYING for license information.



Description:
------------
graphlcd is a plugin to support graphical LC Displays with VDR.
At the moment, these controllers are supported:
  Hitachi HD61830
  Toshiba T6963
  Samsung KS0108
  Epson SED1520 (only tested with DIP122 lcd module)
  Epson SED1330
  Noritake GU140X32F-7806
  Noritake GU256X64-372
  Noritake GU256X64C-3XX0 (serial or parallel)
through serdisplib (see README.serdisplib):
  Optrex 323
  PCD8544-based Nokia displays (found in different monochrome nokia phones)
  Nokia 7110 display (Controller: SED1565)

  Other controllers might be supported in the future...

Additionally graphlcd includes some special drivers:
  framebuffer, for devices that are connected to the VGA connector
  image, for writing image sequences in PBM (Portable Bit Map) format that
    show the plugin's output.


Installation and Configuration:
-------------------------------
1. unpack the tarball to .../VDR/PLUGINS/src directory

2. to compile the plugin, type
   make plugins (from VDR's source directory)
 or
   make all (from the plugin's source directory)

3. copy the 'graphlcd' subdirecory to VDRconfigDir/plugins/
   Afterwards, the structure should look like this:

   VDR Config Directory (eg: /video)
    |
    +- plugins
    |   |
    |   +- graphlcd   (contains logonames.alias)
    |   |   |
    |   |   +-- fonts (contains *.fnt files)
    |   |   |
    .   .   +-- logos (contains *.glcd files)
    .   .

4. start VDR and the plugin.
   You have to specify Your LCD-Controller and probably some
   other options in the command line.
   Possible options are:
     -c CTR,   --contr=CTR    LCD-Controller type
     -p IOP,   --port=IOP     IO port
     -d DEV,   --device=DEV   sets the parport device
     -x SZX,   --sizex=SZX    horizontal size in pixels
     -y SZY,   --sizey=SZY    vertical   size in pixels
     -z Z,     --zoom=Z       double pixel size with Z=1
                              (works only on framebuffer device)

   -c: sets the LCD-Controller. Currently available are:
         hd61830, t6963, ks0108, sed1520, sed1330, sed1330_2, gu140x32f,
         gu256x64-372, gu256x64C-3xx0, framebuffer, image, simlcd
   -p: sets the port address of the parallel port. If this parameter
       is not given, 0x378 is used. To use this direct output, VDR
       has to be started with 'root' user.
   -d: instead of using the direct output via port address (see -p),
       You can use the parport device (/dev/parportX). The advantage
       over the direct output via port address is that this works for
       non-root users also. But it's a little bit slower.
       The modules ppdev.o, parport.o and parport_pc.o must be loaded
       or compiled into the kernel.
   -x: sets the horizontal size of the LCD. If this parameter is not given,
       240 is used.
   -y: sets the vertical size of the LCD. If this parameter is not given,
       128 is used.

   Examples:
     vdr -P 'graphlcd -c hd61830 -p 0x378 -x 240 -y 128'
     vdr -P 'graphlcd -c ks0108 -d /dev/parport0 -x 128 -y 64'


The LCD has to be connected to a parallel Port and the wiring must be
like this:
 (Note: This pin number might differ with other displays)

HD61830
=======
  printerport   LCD          other
  -----------   ----------   ----------
  GND   (18)    GND   (01)   GND          (Ground)
                VDD   (02)   +5V          (V Controller)
                V0    (03)   +5V..-15V    (Contrast)
  INIT  (16)    RS    (04)                (Register Select)
  nLF   (14)    nRW   (05)                (Read/Write)
  nSTRB (01)    EN    (06)                (Enable)
  D0    (02)    D0    (07)                (DataBit0)
  D1    (03)    D1    (08)                (DataBit1)
  D2    (04)    D2    (09)                (DataBit2)
  D3    (05)    D3    (10)                (DataBit3)
  D4    (06)    D4    (11)                (DataBit4)
  D5    (07)    D5    (12)                (DataBit5)
  D6    (08)    D6    (13)                (DataBit6)
  D7    (09)    D7    (14)                (DataBit7)
                nCS   (15)   GND          (Chip Select)
                nRES  (16)   +5V          (Reset)
                VEE   (17)   -12V         (V LCD)
                nDO   (18)                (not connected)



T6963
=====
  printerport   LCD          other
  -----------   ----------   ----------
  GND   (18)    GND   (02)   GND          (Ground)
  nSTRB (01)    WR    (05)                (Write)
  nSEL  (17)    RD    (06)                (Read)
  nLF   (14)    CE    (07)                ()
  INIT  (16)    C/D   (08)                ()
  D0    (02)    D0    (11)                (DataBit0)
  D1    (03)    D1    (12)                (DataBit1)
  D2    (04)    D2    (13)                (DataBit2)
  D3    (05)    D3    (14)                (DataBit3)
  D4    (06)    D4    (15)                (DataBit4)
  D5    (07)    D5    (16)                (DataBit5)
  D6    (08)    D6    (17)                (DataBit6)
  D7    (09)    D7    (18)                (DataBit7)

  Because the T6963 driver reads the status of the display, it *might*
  be neccessary to enable the bidirectional mode in the BIOS and to
  enable bidirectional mode in the Linux kernel:
  <*> Parallel port support
    <*>   PC-style hardware
    [*]   IEEE 1284 transfer modes



  Alternative wiring  (used by some Windows programs):

  printerport   LCD          other
  -----------   ----------   ----------
  GND   (18)    GND   (02)   GND          (Ground)
  INIT  (16)    WR    (05)                (Write)
  nLF   (14)    RD    (06)                (Read)
  nSTRB (01)    CE    (07)                ()
  nSEL  (17)    C/D   (08)                ()
  D0    (02)    D0    (11)                (DataBit0)
  D1    (03)    D1    (12)                (DataBit1)
  D2    (04)    D2    (13)                (DataBit2)
  D3    (05)    D3    (14)                (DataBit3)
  D4    (06)    D4    (15)                (DataBit4)
  D5    (07)    D5    (16)                (DataBit5)
  D6    (08)    D6    (17)                (DataBit6)
  D7    (09)    D7    (18)                (DataBit7)

  Wiring setting can be selected in setup menu.
 
  Note: the LCD must operate in the 6x8 or 8x8 Font mode.
    Usually, there is a pin to choose 6x8 or 8x8 Font mode.

    There are Displays that have a pin to select the number of
    characters per line. In that case, You have to select
    (horiz.Size / 6) or (horiz.Size / 8) characters per line.

    Font mode can be changed in setup menu.


KS0108
======
  printerport   LCD          other
  -----------   ----------   ----------
  GND   (18)    GND   (01)   GND          (Ground)
                Vdd   (02)   +5V
                Vo    (03)                (LCD Contrast In)
  nSEL  (17)    R/S   (04)                (Register Select)
                R/W   (05)   GND          (Read/Write)
  nSTRB (01)    EN    (06)                (Enable)
  D0    (02)    D0    (07)                (DataBit0)
  D1    (03)    D1    (08)                (DataBit1)
  D2    (04)    D2    (09)                (DataBit2)
  D3    (05)    D3    (10)                (DataBit3)
  D4    (06)    D4    (11)                (DataBit4)
  D5    (07)    D5    (12)                (DataBit5)
  D6    (08)    D6    (13)                (DataBit6)
  D7    (09)    D7    (14)                (DataBit7)
  nLF   (14)    CS1   (15)                (ChipSelect Controller 1)
  INIT  (16)    CE2   (16)                (ChipSelect Controller 2)
                RESET (17)   +5V          (Controller Reset)
                Vout  (18)                (Contrast Out)
                LED+  (19)   +4V          (Backlight)
                LED-  (20)   GND          (Backlight GND)



SED1520/DIP122
==============
  printerport   LCD          other
  -----------   ----------   ----------
  GND   (18)    GND   (01)   GND          (Ground)
                Vdd   (02)   +5V
                Vo    (03)                (LCD Contrast In -4V)
  nSEL  (17)    R/S   (04)                (Register Select)
                R/W   (05)   GND          (Read/Write)
  nSTRB (01)    EN1   (06)                (Enable Left)
  D0    (02)    D0    (07)                (DataBit0)
  D1    (03)    D1    (08)                (DataBit1)
  D2    (04)    D2    (09)                (DataBit2)
  D3    (05)    D3    (10)                (DataBit3)
  D4    (06)    D4    (11)                (DataBit4)
  D5    (07)    D5    (12)                (DataBit5)
  D6    (08)    D6    (13)                (DataBit6)
  D7    (09)    D7    (14)                (DataBit7)
  INIT  (16)    EN2   (15)                (Enable Right)
                RESET (16)   +5V          (Controller Reset)
                LED+  (17)   +4V/150mA    (Backlight with 6,4Ohm Resistor to +5V)
  (nLF) (14)    LED-  (18)   GND          (Backlight GND [via BS170])



SED1330
=======
  printerport   LCD          other
  -----------   ----------   ----------
  GND   (18)    GND   (01)   GND          (Ground)
                VDD   (02)   +5V          (V Controller)
                V0    (03)   +5V..-22V    (Contrast)
  INIT  (16)    RS    (04)                (Register Select)
  nLF   (14)    nRW   (05)                (Read/Write)
  nSTRB (01)    EN    (06)                (Enable)
  D0    (02)    D0    (07)                (DataBit0)
  D1    (03)    D1    (08)                (DataBit1)
  D2    (04)    D2    (09)                (DataBit2)
  D3    (05)    D3    (10)                (DataBit3)
  D4    (06)    D4    (11)                (DataBit4)
  D5    (07)    D5    (12)                (DataBit5)
  D6    (08)    D6    (13)                (DataBit6)
  D7    (09)    D7    (14)                (DataBit7)
                nCS   (15)   GND          (Chip Select)
                nRES  (16)   +5V          (Reset)
                VEE   (17)   -22V         (V LCD)
                nDO   (18)                (not connected)


GU140X32F Noritake Dot Graphics VFD Module GU140X32F-7806
=========================================================
  printerport   LCD          other
  -----------   ----------   ----------
  GND   (18)    GND   (01)   GND          (Ground)
                VDD   (02)   +5V          (V Controller ! 350mA)
                NC    (03)                (not connected)
  STRB  (1)     RS    (04)                (Register Select)
  LF    (14)    RW    (05)                (Read/Write)
  INIT  (16)    EN    (06)                (Enable)
  D0    (02)    D0    (07)                (DataBit0)
  D1    (03)    D1    (08)                (DataBit1)
  D2    (04)    D2    (09)                (DataBit2)
  D3    (05)    D3    (10)                (DataBit3)
  D4    (06)    D4    (11)                (DataBit4)
  D5    (07)    D5    (12)                (DataBit5)
  D6    (08)    D6    (13)                (DataBit6)
  D7    (09)    D7    (14)                (DataBit7)


GU256X64-372 Noritake Dot Graphics VFD Module
=========================================================
  printerport        LCD          other
  -----------        ----------   ----------
  D0    (2)          DB0 (15)                        (DataBit 0)
  D1    (3)          DB1 (13)                        (DataBit 1)
  D2    (4)          DB2 (11)                        (DataBit 2)
  D3    (5)          DB3 (09)                        (DataBit 3)
  D4    (6)          DB4 (07)                        (DataBit 4)
  D5    (7)          DB5 (05)                        (DataBit 5)
  D6    (8)          DB6 (03)                        (DataBit 6)
  D7    (9)          DB7 (01)                        (DataBit 7)
  INIT  (16)         nWR (17)                        (Write)
  nSEL  (17)         R/S (19)                        (Register Select, C/D)
  GND   (18)         nRD (21)                        (Read)
  GND   (18)         CSS (23)                        (ChipSelect)
  GND   (18)         GND (02)                        (Ground)

GU256X64C-3xx0 Noritake Dot Graphics VFD Module
=========================================================
  printerport        LCD          other
  -----------        ----------   ----------
  D0    (2)          DB0 (08)                        (DataBit 0)
  D1    (3)          DB1 (07)                        (DataBit 1)
  D2    (4)          DB2 (06)                        (DataBit 2)
  D3    (5)          DB3 (05)                        (DataBit 3)
  D4    (6)          DB4 (04)                        (DataBit 4)
  D5    (7)          DB5 (03)                        (DataBit 5)
  D6    (8)          DB6 (02)                        (DataBit 6)
  D7    (9)          DB7 (01)                        (DataBit 7)
  Ack   (10)         RDY (12)                        (Display Ready)
  INIT  (16)         nWR (10)                        (Write)
  GND   (18)         GND (09)     GND                (Ground)
  GND   (19)         GND (11)     GND                (Ground)
  GND   (20)         GND (13)     GND                (Ground)
  GND   (21)         GND (14)     GND                (Ground)
                     VCC (15)     VCC                (Power supply 5V)
                     VCC (16)     VCC                (Power supply 5V)

GU256X64C-3xx0 Noritake Dot Graphics VFD Module (serial port)
=========================================================
 serialport    LCD          other
 ----------    ----------   ----------
 DCD   (1)      DTR (2)                  
 RxD   (2)      TxD (4)                 
 TxD   (3)      RxD (1)                
 DTR   (4)      DSR (3)               
 GND   (5)      GND (7)     GND         (Ground)
 DSR   (6)      DTR (2) 
                VCC (6)     VCC         (Power supply 5V)
                Test(5)                 (Factory Test - should be open)

Note:
  Serial access (--wiring 2) to GU256X64C-3xx0 is nearly as fast as
  normal parallel access (--wiring 1) but doesn't create the high system
  load of the parallel approach. So for me serial access is preferred over
  normal parallel mode. Even better is the DMA parallel mode
  (--wiring 0 which is default). For DMA mode you have to switch SW6 on the
  display to ON.

=========================================================

To be able to see logos for the channels, You could create a *.glcd file
in the 'logos' directory. This file could be created with the tools/convpic
tool. The size of the image must be 64x48 (for the *_l.glcd files)
or 40x29 (for the *_m.glcd files).
Normally, the plugin looks for a file with the name
CHANNELNAME_SIZE.glcd, where
CHANNELNAME is the name of the channel like in channels.conf and
SIZE is a character depending of the size of the LCD. (l for large LCDs
and m for medium LCDs)
example: ZDF_l.glcd

If a file cannot be found (because the filename does not match exactely the
channelname in channels.conf), the plugin looks into a file logonames.alias
for alternative channel names.



Framebuffer Usage:
------------------
 
Setup is optimized for 640x480x16 framebuffer. To use it, have a kernel with a framebuffer device 
(e.g. vesa fb) and add e.g. vga = 0311 to the kernel start (in lilo.conf).
 
Start graphlcd with graphlcd -c framebuffer -z 1



Setup Parameters:
-----------------

Plugin active:
  This is something like a 'main switch' for the plugin. If it's set to NO,
  the output to the LCD will be suspended.
  (Possible values: 'no', 'yes')

Orientation:
  Rotates the display output by 180 degrees. This might be useful, if the LCD
  is mounted upside-down.
  (Possible values: 'normal', 'upside down')

Display:
  Inverts the display.
  (Possible values: 'Black/White', 'White/Black')

Brightness:
  Sets the brightness of your display's backlight if supported by its driver
  (gu140x32f/gu256x64-372 only).
  (Possible values: 0 <= x <= 100)

Contrast:
  Sets the contrast of your display if supported by its driver (serdisplib
  only)
  (Possible values: 0 <= x <= 10)

Backlight:
  Switches the backlight of your display on and off if supported by its driver
  (serdisplib only)
  (Possible values: 'no', 'yes')

Refresh Display:
  Normally, the plugin does not update the whole display, but only the areas
  that have changed. So it might be, that some faulty pixels would stay a
  longer time. To avoid this, the plugin makes a complete refresh from time to
  time. This parameter defines how often a complete refresh will be done.
  eg: A value of 5 means, that the plugin will make a complete refresh on
      every 5th update.
      A value of 0 completely disables complete refreshs.
  (Possible values: 0 <= x <= 50)

Adjust Timing:
  To get a timing that is as accurate as possible, the plugin measures the
  time for port commands (see: benchmark in syslog). You might decrease or
  increase the time to wait after port commands with this parameter.
  Normally, there is no need to change this parameter.
  (used by hd61830, ks0108, sed1520, sed1330, gu140x32f, gu256x64-372)
  (Possible values: -50 <= x <= 50)

Wait Method:
  Select the method that is used for sleeping.
  Recommended values:
    'nanosleep (sched_rr)', on kernel 2.4 systems
    'gettimeofday', on kernel 2.6 systems
  (Possible values: 'usleep', 'nanosleep', 'nanosleep (sched_rr)', 'gettimeofday')

Wait Prio:
  Select the process priority that is used when sleeping.
  (Possible values: -20 <= x <= 19)

Wiring (T6963):
  Select the type of wiring your display uses.
  (Possible values: 'Standard', 'Windows', 'Feegy')

Font Select (T6963):
  select the font select your display uses.
  (Possible values: '6x8', '8x8')

Auto Mode (T6963):
  Enables/disables the usage of T6963's auto mode which doubles writing speed.
  (Possible values: 'no', 'yes')

Status Check (T6963):
  Enables/disables the usage of T6963's status check. When using a shielded
  cable for connecting your display, the disabling may be possible. This
  results in doubling the speed of reading and writing data to the LCD.
  (Possible values: 'no', 'yes')

Oscillator Frequency:
  Select the oscillator frequency of your display in kHz (sed1330_2 only).
  (Possible values: 1000 <= x <= 15000)

Show Date/Time:
  Enables/disables the date/time bar.
  (Possible values: 'no', 'yes', 'not in menu')

Show Channel:
  Enables/disables the channel bar.
  (Possible values: 'no', 'yes')

Show Logo:
  Enables/disables the channel logo.
  (Possible values: 'no', 'auto', 'medium', 'large')

Show Symbols:
  Enables/disables the symbols for teletext, dolby digital, 2-channel audio,
  encryption and recordings.
  (Possible values: 'no', 'yes', 'compressed')

Show ET Symbols:
  Enables/disables external triggered symbols.
  graphlcd is able to show some symbols, that can be switched on and off by
  external progams (like vbox). Therefore it reads a file
  (/tmp/graphlcd_symbols). The format of this file is very simple: It might
  have one or more lines. Each line triggers one symbol. The format of each
  line is [ASCII-Char][0|1].
  example:
    V1
    X0
  This example enables the symbol 'V' and disables the symbol 'X'. To get an
  idea, why the symbols are represented by those ASCII-Characters, look into
  sym*.fon and sym*.bmp (in ./tools/crtfont/fonts/ directory): You will see,
  that the symbols are nothing more than a special font and each symbol
  stands for a character.
  (Possible values: 'no', 'yes')

Show Program:
  Enables/disables the time, title and subtitle of the current program.
  (Possible values: 'no', 'yes')

Show Timebar:
  Enables/disables the timebar (under the start and end time of the current
  program).
  (Possible values: 'no', 'yes')

Show Menu:
  Enables/disables the menu.
  (Possible values: 'no', 'yes')

Show Messages:
  Enables/disables displaying messages.
  (Possible values: 'no', 'yes')

Show Color Buttons:
  Enables/disables the 4 colered buttons.
  (Possible values: 'no', 'yes')

Show Volume:
  Enables/disables the volume bar.
  (Possible values: 'no', 'yes')

Show free cards:
  enables/disables the display of the free cards as empty rectangles with one
  icon for each card.
  (Possible values: 'no', 'yes')

Identify replay type:
  Based on the replay's name the plugins tries to identify the type of replay,
  e.g. if it is a VDR, DVD or MP3 replay.
  (Possible values: 'no', 'yes')

Modify replay string:
  Enables/disables replay string modification (Identify replay type has to
  be enabled for this). Based on the replay type graphlcd tries to 'improve'
  the replay name string, e.g. extracts and capitalizes DVD titles.
  (Possible values: 'no', 'yes')

Show Logo on Replay:
  Enables/disables the replay-dependent logo (Identify replay type has to
  be enabled for this).
  (Possible values: 'no', 'auto', 'medium', 'large')

Scroll text lines:
  Enables/disables the scrolling of text lines if they don't fit on screen.
  (used by program information and replay text)
  (Possible values: 'never', 'once', 'always')

Scroll speed:
  Sets the scroll speed in pixels per update.
  (Possible values: 1 <= x <= 10)

Scroll time interval:
  Sets the time between scroller updates in milliseconds.
  (Possible values: 100 <= x <= 2000)



Changing Fonts:
---------------
It's very easy to change the fonts that are used by graphlcd.
The plugin uses 4 fonts:
- a large font, that is used for
        the title of the current program and for
        the title of the recording (during replay).
- a normal font, that is used for
        the date/time bar,
        the channel bar,
        the starttime, endtime and the subtitle of the current program,
        the times in the replay screen,
        the title and the items in the menus,
        the popup-messages and for
        the text items like the content of a recording.
- a small font, that is only used for the text of the 4 colored buttons.
- a symbol font, that contains the symbols.

Because smaller displays should use smaller fonts, the displays will be
classified in 3 categories. Each category should have all 4 fonts.
The name of the font files depend on the category and on the font:
  small displays  ( vertical size < 64 ):
    f_s_l.fnt  : large font
    f_s_n.fnt  : normal font
    f_s_s.fnt  : small font
    f_s_sym.fnt: symbols
  medium displays ( vertical size 64..127 ):
    f_m_l.fnt  : large font
    f_m_n.fnt  : normal font
    f_m_s.fnt  : small font
    f_m_sym.fnt: symbols
  large displays  ( vertical size >= 128 ):
    f_l_l.fnt  : large font
    f_l_n.fnt  : normal font
    f_l_s.fnt  : small font
    f_l_sym.fnt: symbols

To change the fonts you only have to change the related symbolic link to
another font file.
If you use another already existing font or if you want to create a new one by
yourself does not matter. If you want to create a new one or if you want to
modify an existing font, look into ./tools/crtfont and read the README.



Known Problems:
---------------
- The plugin displays the Replay screen when the pause mode in vdr is
  active. I'll look for a nice and clean solution for this...

