====== How to write new display drivers ======

Writing a new driver for lcd4linux is quite easy, if you follow these steps:

  * **Get the SVN (Subversion) version**: This is very important, because it makes it much easier for us to commit your changes into the official code. If you need help with SVN, look at the SVN section at the [[:Download|Download]] page.
  * There's no need to keep two seperate directories (one with the original, one with your modifications): SVN does this job for you.
  * **Always** do a //svn up// before editing, to ensure you're working on current code.
  * use **drv_Sample.c** as a template but **do not** simply copy it, but let subversion do the job: 
 <code>
 svn cp drv_Sample.c drv_<yourname>.c
 </code>

  * edit //drv_<yourname>.c//
    * add a short **description** what this driver is for
    * add your **copyright notice** (important: your name and email)
    * **Please** do not modify the GPL part! (Yes, you have to put your code under GPL, otherwise I'll refuse your patch)
    * do some **documentation** (I know that //real programmers write programs, not documentation//, but...)
    * change the line //static char Name[] = "Sample";// to your driver's name
    * the next steps depend on wheter your display uses text or graphic mode:
    * **text mode**:
      * remove //#include "drv_generic_graphic.h"//
      * remove the whole //drv_Sample_blit// function
      * remove the //drv_Sample_start2//, //drv_Sample_init2// and //drv_Sample_quit2// functions
      * remove the //DRIVER drv_Sample2// declaration at the very bottom
    * **graphic mode**:
      * remove //#include "drv_generic_text.h"//
      * remove the //drv_Sample_clear//, //drv_Sample_write// and //drv_Sample_defchar// functions
      * remove the //drv_Sample_start//, //drv_Sample_init// and //drv_Sample_quit// functions
      * rename the //drv_Sample_start2//, //drv_Sample_init2// and //drv_Sample_quit2// functions and remove the //2//
      * remove the //DRIVER drv_Sample2// declaration at the very bottom
    * if your drisplay doesn't have any GPO's, remove all //gpo// and //gpio// stuff
    * quit editing at this point and continue with next step
  * edit //drv.c//, add declarations and definitions for your driver (just search for //Sample//, copy&paste the corresponding areas, but try to keep them in alphabetical order):
<code>
extern DRIVER drv_Sample;

#ifdef WITH_SAMPLE
    &drv_Sample,
#endif
</code>

  * edit //Makefile.am// and add your //drv_*.c// to EXTRA_lcd4linux_SOURCES (again, copy&paste the //drv_Sample// areas, take care for alphabetical order)
  * edit //drivers.m4// and copy&paste all //Sample// and //SAMPLE// areas (alphabetical order, please). Here you have to decide which generic drivers your display wants to use:
<code>
if test "$SAMPLE" = "yes"; then
   # select either text or graphics mode
   TEXT="yes"
   GRAPHIC="yes"
   # support for GPIO's
   GPIO="yes"
   # select bus: serial (including USB), parallel or i2c
   SERIAL="yes"
   PARPORT="yes"
   #I2C="yes"
   DRIVERS="$DRIVERS drv_Sample.o"
   AC_DEFINE(WITH_SAMPLE,1,[[:Sample|driver]])
fi
</code>

 If your display uses text mode only, remove the //GRAPHIC="yes"// line. If it's a graphic one, remove //TEXT="yes"//. If you don't have GPO's, remove the //GPO="yes"//. Same goes for serial or parallel port. Do not use I2C unless you've been talking to us and you know what you're doing. If your display uses USB, it's either a serial one (using /dev/usb/tts/0 or /dev/tts/USB0 or something), so use the serial subsystem. If it's a //real// USB display, you want to use libusb, which makes things a bit more complex. Please [[:mailto:lcd4linux-devel@lists.sourceforge.net|drop us an email]] in this case...

  * run //./bootstrap//, //./configure// and //make//
  * test if everything compiles and links fine. Now you should have set up the framework for your new display driver!
  * edit drv_YourName.c again and fill it with life:
    * **text mode**:
      * //drv_Sample_clear//: send a command to the display which clears it
      * //drv_Sample_write//: do cursor positioning and send a string to the display (don't mind about double buffering, the generic text subsystem will take care of)
      * //drv_Sample_defchar//: define the bitmap of a user-defined char (used for bars & icons)     
    * **graphic mode**:
      * //drv_Sample_blit//: transfer the framebuffer managed by the generic graphic subsystem to the display. That's all what's up to you!
      * //drv_Sample_GPO//: set GPO's
      * //drv_Sample_start//: maybe read some things from the config file, and initialize display
      * //drv_Sample_init//: read things from config (e.g. display size), set some necessary global variables, and initialize the driver 
      * if your display supports some special features (like contrast, backlight, brightness, ...) implement it as //plugins//. See //plugin_contrast// for an example.
      * if there are none, remove all the //contrast// stuff
      * As your display is either serial or parallel one, you have to adopt these parts, too. Serial (and USB) displays are very easy to handle (there is a drv_generic_serial_send() function which does all the low-level communication). Parallel port displays are a bit tricky, because you have to do all the bit-banging by hand. I tried to provide some very basic functionality in the sample driver (which will surely **not** work on any display!), and I hope you get the idea...
  * test it with your display
  * run //./indent.sh// to apply coding style (this does source code formatting)
  * send us a patch:
    * run //svn diff >your_patch.diff// and send us the file
    * run //svn commit -m "<your log message>"// if you have SVN developer access and '''you know what you're doing'''
  * **Please** add documentation to the wiki!!!

It's easy, believe me!

----