LCDproc Developer's Guide

This document is meant to be a reference for LCDproc developers. It tries to indicate you where to find the relevant information about LCDproc's inner workings.

This document was written for LCDproc 0.5.

In several other places e-mails and other documents have been included in this document. The authors of those are listed below every such document.

The LCDproc clients, for example lcdproc, connect over the network to LCDd. In their communication they use a protocol, often referred to as the "widget language". In this chapter the widget language will be discussed.

The essence of talking to LCDd is quite simple. First you will need to connect to the LCDproc port (usually 13666) on the correct IP address (by default localhost). Once you have established the connection you should say "hello", to let LCDd know you are a good guy. It will respond by telling some LCDproc data, like version and screen width and height. Now your session is open and you can start sending 'real' commands.

LCDd can send a number of strings itself. As a response to your commands, it will usually send a "success" string, or a string starting with "huh" in case of any error. See further below for other strings sent by LCDd.

You can test all these commands by opening a TCP/IP connection manually, like with:

telnet localhost 13666

This way, you can check how the various commands work. It's in this case best to have no other clients. If you do have other clients, you will receive "listen" and "ignore" messages that will disturb your typing.

In this section all commands and their parameters are listed, along with the responses you can expect. If you need a space or a special char in a string, you should quote the string with double quotes. If you need to use a double quote, escape it with a backslash. The listing is divided into subsections for

	  client_set name Parenttest
	  # to be entered on escape from test_menu (but overwritten
	  # for test_{checkbox,ring})
	  menu_add_item "" ask menu "Leave menus?" -is_hidden true
	    menu_add_item "ask" ask_yes action "Yes" -next _quit_
	    menu_add_item "ask" ask_no action "No" -next _close_

	  menu_add_item "" test menu "Test"
	    menu_add_item "test" test_action action "Action"
	    menu_add_item "test" test_checkbox checkbox "Checkbox"
	    menu_add_item "test" test_ring ring "Ring" -strings "one\ttwo\tthree"
	    menu_add_item "test" test_slider slider "Slider" -mintext "" -maxtext "" -value "50"
	    menu_add_item "test" test_numeric numeric "Numeric" -value "42"
	    menu_add_item "test" test_alpha alpha "Alpha" -value "abc"
	    menu_add_item "test" test_ip ip "IP" -v6 false -value "192.168.1.1"
	    menu_add_item "test" test_menu menu "Menu"
	    menu_add_item "test_menu" test_menu_action action "Submenu's action"

	  # no successor for menus. Since test_checkbox and test_ring have their
	  # own predecessors defined the "ask" rule will not work for them
	  menu_set_item "" test -prev "ask"

	  menu_set_item "test" test_action -next "test_checkbox"
	  menu_set_item "test" test_checkbox -next "test_ring" -prev "test_action"
	  menu_set_item "test" test_ring -next "test_slider" -prev "test_checkbox"
	  menu_set_item "test" test_slider -next "test_numeric" -prev "test_ring"
	  menu_set_item "test" test_numeric -next "test_alpha" -prev "test_slider"
	  menu_set_item "test" test_alpha -next "test_ip" -prev "test_numeric"
	  menu_set_item "test" test_ip -next "test_menu" -prev "test_alpha"
	  menu_set_item "test" test_menu_action -next "_close_"

	  # replace the main menu with the client's menu as created above
	  menu_set_main ""
	

LCDd can send messages back to the client. These messages can be directly related to the last command, or generated for some other reason. Because messages can be generated at any moment, the client should read from the connection at regular intervals. A very simple client could simply ignore all received messages. Not reading the messages will cause trouble !

If you want to start programming for LCDproc you will need the have the most current source code available. You can get it several ways:

$ tar xvfz lcdproc-CVS-current.tar.gz

$ cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc login

$ cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc checkout -P lcdproc

$ cvs update -d

LCDproc has been developed by many contributors over many years. You may find different programming styles (naming, indention, etc) in the source code.

When modifying an existing file, please take a careful look at its style and program continuing that style instead of mixing it up with another one even if it does not comply with the guidelines written below.

For newly added files the following guideline describes how source code should look like.

/* Constants */
#define KEYPAD_AUTOREPEAT_DELAY 500
#define KEYPAD_AUTOREPEAT_FREQ 15

/* Variable names */
MODULE_EXPORT char * api_version = API_VERSION;
MODULE_EXPORT int stay_in_foreground = 0;
MODULE_EXPORT int supports_multiple = 1;

/* Function names */
void HD44780_position(Driver *drvthis, int x, int y);
static void uPause(PrivateData *p, int usecs);
unsigned char HD44780_scankeypad(PrivateData *p);
  

-TPrivateData
-TDriver

-l100
-lc79
-i8
-ip8
-di1
-cd33
-ci8
-cli0
-ts8

-ut
-nsob
-sc
-psl
-npcs
-lp
-fc1
-nbc
-nce
-brs
-br
-sbi0
-saw
-sai
-saf
-nprs
-hnl
-fca
-cdw
-nbfda
-nbbo
-ncdb
-nbad
-cs
    

When you have finished modifying the code you may decide to submit it to the LCDproc project. You usually do this by submitting a patch for review to the mailing list.

To create a patch you need the unmodified files and the files containing your modifications. Usually you do this by storing an unmodified copy of the sources in one directory and another copy with your modifications in another one. You then run diff like this:

diff-urN -X unmodified-dir/diff_ignore unmodified-dir your-source-dir > mymodifications.patch

If you have modified files in a source tree you checked out from CVS you can also run cvs diff from the working directory:

cvs diff-u > mymodifications.patch

Here we provide functions that should be used by all parts of the program.

To enable the debug() function on all of the software, just type:

./configure --enable-debug and recompile with 'make'.

This way, the global DEBUG macro is off but is locally enabled in certain parts of the software.

The reporting levels have the following meaning.

Levels 4 (maybe) and 5 (certainly) should be reported using the debug function. The code that this function generates will not be in the executable when compiled without debugging. This way memory and CPU cycles are saved.

report.h file defines 3 functions for debugging and reporting:

Driving an LCD display is not easy; you need to address ports, to send bytes in a certain order, to respect timing, and unfortunately no two operating system let you do this in the same way. But don't despair! There's hope! Someone in a galaxy far far away, has Already done the dirty job for you! This dirty job has been put in shared files. These shared files are full cross platform and are auto-magically configured by the configure script. You only need to include them and use their functions to benefit from them.

These files are provided only for drivers, others are provided for all of LCDproc. These files are located in the shared directory, they have a dedicated chapter in this book.

#include "port.h"

/*
 * Get access to these 3 ports:
 *  0x378 (CONTROL),
 *  0x379 (STATUS) and
 *  0x37A (DATA)
 */
if (port_access_multiple(0x378, 3) == -1) {
	/* Access denied, do something */
}

/* Write a 'A' to the control port */
port_out(0x378, 'A');

/* Read from the status port */
char status = port_in(0x379);

/* Close the 3 ports */
port_deny_multiple(0x378, 3);

#include "adv_bignum.h"

MODULE_EXPORT void
myDriver_num( Driver * drvthis, int x, int num )
{
  PrivateData *p = drvthis->private_data;
  int do_init = 0;

  if (p->ccmode != CCMODE_BIGNUM){     // Are the custom-characters set up correctly? If not:
    do_init = 1;                       // Lib_adv_bignum has to set the custom-characters.
    p->ccmode = CCMODE_BIGNUM;         // Switch custom-charactermode to bignum.
  }

  // Lib_adv_bignum does everything needed to show the big-numbers.
  lib_adv_bignum(drvthis, x, num, 0, do_init);
}

myDriver_LDADD: libLCD.a libbignum.a

myDriver_SOURCES: lcd.h lcd_lib.h myDriver.c myDriver.h report.h adv_bignum.h

The API defines functions which drivers may implement to provide certain services. If a driver implements a function, the function will be detected by the server. For some optional functions the server core provides default implementations.

The API consists of functions to:

The API is best described by starting with the struct lcd_logical_driver which is defined in server/drivers/lcd.h.

Below is a commented version of lcd_logical_driver. Each function is described more detailed in the section called “Functions in Detail”.

typedef struct lcd_logical_driver {

	//////// Variables to be provided by the driver module
	// The driver loader will look for symbols with these names !

	// pointer to a string describing the API version
	char *api_version;

	// Does this driver require to be in foreground ?
	int *stay_in_foreground;

	/ Does this driver support multiple instances ?
	int *supports_multiple;

	// What should alternatively be prepended to the function names ?
	char **symbol_prefix;

	//////// Functions to be provided by the driver module

	//// Mandatory functions (necessary for all drivers)

	// initialize driver: returns >= 0 on success
	int (*init)		(Driver *drvthis);

	// close driver
	void (*close)		(Driver *drvthis);


	//// Essential output functions (necessary for output drivers)

	// get display width / height (in characters; 1-based)
	int (*width)		(Driver *drvthis);
	int (*height)		(Driver *drvthis);

	// clear screen
	void (*clear)		(Driver *drvthis);

	// flush screen contents to LCD
	void (*flush)		(Driver *drvthis);

	// write string s at position (x,y)
	void (*string)		(Driver *drvthis, int x, int y, const char *str);

	// write char c at position (x,y)
	void (*chr)		(Driver *drvthis, int x, int y, char c);


	//// essential input functions (necessary for input drivers)

	// get key from driver: returns a string denoting the key pressed
	const char *(*get_key)	(Driver *drvthis);


	//// Extended output functions (optional; core provides alternatives)

	// draw a bar from pos (x,y) upward / to the right filling promille of len chars
	void (*vbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);
	void (*hbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);

	// display (big) number num at horizontal position x
	void (*num)		(Driver *drvthis, int x, int num);

	// set heartbeat state; animate heartbeat
	void (*heartbeat)	(Driver *drvthis, int state);

	// draw named icon at position (x,y)
	int (*icon)		(Driver *drvthis, int x, int y, int icon);

	// set cursor type and move it to position (x,y)
	void (*cursor)		(Driver *drvthis, int x, int y, int type);


	//// User-defined character functions

	// set special character / get free characters
	// - It is currently unclear how this system should work exactly
	// - 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)
	void (*set_char)	(Driver *drvthis, int n, unsigned char *dat);
	int (*get_free_chars)	(Driver *drvthis);

	// get width / height of a character cell (in pixels)
	// - necessary to provide info about cell size to clients
	// - if not defined, the core will provide alternatives returning default values
	int (*cellwidth)	(Driver *drvthis);
	int (*cellheight)	(Driver *drvthis);


	//// Hardware functions

	// get / set the display's contrast
	int (*get_contrast)	(Driver *drvthis);
	void (*set_contrast)	(Driver *drvthis, int promille);

	// get / set brightness for given backlight state
	int (*get_brightness)	(Driver *drvthis, int state);
	void (*set_brightness)	(Driver *drvthis, int state, int promille);

	// set backlight state
	void (*backlight)	(Driver *drvthis, int state);

	// set output
	void (*output)		(Driver *drvthis, int state);


	//// Informational functions
	// get a string describing the driver and it's features
	const char * (*get_info) (Driver *drvthis);



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

	// name of the driver instance (name of the config file section)
	// - do not change from the driver; consider it read-only
	// - to be used to access the driver's own section in the config file
	char * name;

	// pointer to the driver instance's private data
	// - filled by the server by calling store_private_ptr()
	// - the driver should cast this to it's own private structure pointer
	void * private_data;


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

	// store a pointer to the driver instance's private data
	int (*store_private_ptr) (struct lcd_logical_driver * driver, void * private_data);

	// Config file functions, cwprovided by the server
	// - see configfile.h on how to use these functions
	// - as sectionname, always use the driver name: drvthis->name
	short (*config_get_bool) (char * sectionname, char * keyname,
				int skip, short default_value);
	long int (*config_get_int) (char * sectionname, char * keyname,
				int skip, long int default_value);
	double (*config_get_float) (char * sectionname, char * keyname,
				int skip, double default_value);
	const char *(*config_get_string) (char * sectionname, char * keyname,
				int skip, const char * default_value);
				// Returns a string in server memory space.
				// Copy this string.
	int config_has_section	(const char *sectionname);
	int config_has_key	(const char *sectionname, const char *keyname);

	// error reporting function
	// - see drivers/report.h for details
	void (*report)		( const int level, const char *format, .../*args*/ );

	// Display properties functions (for drivers that adapt to other loaded drivers)
	// - the return the size of another already loaded driver
	// - if no driver is loaded yet, the return values will be 0
	int (*get_display_width) ();
	int (*get_display_height) ();
} Driver;

With the introduction of loadable modules it is necessary to stop using global variables to store a driver's data in. Instead, you should store it in a structure, that you allocate and 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 !

In the driver's private structure will probably at least be something like:

typedef struct MyDriver_private_data {
	int fd;				// file descriptor for the LCD device
        int width, height;		// dimension of the LCD (in characters, 1-based
        int cellwidth, cellheight;	// Size of each LCD cell, in pixels
        unsigned char *framebuf;	// Frame buffer...
} PrivateData;

You allocate and store this structure like this:

	PrivateData *p;

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

	// initialize private data
	p->fd = -1;
	p->cellheight = 8;
	p->cellwidth = 6;

	(... continue with the rest of your init routine)

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

	PrivateData *p = (PrivateData *) drvthis->private_data;

Then you can access your data like:

	p->framebuf

The init() function. It starts up the LCD, initializes all variables, allocates private data space and stores the pointer by calling store_private_ptr(); Returns <0 on error.

Shut down the connection with the LCD. Called just before unloading the driver.

Get the screen width in characters. The result is 1-based.

Get the screen height in character lines. The result is 1-based.

Clear the framebuffer.

Flush the framebuffer to the LCD.

Place string str into position (x,y) 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.

Place a single character c into position (x,y) 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.

Draw a vertical bar at position (x,y) that has maximal length len, where a fraction of (promille / 1000) is filled.

Draw a horizontal bar at position (x,y) that has maximal length len, where a fraction of (promille / 1000) is filled.

Display big number num at horizontal position x.

Sets the heartbeat to the indicated state: 0=off, 1=on. Use HEARTBEAT_ON to say that we want to display/refresh the heartbeat. The driver choose how to do it.

Draw named icon icon at position (x,y). If the driver returns -1 the server core will draw an appropriate replacement character.

Move cursor to position (x,y), setting its type to type.

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)

Get total number of custom characters available.

Return the width of a character cell in pixels. The result is 1-based.

Return the height of a character cell in pixels. The result is 1-based.

Get the contrast value from the driver. The return value is an integer in the range from 0 to 1000. Many displays do not support getting or setting contrast using software.

Sets the contrast to the given value, which is an integer in the range from 0 to 1000. It is up to the driver to map the logical interval [0, 1000] into the interval that the hardware supports. Many displays do not support software setting of contrast.

Get the brightness value from the driver for the given backlight state. The parameter state determines which one is returned. The return value is an integer in the range from 0 to 1000. Many displays do not support getting or setting brightness using software.

Set the brightness for the given backlight state to the value given. Value must be an integer in the range from 0 to 1000. It is up to the driver to map the logical interval [0, 1000] into the interval that the hardware supports. Many displays do not support software setting of brightness.

Sets the backlight to the given brightness state. Often hardware can only support two values for the backlight: on and off. In that case any value of state > 0 will switch the backlight on.

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'.

Checks if a key has been pressed on the device. Returns NULL for "no key pressed", or a string describing the pressed key. These characters should match the keypad-layout.

Returns a string describing the driver and its features.

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.

Call to server. Retrieve an integer from the config file.

Call to server. Retrieve a float from the config file.

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.

Returns whether a section exists. Does not need to be called prior to a call to a config_get_* function.

Returns the number of times a key exists. Does not need to be called prior to a call to a config_get_* function.

First version, Joris Robijn, 20011016
Corrected and expanded, Peter Marschall 20060411
Sync'd with lcd.h, Markus Dolze, 20090322

LCDproc is meant to be modular, it is relatively easy to add new input and output drivers to LCDproc.

This chapter will explain you the major steps and few gotchas of adding your own driver to LCDproc. Enjoy!

Be sure to read Chapter 3, Programming for LCDproc and Chapter 5, The LCDproc driver API as well.

As a starting point you may take a look at the debug driver. It is available as server/drivers/debug.c.

LCDproc is open source software. Anyone is free to take LCDproc's code, write his own driver and publish the modified sources somewhere again. If you want your driver to be included in LCDproc's code some conditions have to be met:

How I Learned to Stop Worrying and Love the Configure Script

It was decided pretty early in LCDproc's life to use GNU autoconf and GNU automake. This allows LCDproc to be ported to several platforms with much less effort. It can be quite daunting to understand how autoconf & automake interact with each others and with your code, but don't be discouraged. We have taken great care in making this as simple as possible for programmers to add their own driver to LCDproc. Hopefully, you'll only have to modify two files, one for autoconf and one for automake.

The first thing you need to do is to find a name for your driver, it should be as descriptive as possible; most drivers are named after their respective chipset, for example hd44780, mtc_s16209x, sed1330 and stv5730, others are named after the company that makes that particular LCD display, for example CFontz and MtxOrb. Remember that these names are case sensitive. In this chapter, we'll use myDriver (which is an absolute non-descriptive name).

AC_ARG_ENABLE(drivers,
	[  --enable-drivers=<list> compile driver for LCDs in <list>.]
	[                  drivers may be separated with commas.]
	[                  Possible choices are:]
	[                    bayrad,CFontz,CFontz633,CFontzPacket,curses,CwLnx,]
	[                    glcdlib,glk,hd44780,icp_a106,imon,IOWarrior,irman,]
	[                    joy,lb216,lcdm001,lcterm,lirc,ms6931,mtc_s16209x,]
	[                    MtxOrb,NoritakeVFD,pyramid,sed1330,sed1520,serialVFD,]
	[                    sli,stv5730,svga,t6963,text,tyan,ula200,xosd]
	[                  'all' compiles all drivers;]
	[                  'all,!xxx,!yyy' de-selects previously selected drivers],
	drivers="$enableval",

AC_ARG_ENABLE(drivers,
	[  --enable-drivers=<list> compile driver for LCDs in <list>.]
	[                  drivers may be separated with commas.]
	[                  Possible choices are:]
	[                    bayrad,CFontz,CFontz633,CFontzPacket,curses,CwLnx,]
	[                    glcdlib,glk,hd44780,icp_a106,imon,IOWarrior,irman,]
	[                    joy,lb216,lcdm001,lcterm,lirc,ms6931,mtc_s16209x,]
	[                    MtxOrb,NoritakeVFD,pyramid,sed1330,sed1520,serialVFD,]
	[                    sli,stv5730,svga,t6963,text,tyan,ula200,xosd,myDriver]
	[                  'all' compiles all drivers;]
	[                  'all,!xxx,!yyy' de-selects previously selected drivers],
	drivers="$enableval",

allDrivers=[bayrad,CFontz,CFontz633,...(big list)...,tyan,ula200,xosd]

allDrivers=[bayrad,CFontz,CFontz633,...(big list)...,tyan,ula200,xosd,myDriver]

		myDriver)
			DRIVERS="$DRIVERS myDriver${SO}"
			actdrivers=["$actdrivers myDriver"]
			;;

EXTRA_PROGRAMS = bayrad CFontz ...(big list)... ula200 xosd

EXTRA_PROGRAMS = bayrad CFontz ...(big list)... ula200 xosd myDriver

myDriver_LDADD = @SOMESTRANGELIB@

myDriver_SOURCES =  lcd.h myDriver.c myDriver.h report.h

Please do not forget to also add the required documentation, so that your driver can be used from others as well.

…

## MyDriver for MyDevice ##
[MyDriver]

# Select the output device to use [default: /dev/lcd]
Device=/dev/ttyS0

# Set the display size [default: 20x4]
Size=20x4

…

…
.TP
.B ms6931
MSI-6931 displays in 1U rack servers by MSI
.TP
.B mtc_s16209x
MTC_S16209x LCD displays by Microtips Technology Inc
.TP
.B MtxOrb
Matrix Orbital displays (except Matrix Orbital GLK displays)
.TP
.B MyDriver
displays connected using MyDevice
.TP
.B NoritakeVFD
Noritake VFD Device CU20045SCPB-T28A
.TP
.B pyramid
LCD displays from Pyramid (http://www.pyramid.de)
.TP
.B sed1330
SED1330/SED1335 (aka S1D13300/S1D13305) based graphical displays
…

…
<!ENTITY ms6931 SYSTEM "drivers/ms6931.docbook">
<!ENTITY mtc_s16209x SYSTEM "drivers/mtc_s16209x.docbook">
<!ENTITY MtxOrb SYSTEM "drivers/mtxorb.docbook">
<!ENTITY MyDriver SYSTEM "drivers/MyDriver.docbook">
<!ENTITY NoritakeVFD SYSTEM "drivers/NoritakeVFD.docbook">
<!ENTITY pylcd SYSTEM "drivers/pylcd.docbook">
<!ENTITY sed1330 SYSTEM "drivers/sed1330.docbook">
…

…
&ms6931;
&mtc_s16209x;
&MtxOrb;
&MyDriver;
&NoritakeVFD;
&pylcd;
&sed1330;
…

## Process this file with automake to produce Makefile.in

EXTRA_DIST =	bayrad.docbook \
		CFontz.docbook \
		...
		MyDriver.docbook \
		...
## EOF

Any release of LCDproc is accompanied the the user guide and developer guide. Here is how to create these documentation packages.

The online documentation consists of the user and developer guide, each converted to a single file for viewing online.