lcdproc/docs/lcdproc-dev/driver-api.docbook

<chapter id="driver-api">
  <title>The LCDproc driver API</title>
  
<para>
  This chapter describes the driver API of v0.5 of LCDproc.
  At time of this writing, this version is not released and some things might
  be changed.
</para>

<para>
  The API consists of several functions to tell the driver that
  certains actions should be performed, some data, and several functions
  to retrieve configuration data from the server.
</para>

<sect1 id="api-overview">
  <title>OVERVIEW OF OPERATION</title>

<para>
  The API is best descibed by starting with the struct lcd_logical_driver
  which is defined in server/drivers/lcd.h.
</para>

<para>
  The use of the API has changed from v0.4 to v0.5. The default functions that
  the server put in the pointers in v0.4 do no longer exist. Instead empty
  functions are the default. If a driver implements a function, the function
  will be detected by the server. The driver should at least implement all
  basic functions like driver_chr and driver_str itself, and should also have
  defined a number of other symbols for the server.
</para>

<para>
  I will walk through the driver struct here.
</para>

<screen>
typedef struct lcd_logical_driver {

	//////// Variables in the driver module
	// The driver loader will look for symbols with these names !
	char *api_version;
	int *stay_in_foreground;	// Does this driver require to be in foreground ?
	int *does_input;	// Does this driver do output ?
	int *does_output;	// Does this driver do output ?

  The programmer should define the following symbols:

char * api_version = API_VERSION;  // &lt;-- this symbol is defined by make
int stay_in_foreground = 0; // This driver does not need to be in foreground
int does_input = 0;	    // This driver does not do input
int does_output = 1;	    // But only output

  And fill these values with the correct values. Upon loading the driver module,
  the server will locate these symbols and store pointers to them in the
  driver struct.

  Because the drivers are loadable, some kind of version checking should be
  done. Therefor the server expects the correct version number to be found in
  the api_version symbol (a string). For the v0.5 version this should be "0.5".
  If the version is incompatible, the driver will not be loaded. The current
  API version can always be determined by inserting the compiler define
  API_VERSION in the code.

	///// Functions in the driver module
	// Basic functions
 	// All these Basic functions should be implemented !
	int (*init)		(drvthis);
	void (*close)		(drvthis);
	int (*width)		(drvthis);
	int (*height)		(drvthis);
	void (*clear)		(drvthis);
	void (*flush)		(drvthis);
	void (*string)		(drvthis, int x, int y, char *str);
	void (*chr)		(drvthis, int x, int y, char c);

	// Extended functions
	void (*vbar)		(drvthis, int x, int y, int len, int promille, int options);
	void (*hbar)		(drvthis, int x, int y, int len, int promille, int options);

  These functions have been extended since v0.4. They now now expext complete
  coordinates, a length (in chars, not pixels!) a promillage (0 to 1000) and an
  option.

	void (*num)		(drvthis, int x, int num);

  Draw big numbers on your display. Only 6 positions exist, 1 to 6.
  David GLAUDE:
    "I don't think this is valid... There are as many position as wanted.
    A BigNum could be at any column from 1 to end of the LCD.
    It could also be at -1 and -2 (where only the end is visible).
    Optionaly it could be on a specific raw from -3 to end of the LCD.
    This permit scrolling of BIGNUM or in the futur BIGFONT."

	void (*heartbeat)	(drvthis, int state);

  Should be called to animate the heartbeat. The driver should therefore
  probably call the icon function below.

	void (*icon)		(drvthis, int x, int y, int icon);

  Tells to place a certain icon at a position.


	// Userdef character functions

	void (*set_char)	(drvthis, char ch, char *dat)
	int (*get_free_chars)	(drvthis)
	int (*cellwidth)	(drvthis)
	int (*cellheight)	(drvthis)

  Functions to define a character. It is currently unclear how this system
  should exactly work. The set_char function expects a simple block of data
  with 1 byte for each pixel-line. So that is 8 bytes for a 5x8 char.

	// Hardware functions
	int (*contrast)		(drvthis, int contrast);
	void (*backlight)	(drvthis, int on);
	void (*output)		(drvthis, int on);

	// Key functions
	const char *(*get_key)	(drvthis);

  Returns a string. This string is withing driver's memory space and the server
  should therefor never try to modify this string.

	char *(*get_info)	(drvthis);

  Returns a string describing the driver and it's features.

	//////// Variables in server core available for drivers

	char * name;		// Name of this driver.
	void * private_data;

These variables should be taken read-only for the drivers. The name variable
should be used to access the driver's own section in the config file.
The private_data pointer is the pointer to the driver's own data block. This
pointer should be stored using the store_private_ptr function below. The
driver should cast this to it's own private structure pointer.


	//////// Functions in server core available for drivers

	int (*store_private_ptr) (struct lcd_logical_driver * driver, void * private_data);

Store the driver's private data:


	// Config file functions, filled by server
	char (*config_get_bool)	(char * sectionname, char * keyname,
				int skip, char default_value);
	int (*config_get_int)	(char * sectionname, char * keyname,
				int skip, int default_value);
	double (*config_get_float) (char * sectionname, char * keyname,
				int skip, double default_value);
	char *(*config_get_string) (char * sectionname, char * keyname,
				int skip, char * default_value);
				// Returns a string in server memory space.
				// Copy this string.
	int config_has_section	(char *sectionname);
	int config_has_key	(char *sectionname, char *keyname);

See configfile.h on how to use these functions. As sectionname, always use the
driver name: drvthis->name


	// Reporting function
	void (*report)			( const int level, const char *format, .../*args*/ );

Easily usable report functions by including drivers/report.h. See that file
for details.


	// Display properties functions (for drivers that adapt to other loaded drivers)
	int (*get_display_width) ();
	int (*get_display_height) ();

If you have a driver that can adapt its size to the size of an other driver,
it should read these values. If there is no other driver loaded yet, the
returned values will be 0.


	// Driver private data
	void * private_data;	// Filled by server by calling store_private_ptr()

} Driver;

The flush_box and draw_frame functions have been removed for v0.5.
</screen>

</sect1>

<sect1 id="private-data">
  <title>PRIVATE DATA</title>

<para>
  With the introduction of loadable modules it is necesary to stop using global
  variables to store a driver's data in. Instead, you should store it in a
  structure, that you allocate abd store on driver's init. If you don't use
  this system, but use globals, you get queer results if you run two LCDd
  daemons on one machine. They will then use the same variables !
</para>

<para>
  In the driver's private structure will probably at least be something like:
</para>

<screen>
typedef struct my_driver_private {

        // Size in cells of the LCD
        int width, height;
        // Size of each LCD cell, in pixels
        int cellwidth, cellheight;
        // Frame buffer...
        char *framebuf;
} PrivateData;
</screen>

<para>
  You allocate and store this structure like this:
</para>

<screen>
	PrivateData * p;

	// Allocate and store private data
	p = (PrivateData *) malloc( sizeof(PrivateData) );
	if( p == NULL )
		return -1;
	if( drvthis->store_private_ptr( drvthis, p ) &lt; 0 )
		return -1;

	(... continue with the rest of your init routine)
</screen>

<para>
  You retrieve this private data pointer by adding the following code to the
  beginning of your functions:
</para>

<screen>
	PrivateData * p = (PrivateData*) drvthis->private_data;
</screen>

<para>
  Then you can access your data like:
</para>
<screen>
	p->framebuf
</screen>

</sect1>

<sect1 id="function-details">
  <title>FUNCTIONS IN DETAIL</title>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*init)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  The init() function.
  It starts up the LCD, initializes all variables, allocates private data space
  and stores the pointer by calling store_private_ptr();
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*close)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Shut down the connection with the LCD.
  Called just before unloading the driver.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*width)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Get the screen width in characters.
  The result is 1-based.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*height)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Get the screen height in lines.
  The result is 1-based.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*clear)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Clear the framebuffer.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*flush)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Flush the framebuffer to the LCD.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*string)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>x</parameter></paramdef>
	<paramdef>int <parameter>y</parameter></paramdef>
	<paramdef>char *<parameter>str</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Place string <replaceable>str</replaceable> into position
  (<replaceable>x</replaceable>,<replaceable>y</replaceable>) in the framebuffer.
  All coordinates are 1-based, i.e. (1,1) is top left.
  The driver should check for overflows, i.e. that the positional parameters
  are within the screen's boundaries and cut off the part of the string
  that is out of bounds.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*chr)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>x</parameter></paramdef>
	<paramdef>int <parameter>y</parameter></paramdef>
	<paramdef>char <parameter>c</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Place a single character <replaceable>c</replaceable> into position
  (<replaceable>x</replaceable>,<replaceable>y</replaceable>) in the framebuffer.
  The driver should check for overflows, i.e. that the positional parameters
  are within the screen's boundaries and ignore the request if 
  the character is out of bounds.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*vbar)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>x</parameter></paramdef>
	<paramdef>int <parameter>y</parameter></paramdef>
	<paramdef>int <parameter>len</parameter></paramdef>
	<paramdef>int <parameter>promille</parameter></paramdef>
	<paramdef>int <parameter>options</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Draw a vertical bar at position (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
  that has maximal length <replaceable>len</replaceable>, where a fraction of
  (<replaceable>promille</replaceable> / 1000) is filled.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*hbar)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>x</parameter></paramdef>
	<paramdef>int <parameter>y</parameter></paramdef>
	<paramdef>int <parameter>len</parameter></paramdef>
	<paramdef>int <parameter>promille</parameter></paramdef>
	<paramdef>int <parameter>options</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Draw a horizontal bar at position (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
  that has maximal length <replaceable>len</replaceable>, where a fraction of
  (<replaceable>promille</replaceable> / 1000) is filled.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*num)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>x</parameter></paramdef>
	<paramdef>int <parameter>num</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Display big number <replaceable>num</replaceable> at horizontal position <replaceable>x</replaceable>.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*heartbeat)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>state</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Sets the heartbeat to the indicated state.
  0=off 1=graph1 2=graph2
  David GLAUDE:
  "state is apparently type and it could have the value
  HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
  The driver choose how to do it. See MtxOrb.c"
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*icon)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>x</parameter></paramdef>
	<paramdef>int <parameter>y</parameter></paramdef>
	<paramdef>int <parameter>icon</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*set_char)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>char <parameter>ch</parameter></paramdef>
	<paramdef>char *<parameter>dat</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*get_free_chars)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*cellwidth)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*cellheight)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*contrast)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>contrast</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Sets the contrast to the given value. Values should be 0 to 255.
  Many displays do not support software setting of contrast.
  Use -1 to get the current value returned.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*backlight)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>brightness</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Sets the backlight to brightness 'on'.
  Often hardware can only support on and off, in that case any value
  of on>0 will switch the backlight on.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>void <function>(*output)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
	<paramdef>int <parameter>state</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Sets the output value. Some displays/wirings have a general purpose
  output, which can be controlled by calling this function. See the
  'output' command in the 'widget language'.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>const char *<function>(*get_key)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Checks if a key has been pressed on the device.
  Returns NULL for "no key pressed", or a string describing the pressd key.
  These characters should match the keypad-layout.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>char *<function>(*get_info)</function></funcdef>
	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Returns a string describing the driver and its features.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>char <function>(*config_get_bool)</function></funcdef>
	<paramdef>char *<parameter>sectionname</parameter></paramdef>
	<paramdef>char *<parameter>keyname</parameter></paramdef>
	<paramdef>int <parameter>skip</parameter></paramdef>
	<paramdef>char <parameter>default_value</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Call to server. Retrieve a bool from the config file.
  Sectionname should be the name of the driver (as in the struct).
  If the key cannot be found, the default value will be returned.
  skip should be 0 usually, but if you want to retrieve multiple
  identical keys, then increase skip to get every next value.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>(*config_get_int)</function></funcdef>
	<paramdef>char *<parameter>sectionname</parameter></paramdef>
	<paramdef>char *<parameter>keyname</parameter></paramdef>
	<paramdef>int <parameter>skip</parameter></paramdef>
	<paramdef>int <parameter>default_value</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Call to server. Retrieve an integer from the config file.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>double <function>(*config_get_float)</function></funcdef>
	<paramdef>char *<parameter>sectionname</parameter></paramdef>
	<paramdef>char *<parameter>keyname</parameter></paramdef>
	<paramdef>int <parameter>skip</parameter></paramdef>
	<paramdef>double <parameter>default_value</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Call to server. Retrieve a float from the config file.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>char *<function>(*config_get_string)</function></funcdef>
	<paramdef>char *<parameter>sectionname</parameter></paramdef>
	<paramdef>char *<parameter>keyname</parameter></paramdef>
	<paramdef>int <parameter>skip</parameter></paramdef>
	<paramdef>char *<parameter>default</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Call to server. Retrieve a string from the config file.
  Fill result with a pointer to some available space. You can fill it
  with a default value. If the key is found, it will be overwritten
  with the value from the key.
  Note that you should always first copy the the returned string.
  It is in the address space of the server, and will be freed at the
  next call.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>config_has_section</function></funcdef>
	<paramdef>char *<parameter>sectionname</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Returns wether a section exists. Does not need to be called prior
  to a call to a config_get_* function.
</para>

<funcsynopsis>
  <funcprototype>
	<funcdef>int <function>config_has_key</function></funcdef>
	<paramdef>char *<parameter>sectionname</parameter></paramdef>
	<paramdef>char *<parameter>keyname</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<para>
  Returns the number of times a key exists. Does not need to be called
  prior to a call to a config_get_* function.
</para>


<screen>
First version, Joris Robijn, 20011016
</screen>

</sect1>

</chapter>