diff --git a/docs/LCDd.8 b/docs/LCDd.8 index b6605d1..66ec8dd 100644 --- a/docs/LCDd.8 +++ b/docs/LCDd.8 @@ -1,21 +1,24 @@ -.TH LCDd 8 "9 September 2001" LCDproc +.TH LCDd 8 "4 March 2002" LCDproc .SH NAME LCDd - LCDproc server daemon .SH SYNOPSIS .B LCDd -[\-\-help] -[\-\-type <\fIsize\fP>] -[\-\-driver <\fIdriver\fP> [\fIargs\fP] ] -[\-\-foreground \fI\fP] -[\-\-backlight <\fImode\fP>] -[\-\-serverinfo off] +[\-hfiws] +[\-c <\fIconfig\fP>] +[\-d <\fIdriver\fP>] +[\-a <\fIaddr\fP>] +[\-p <\fIport\fP>] +[\-u <\fIuser\fP>] +[\-w <\fItime\fP>] +[\-r <\fIlevel\fP>] .SH DESCRIPTION LCDd is the server portion of LCDproc which listens to a certain port (normally 13666) and displays information on an LCD display. It works with several types and sizes of displays. .PP -LCDd will attempt to open /dev/lcd by default and will error if this -device is not available. In most cases, it should be sufficient to -link /dev/lcd to the appropriate serial or parallel device. +As of version 0.4.3 of LCDproc most settings are configured through the LCDd configuration +file, which is normally /etc/LCDd.conf. Before running LCDd you should carefully read through +that file and modify everything neccessary according to your needs. Otherwise you might encounter +LCDd not running properly on your system. .PP To make full use of LCDd, a client such as lcdproc(1) is required. .SH OPTIONS @@ -23,41 +26,52 @@ Available .I LCDd options are: .TP 8 -.B \-h, \-\-help +.B \-h Display this help screen .TP 8 -.B \-t, \-\-type -select an LCD size (20x4, 16x2, etc...) +.B \-c +Use a configuration file other than /etc/LCDd.conf .TP 8 -.B \-d, \-\-driver <\fIdriver\fP> [\fIargs\fP] -Adds (another) driver to use to display information. Any \fIargs\fP specified will be -passed to the chosen driver for initialization. +.B \-d +Add a driver to use (output only to first) .TP 8 -.B \-f, \-\-foreground -Run in the foreground (no daemon) +.B \-f +Run in the foreground .TP 8 -.B \-b\fP,\fB \-\--backlight \fI\fP -Set backlight mode (on, off, open) +.B \-i +Disable showing of the main LCDproc server screen .TP 8 -.B \-i, \-\-serverinfo off -Set the server screen to low priority -.PP -Help on each driver's parameters are obtained upon request: -"LCDd -d driver --help" +.B \-w +Time to pause at each screen (in seconds) +.TP 8 +.B \-a +Network IP address to bind to +.TP 8 +.B \-p +Network port to listen for connections on +.TP 8 +.B \-u +User to run as +.TP 8 +.B \-s +Output messages to syslog +.TP 8 +.B \-r +Report level (default=2) .SS Supported Drivers -Supported display drivers include: +Currently supported display drivers include: .TP -.B CFontz +.B CFontz (or CrystalFontz) CrystalFontz LCD displays .TP -.B curses +.B curses (or ncurses) Standard video display using the ncurses library .TP .B HD44780 Hitachi HD44780 LCD displays .TP -.B BayRad +.B BayRAD EMAC BayRad displays .TP .B irmanin @@ -72,14 +86,17 @@ Wirz SLI driver (unknown) .B joy Joystick driver (input) .TP -.B MtxOrb +.B MtxOrb (or MatrixOrbital) Matrix Orbital displays (not Matrix Orbital GLK displays) .TP +.B glk +Matrix Orbital GLK graphical LCD displays +.TP .B LB216 LB216 LCD display .TP -.B glk -Matrix Orbital GLK graphical LCD displays +.B lcdm001 (or LCDM001) +kernelconcepts.de 20x4 serial LCD displays .TP .B text Standard "hard-copy" text display @@ -88,12 +105,13 @@ Standard "hard-copy" text display Undocumented debug driver .PP Multiple drivers can be used simultaneously; thus, for example, a Matrix Orbital display (MtxOrb driver) -can be combined with the an infrared driver (irmanin driver). +can be combined with an infrared driver (irmanin driver). .SH INVOCATION .TP -LCDd -d MtxOrb "--device /dev/lcd --contrast 200" -d joy -Start LCDd with the Matrix Orbital driver and the Joystick input driver, -with the /dev/lcd device and a contrast value of 200. +LCDd -d MtxOrb -d joy +As of version 0.4.3, driver parameters are read from a configuration file (default location /etc/LCDd.conf) rather than being passed on the command line as arguments. +The invocation example above will start LCDd with the Matrix Orbital driver and the Joystick input driver, +and attempt to load the driver parameters from the default configuration file. .SH SERVER PROTOCOL There is a basic sequence: .TP 8 @@ -273,7 +291,7 @@ frames per movement; a negative number indicates movements per frame. left top right bottom wid hgt dir speed .sp Frames define a visible "box" on screen, -from the (\fIleft\fR, \fItop\fR) corner to the +>from the (\fIleft\fR, \fItop\fR) corner to the (\fIright\fR, \fIbottom\fR) corner. The actual data may be bigger, and is defined as \fIwid\fR (width) by \fIhgt\fR (height); if it is bigger, then the frame will scroll in the direction (\fIdir\fR) @@ -284,23 +302,25 @@ check the order of the options and the quoting involved. Some combinations of options will be misread and thus fail. .PP Try using the -d option last. +.SH FILES +.na +.nf +\fB/etc/LCDd.conf\fR, LCDd default configuration file +.Sh SEE ALSO +.Xr lcdproc 1 .SH AUTHOR -LCDd was written by William Ferrell (choadster@earthlink.net) and Scott Scriv +LCDd was originally written by William Ferrell (wwf@splatwerks.org) and Scott Scriv en (scriven@cs.colostate.edu). +Since that time various people have contributed to LCDproc. + The newest version of LCDd should be available from here as part of the lcdproc package: http://lcdproc.omnipotent.net/ .SH LEGAL STUFF -The lcdproc package is released as "WorksForMe-Ware". In other words, it is free, kinda nea -t, and we don't guarantee that it will do anything in particular on any machine -except the ones it was developed on. +The lcdproc package is released as "WorksForMe-Ware". In other words, it is free, kinda neat, and we don't guarantee that it will do anything in particular on any machine except the ones it was developed on. .PP -It is technically released under the GNU GPL license (you should have received t -he file, "COPYING", with LCDproc) (also, look on http://www.fsf.org/ for more in -formation), so you can distribute and use it for free -- but you must make the s -ource code freely available to anyone who wants it. +It is technically released under the GNU GPL license (you should have received the file, "COPYING", with LCDproc) (also, look on http://www.fsf.org/ for more information), so you can distribute and use it for free -- but you must make the source code freely available to anyone who wants it. .PP -For any sort of real legal information, read the GNU GPL (GNU General Public Lic -ense). It's worth reading. +For any sort of real legal information, read the GNU GPL (GNU General Public License). It's worth reading. diff --git a/docs/Makefile.am b/docs/Makefile.am index dc04574..72328fd 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,2 +1,3 @@ man_MANS = lcdproc.1 LCDd.8 -EXTRA_DIST = README.dg README.dg2 hd44780_howto.txt lcdproc.sgml menustuff.txt netstuff.txt lcdproc.1 LCDd.8 +SUBDIRS = lcdproc-user +EXTRA_DIST = README.dg README.dg2 menustuff.txt netstuff.txt lcdproc.1 LCDd.8 diff --git a/docs/lcdproc-user/Makefile.am b/docs/lcdproc-user/Makefile.am new file mode 100644 index 0000000..e1ff44c --- /dev/null +++ b/docs/lcdproc-user/Makefile.am @@ -0,0 +1,2 @@ +SUBDIRS = drivers +EXTRA_DIST = bookinfo.docbook configuration.docbook contact.docbook drivers.docbook how-to-obtain.docbook installation.docbook introduction.docbook lcdproc-user.docbook license.docbook README.docbook running.docbook diff --git a/docs/lcdproc-user/README.docbook b/docs/lcdproc-user/README.docbook new file mode 100644 index 0000000..3485a98 --- /dev/null +++ b/docs/lcdproc-user/README.docbook @@ -0,0 +1,14 @@ +README.docbook + +You can generate the documentation of LCDproc using +the Docbook utilities. + +$ docbook2html lcdproc-user.docbook + +should generate ist as HTML. + +On my box (Mdk 8.1) I have to run + +$ docbook2html -c /etc/sgml/catalog lcdproc-user.docbook + +(-c defines the location of the SGML catalog) \ No newline at end of file diff --git a/docs/lcdproc-user/bookinfo.docbook b/docs/lcdproc-user/bookinfo.docbook new file mode 100644 index 0000000..bafb35f --- /dev/null +++ b/docs/lcdproc-user/bookinfo.docbook @@ -0,0 +1,70 @@ + + +LCDproc User's Guide +The Ultimate Guide to LCDproc 0.4.3 + + + + +Rene +Wagner +
reenoo@gmx.de
 + + + +Guillaume +Filion +
gfk@logidac.com
 + + + +William W. +Ferrell +
wwf@splatwerks.org
 + + + + +2002-03-01 +0.0.1 + + + +This document is a guide to LCDproc written for users. It covers LCDproc 0.4.3 ONLY. +Some things may be valid for 0.5 as well, but a lot has changed since 0.4.1 and a lot +will change for 0.5. + + + + +2002 +Rene Wagner + + +2002 +Guillaume Filion + + +1999 +William W. Ferrell + + + + +Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, Version +1.1 or any later version published by the Free Software Foundation; with +no Invariant Sections, with no Front-Cover texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + + + + +documentation +LCDproc +0.4.3 +user's guide + + + diff --git a/docs/lcdproc-user/configuration.docbook b/docs/lcdproc-user/configuration.docbook new file mode 100644 index 0000000..8d279e7 --- /dev/null +++ b/docs/lcdproc-user/configuration.docbook @@ -0,0 +1,428 @@ + +LCDproc Configuration + + +Configure LCDd + + +As mentioned in the introduction +LCDd, the LCDproc server, now (with version 0.4.3 of LCDproc) has its +own configuration file, which is normally /etc/LCDd.conf. + + + + +If you have not installed LCDproc from the sources the configuration +file might have a different location. You should find it when making +your system's package manager list all the files in the LCDproc package. + + + + +The format of the /etc/LCDd.conf is ini-file-like. + + +It is divided into sections that start at +markers that look like [section]. Comments are all line-based comments, +and are lines that start with '#' or ';'. + + + +The server has a 'central' section named [server]. Further each driver +has a section which defines how the driver acts. Those sections start with +[drivername]. + + +The drivers are activated by specifiying them in a driver= line in the +server section, like: + + + +<filename>LCDd.conf</filename>: Specify which driver to use + + +Driver=curses + + + + + +This tells LCDd to use the curses driver. The first driver specified here +that is capable of output functionality will be used as 'the' output driver. +All extra drivers can only serve as input. +The default driver to use is curses. + + + + +If LCDd is started automatically by an init-script using the curses driver +will lock /dev/tty1! So, be careful about what you are +doing here. + + + + +The drivers can read their own options from the config file, but most of +them don't do this yet. They expect 'command-line'-format parameters that +were previously placed on the command line. These parameters can be +given to the driver in the following way: + + + +<filename>LCDd.conf</filename>: Compatibility mode for drivers written for 0.4.1 + + +Arguments="place arguments here" + + + + + +The arguments between the quotes are passed to the driver. +As said before these are the same arguments that would have +been passed to the driver using the old command line format of + + + +LCDd -d driver "driverargs" + + + + +The -d option still works, but does not allow driverargs any more. + + +If -d is specified on the command line, the Driver= options in the +config file are ignored. + + + + +<filename>LCDd.conf</filename>: The [server] Section + + +The [server] section of the LCDd.conf contains the +settings for the LCDproc server LCDd. + + + + +Driver= + + +Tells the server which driver(s) to use. See +above for details + + + +The default setting is Driver=none which makes the server exit right +after the start. This is neccessary to avoid trouble with package installations. + + + + + +Bind= + + +Tells the server to bind to the given interface. Default to Bind=127.0.0.1 which +is actually the safest variant. + + + + +Port= + + +Tells the server to listen to this specified port; defaults to 13666. + + + + + +ReportLevel= + + +Sets the reporting level; defaults to 2 (warnings and errors only). + + + + + +ReportToSyslog= + + +Should we report to syslog instead of stderr ? Defaults to no. + + + + + +WaitTime= + + + +Sets the default time in seconds to display a screen. + + + + + +User= + + + +User to run as. LCDd will drop its root privileges, +if any, and run as this user instead. Defaults to User=nobody. + + + +If you want to use the server menu, to shutdown or reboot your system, + you will have to set this to root. Otherwise LCDd does not have the + privileges to run commands like init 6. + + + + + + +ServerScreen= + + + +Enables the server screen even when other screens are active. Defaults to +no. + + + + + +Foreground= + + +The server will stay in the foreground if set to true. +Otherwise the server will fork to background and report +to syslog. Defaults to yes. + + + + + + + + + + +<filename>LCDd.conf</filename>: The [input] Section + + +The [input] section enables you to set some general ("global") +options related to the way LCDd handles +input "events". + + + +The Standard LCDd Input Keys + + + +Keyname +Function + + + +Normal context +Menu context + + + + +PauseKey +Pause/Continue +Enter/select + + +BackKey +Back (Go to previous screen) +Up/Left + + +ForwardKey +Forward (Go to next screen) +Down/Right + + +MainMenuKey +Open main menu +Exit/Cancel + + + +
+ + + +The way input keys are handled will change completely in LCDproc 0.5. + + + + + +<filename>LCDd.conf</filename>: [input] Section: The Free*Key Options + + +The Free*Key Options are interesting for those users whose keypad (or other input source) +has got only four (or less) keys. In this case LCDd would normally use all those +keys to enable you to control the server menu and the other server functions (like +switching to the next screen). If these keys are used by a client to do anything +but noticing that the user has e.g. entered the menu or switched to another screen, +this will probably cause trouble, as one keypress has several effects at the same +time. + + +The Free*Key options enable you to influence this behaviour. + + + + +FreePauseKey= + + +If set to yes, this prevents LCDd from handling the PauseKey itself. +Then a client can request the key 'A' and handle it. + + + + +FreeBackKey= + + +If set to yes, this prevents LCDd from handling the BackKey itself. +Then a client can request the key 'B' and handle it. + + + + +FreeForwardKey= + + +If set to yes, this prevents LCDd from handling the ForwardKey itself. +Then a client can request the key 'C' and handle it. + + + + + +FreeMainMenuKey= + + +If set to yes, this prevents LCDd from handling the MainMenuKey itself. +Then a client can request the key 'D' and handle it. + + + +Even if you "free" the above keys, you can still use the menu +provided you set FreeMainMenuKey to no. + + + + + + + + + + + + +<filename>LCDd.conf</filename>: The Drivers Section + + +As mentioned earlier, each driver has its own section in the +LCDd.conf. + + + +The settings are more or less self-explanatory. So, read through the +section of your driver and change everything neccessary. + + + + + + + +The LCDproc Init Scripts + + +The LCDproc distribution contains init scripts for RedHat- and Debian-based +GNU/Linux distributions. You can find them in the docs/ +directory of the LCDproc sources. + + + + +The init scripts are generated using autoconf. So, again it is important that +you have run ./configure with the correct options for your +system. + + + + +Refer to your system's manual on how to install the scripts. + + + +init-LCDd + +The file scripts/init-LCDd.* is the init script for the +LCDproc server LCDd. It does not require modification. + + + + +init-lcdproc + +The file scripts/init-lcdproc.* is the init script for the +LCDproc "main" client lcdproc. As lcdproc itself does not (yet) have a configuration file +you may want to modify the options the init script passes to lcdproc. + + + + +You can retrieve a listing of all options of lcdproc running lcdproc --help. + + + + +The lcdproc init script retrieves the options it will pass to lcdproc from the file +/etc/lcdproc.conf (scripts/lcdproc.conf in the +sources distribution). + + + +<filename>lcdproc.conf</filename>: Modify the option passed to lcdproc + + +# /etc/lcdproc.conf +# +# Configuration file of the main LCDproc client "lcdproc" +# NOTE: The configuration file of LCDd is /etc/LCDd.conf + +# Set SCREENS to the screens you want lcdproc to send to LCDd +# lcdproc --help will give you a list of the screens available + +SCREENS="C X" + + + + + +In this example lcdproc will only send information on the CPU usage [C] and system load [X] to the server. + + + + + + + diff --git a/docs/lcdproc-user/contact.docbook b/docs/lcdproc-user/contact.docbook new file mode 100644 index 0000000..8c06456 --- /dev/null +++ b/docs/lcdproc-user/contact.docbook @@ -0,0 +1,100 @@ + +Contact Us + + +Errata + + +Of course LCDproc is not perfect (yet). We do our very best +to improve it, but in some cases we are very much restricted +in our efforts. + + + +The main reason for that is the fact that we do NOT have all +the hardware people have writte. drivers for. Unfortunately +some developers have kind of vanished and don't react to mails +from the mailing list any more. + + + +So, as far as drivers are concerned we rely on YOU as testers. +We have developed elaborate "coding in the dark" skills over the +time. E.g. the CFontz driver has been updated and ported to 0.4.3 +without the developers having the hardware. + + + + + +The LCDproc Mailing List + + +We are a bit lazy about the bug-tracking and whatever stuff +on SourceForge. So, please contact us directly through the mailing +list. + + + +For details on how to subscribe to the list see +http://lcdproc.omnipotent.net/mail.php3. + + + +We like people to subscribe to the list with their real names. +Of course we cannot and do not want to force you to do so. +Anyway, we need to know your name, if you want to contribute code +to LCDproc (legal issues of copyrights). + + + + + +Reporting Bugs + + +Possibly you will find a bug in the LCDproc distribution. +Before reporting this to the mailing list, please respect the following: + + + +Your system should be more or less up to date. This does not mean +that you have to update from GNU/Linux kernel 2.0.x to 2.2.x or from 2.2.x to +2.4.x. But we would like to make sure that your problem is not related to a +known bug in the kernel or maybe your compiler. + +Especially LCDd might need certain privileges to execute +a command. Make sure LCDd HAS the rights to do so. + + +When experiencing problems with LCDd, make sure that your hardware is OK. +E.g. you should make sure that the wireing for your (in this case most +likely parallel) device is correct. + + +Make sure that you use the correct speed settings for your device. +Incorrect speed settings (baud rate) are most likely to produce garbage +scrolling on your display. +Refer to the specifications of your device. If your device needs a speed +setting that is not supported by LCDd send us a mail. +Make sure that you have modified the configuration file according +to your needs and that LCDd actually uses the configuration file. I.e. you might +have to run LCDd with the -c option + + + + +Anyway, no question is too stupid to ask ;) Feel free to ask whatever you want. +Unfortunately replying to mails takes time as well (a damn lot of time). So, if +you want LCDproc to develop faster, please try to solve a problem yourself first. + + + +BUT if you have actually FOUND A BUG we will be quite happy if you let us know. +We NEED YOU as testers and appreciate any feedback. + + + + + + diff --git a/docs/lcdproc-user/drivers.docbook b/docs/lcdproc-user/drivers.docbook new file mode 100644 index 0000000..17384e3 --- /dev/null +++ b/docs/lcdproc-user/drivers.docbook @@ -0,0 +1,15 @@ + +LCDproc Drivers + + +This chapter contains the documentation of each LCDproc driver, +which may include the installation process of the hardware as +well as the configuration of LCDd. + + +&hd44780; +&ppttrouble; +&mtxorb; +&lircin; + + diff --git a/docs/lcdproc-user/drivers/Makefile.am b/docs/lcdproc-user/drivers/Makefile.am new file mode 100644 index 0000000..ef76e87 --- /dev/null +++ b/docs/lcdproc-user/drivers/Makefile.am @@ -0,0 +1 @@ +EXTRA_DIST = hd44780.docbook lircin.docbook mtxorb.docbook ppttrouble.docbook diff --git a/docs/lcdproc-user/drivers/hd44780.docbook b/docs/lcdproc-user/drivers/hd44780.docbook new file mode 100644 index 0000000..29ba79e --- /dev/null +++ b/docs/lcdproc-user/drivers/hd44780.docbook @@ -0,0 +1,1136 @@ + +The HD44780 Driver + + +There are several ways of wiring up the HD44780 devices. Your choice +will probably be governed largely by your ability to wire up each one +and/or a desire to use the device with other programs. + + +The LCDproc HD44780 driver supports the following connections on a +parallel port: + + +4-bit +8-bit (winamp style) +extended 8-bit (LCD + LED bargraph) +serial LPT + + +And supports a PIC-an-LCD connected to a serial port. + + +The driver also lets you use multiple displays as a single virtual +display. For example, a 4, 2 and 1 line display can be used to form a +7 line display. The number of displays is limited by the individual +HD44780 driver. + + + +Connections + + +Common connections for all connectiontypes + + +No matter what connectiontype you choose, you will always need some +connections. They are explaned here. + + + +Power + + +All variants use the same method of obtaining power. i.e., for each LCD: + + + +HD44780: Power Connections + + + +LCD +pin +signal + + + + +1 +GND +(connect to any of pins 18 - 25 of you parallel port) + + +2 ++5V + + + +3 +Vadj +(contrast) + + + +
+ + + +Always double check your power connection, your display will probably +NOT survive a reversely connected supply ! + + + + +There are several ways to get 5V: + + + +Connect to a 5V line intented for disk drives (the red +wire is 5V, black is GND). +Get it from a joystick port (pin 1 and 9 are 5V, 4, 5 +and 12 are GND). It seems that some soundcards can use these lines for +communication, so if you want to use this first check wether it really +gives a 'clean' 5V. +If you don't have a backlight, you can sometimes get +the needed mA's from the LPT port itself. Connect a few diodes from the +data pins to a capacitor and you have the 5V. If it's strong enough is +another question... +Get it from the keyboard connector. I do not recommend +to use this with a backlight, as the keyboard connector is often protected +with a fuse of 100mA or 200mA. + + +
+HD44780: Connecting the contrast adjusting pin (Vadj.) + + + +
+ + + + +Keypad + + +You can connect a keypad with all connection types. The maximum supported +number of keys differs per type. There are several ways to connect the keys +to the input pins. + + + +Direct Keys + + +If you connect a key like sketched below, then you can only connect one key +per input pin. It is a simple solution if you need only few keys. + + +
+HD44780: Direct Keys + + + +
+ + +By default, the following keystrokes are generated by the different keys: + + + +HD44780: Default Keystrokes + + + +X0 +A + + +X1 +B + + +X2 +C + + +X3 +D + + + +
+ + + + +Matrix Keys + + +Using a matrix, we can connect much more keys. To simplify the drawing here, +we replace all switches with an @ symbol: + + +
+HD44780: Single Matrix Key + + + +
+ + +We connect the matrix of keys like this: + + +
+HD44780: Complete Key Matrix + + + +
+ + +As you can see, you need 1 resistor per X line, and 1 diode per Y line. +Lcdproc will presume that you have a keypad with a layout like a telephone +connected, with X and Y lines connected as show. To be more precise, it +assumes this: + + +
+HD44780: Keypad Layout + + + +
+ + +If you only need 10 keys, leave the rest away. However, the lcdproc menu is +controlled by the keystrokes A to D. You should modify and recompile the +driver to get an other keypad layout. + + + +You can buy arrays of keys that are connected like this in the electronics +shop. They usually call it a matrix keypad. To hook it to lcdproc, you +would only need to add the resistors and diodes. + + + +If you want to use just one return line, for example with the serialLpt +wiring, it looks (completely drawn) like this: + + +
+HD44780: One Return Line + + + +
+ + + +If the driver generates keypresses without that you actually press a key, +it might be that the unconnected input lines are picking up +electromagnetic waves from the air. In that case connect the unconnected +input lines (pin 10, 11, 12, 13 and 15 of the LPT) to VCC = 5V. + + + + + + + + +Backlight + + +A small extension allows you to switch the backlight of the display on +and off. At the moment only the 4bit and winamp connection types support +this. The extension uses one output pin, you cannot use that pin for other +functions anymore. The wiring looks like this: + + +
+HD44780: Backlight Wiring + + + +
+ + + +Sometimes the backlight connections are not on the 'main' connector, but on +the side. If that is the case, there is usually NO RESISTOR present to limit +the current through the LEDs. Therefor you should then add a resistor after +the transistor of about 10 ohm (see display documentation). + + + + + +If you want the backlight to light a bit while it's switched 'off', you can +add a resistor bypassing the transistor from e to c, with a value of, say +47ohm or 22ohm. (My 4x20 has an internal resistor of 6ohm, so with 47 ohm +extra it lights at only 1/9th. I like this. Joris.) + + + + + + + + +4-bit + + +This is originally based on "lcdtext" (by Matthias Prinke). + + + +HD44780: 4-bit Pinouts (1) + + + +printer port +LCD + + + + +D0 (2) +D4 (11) + + +D1 (3) +D5 (12) + + +D2 (4) +D6 (13) + + +D3 (5) +D7 (14) + + +D4 (6) +RS (4) + + +D5 (7) +RW (5) (LCD3 - 6) (optional - pull all LCD RW low) + + +D6 (8) +EN (6) + + +D7 (9) +EN2 (LCD2 - 6) (optional) + + + +
+ + +If you want to connect more than two displays to the parallel port then +wire D5 (pin 7) to the enable line (pin 6) of the third LCD. Then for +displays four to seven use: + + + +HD44780: 4-bit Pinouts (2) + + + +printer port +LCD + + + + +STR (1) +EN4 + + +LF (14) +EN5 + + +INIT (16) +EN6 + + +SEL (17) +EN7 + + + +
+ + +The optional keypad can be connected as follows: + + + +HD44780: 4-bit Keypad Pinouts + + + +printer port +LCD + + + + +D0 (2) +Y0 + + +D1 (3) +Y1 + + +D2 (4) +Y2 + + +D3 (5) +Y3 + + +D4 (6) +Y4 + + +D5 (7) +Y5 + + +nSTRB (1) +Y6 + + +nLF (14) +Y7 + + +INIT (16) +Y8 + + +nSEL (17) +Y9 + + + + + + +nACK (10) +X0 + + +BUSY (11) +X1 + + +PAPEREND (12) +X2 + + +SELIN (13) +X3 + + +nFAULT (15) +X4 + + + +
+ + +The optional backlight wiring should be connected to D5, pin 7. + + + + + +8-bit "Winamp" + + +This type of connection should work with winamp. + + +
+HD44780: "Winamp" wiring + + + +
+ + +If you want the display to work with the Winamp plugin, wire nLF (pin 14) +to nRW of your LCD. You can then use the plugin in bidirectional mode (wich +is much faster). With 3 connected LCDs this is not possible. +Note from Benjamin: I haven't tried using winamp while having the third LCD +connected to this line. + + + +The optional keypad can be connected as follows: + + +
+HD44780: "Winamp" wiring - Keypad + + + +
+ + +The optional backlight wiring should be connected to nSEL, pin 17. + + + + + +8-bit "lcdtime" + + +This is originally based on "lcdtime" (by Benjamin Tse +blt@ComPorts.com) and allows you to combine the LCD with a LED +bargraph. The LCD is driven by LCDproc and the LEDs by another program +such as portato. Further details can be obtained from: + + + +http://metalab.unc.edu/pub/linux/system/status/lcdtime-0.2.tar.gz +http://metalab.unc.edu/pub/linux/system/status/meter-0.2.tar.gz +http://metalab.unc.edu/pub/linux/system/status/portato-1.2.tar.gz + + + + +Theoretically this wiring sends the data over twice as slow as the +winamp or ext8bit wirings, because it only sends 4 bits at a time. + + + + +The LCD connections are: + + +
+HD44780: "lcdtime" wiring + + + +
+ + +See the lcdtime tar-ball (above) for full details of the bargraph +connections. + + + +The optional keypad can be connected as follows: + + +
+HD44780: "lcdtime" wiring - keypad + + + +
+ + +The backlight wiring should be attached to nSEL, pin 17. Because the portato +program (mentioned above) also uses this pin to control the bargraph, you +cannot use the backlight control together with the bargraph. + + + + + +Serial LPT + + +This interface uses a handful of wires to interface to the +HD44780. Suitable for high noise, long connections. Designed by +Andrew McMeikan andrewm@engineer.com. The original wiring and +driver can be found at: + + +http://members.xoom.com/andrewmuck + + + +I (Joris) have extended this driver and the wiring a bit. It now supports +keys again (it had earlier supported keys, but some time did not). + + + +Further I have extended the driver and the wiring to be able to run +using 2 instead of 3 output pins. That's even one less pin ! :) + + + +Of course the use of fewer lines than the other wirings can not stay +without drawbacks. In this case the simplicity of the long feeding wires +is compensated by some intelligence in the decoding of the data. If you +have no experience with the soldering iron, I do not recommend to build +this wiring. + + + +OK, so here is the wiring. First of the 'simple' 3 wires version. IC1 is +the shift register, a 4094. Do not forget to connect the 5V to pin 16 and +GND to pin 8 of the IC. + + +
+HD44780: Serial LPT wiring ('simple') + + + +
+ + +The second possible wiring is with 2 output lines. This one is a bit more +complex. If you do not understand the schematic, do not build it. + + +
+HD44780: Serial LPT wiring ('complex') + +o----|R Q6|---------------------o Y6 + | 22k | |/ | |13 + | --- IC1 | Q7|---+ +--o 5 RW + | --- | | | 5V | + | |100p ----------- | O === + | | | | + | === | .-. + | | | |22k + +--------------------------------------+ | | + | '-' + | ___ 11|\ 10 | 5|\ 6 + +--|___|--+----| >o-------------------||----+-----| >o---o 6 EN + 22k | |/ 22p |/ + --- IC1 IC1 + --- + |22p + | IC1=74HCT14 (6x Schmitt trigger inverter) + === + + + 5V O--+-------+------+------+------------------------+-----o 2 VCC + | | | | 13|\ 12 | + | | | +---| >o- | + |100n O 14 O 14 |/ .-. + --- IC1 IC2 | |<---o 3 Vlcd + --- O 7 O 7 1|\ 2 3|\ 4 | |10k + | | | +--| >o- +--| >o- '-' + GND | | | | |/ | |/ | + 18..25 o--------+-------+------+-------+----------+-----+------+-----o 1 GND + | + === GND + +]]> + +
+ + +Serial LPT Keypad + + + +To understand this part of the serialLpt documentation, you also need to +read the keypad section in this document. + + + + +serialLpt wiring supports a keypad. The 3 wires version supports +8 keys, or if you use multiple return lines up to 8 x 5 = 40 lines. The +2 wires version supports 7 keys, or with multiple return lines +7 x 5 = 35 keys. + + +
+HD44780: Serial LPT - Keypad return lines + + + +
+ + +On lines longer than, say a meter, you should buffer the return line(s). +If you only have 1 return line, you can buffer it with two remaining +buffers from the 74HCT14: + + +
+HD44780: Serial LPT - Keypad return lines buffered + +o------| >o---|___|---+---o input pin on LPT port + return |/ |/ 220E | + IC1 IC1 --- + --- 1nF + | + === + +]]> + +
+ + + + +Serial LPT Backlight + + +Also a backlight is suported. You will also need a port from the 74HCT14 for +that. The BL output below should be connected to the BL input in the +backlight section + + +
+HD44780: Serial LPT - Backlight extra circuit + +o----o BL output + LPT-D3 470k | |/ + --- IC1 + --- + |100nF + | + === + +]]> + +
+ + + + + + + +PIC-an-LCD serial device "picanlcd" + + +The PIC-an-LCD module is also supported. It is not connected to the LPT port +but to a serial port, which saves you from a lot of potential problems. +To use it, specify the device to which you have connected the module in the +config file with the Device= setting. The default is /dev/lcd. +It does not support a keypad nor backlight switching. + + + + + + + +Compiling + + +Make sure that the HD44780 files are built when you run configure. This +can be done by specifying "--enable-drivers=all" or by +"--enable-drivers=hd44780". + + + + + +Configuration + + +Since LCDproc 0.4.3 the HD44780 driver can be cnfigured from the configfile. + + + +The [HD44780] section is more or less self-explanatory. Yet, a list of the +possible connection types has proved useful. The following table should make +it clear, how the ConnectionType is to be set. + + + +HD44780: Connection Types + + + +Wiring / Display Type +ConnectionType= + + + + +HD44780 4bit Wiring +4bit + + +HD44780 8bit Wiring ("lcdtime") +8bit + + +HD44780 Serial LPT Wiring +serialLpt + + +HD44780 8bit Wiring "winamp" Style +winamp + + +PIC-an-LCD serial device "picanlcd" +picanlcd + + + +
+ + + +The above table might be outdated, when you read this. +If you suspect this is the case, you might want to have a look at server/drivers/hd44780-drivers.h +which contains the actual translation code. + + + + + + +Running + + +Modify the LCDd.conf file before you run LCDd. In this config file are +detailed instructions on how to configure the HD44780 driver. + + + +Then as usual, start LCDd with the correct config file: + + +E.g. LCDd -c ./LCDd.conf + + +If you want to override the driver selection in LCDd.conf then use: + + +LCDd -c ./LCDd.conf -d HD44780 + + +If you use this, the HD44780 driver will read the options from the config +file anyway. + + + + + +Miscellania + + +This text has originally been taken from a message by Bill Farrow +bfarrow@arrow.bsee.swin.edu.au. + + + +Updated February 2000, Benjamin Tse blt@ComPorts.com + + + +Updated October 2001, Joris Robijn joris@robijn.net + + + +Converted to docbook March 2002, Rene Wagner reenoo@gmx.de + + + +Updated April 2002, Rene Wagner reenoo@gmx.de + + + + diff --git a/docs/lcdproc-user/drivers/lircin.docbook b/docs/lcdproc-user/drivers/lircin.docbook new file mode 100644 index 0000000..6f81411 --- /dev/null +++ b/docs/lcdproc-user/drivers/lircin.docbook @@ -0,0 +1,172 @@ + +The lircin Driver + + +The lircin driver enables you to use any IR remote control +that works with LIRC to control the LCDproc server +(LCDd) +and/or clients that can handle input. + + +Of course you need a working LIRC setup. Refer to +http://www.lirc.org for more +information on LIRC itself. + + + +Checking Your LIRC Setup + + +Basically all you need is a running lircd. +And of course you have to start lircd +as root. + + +Also, make sure that the permission of /dev/lircd +are correct. + + + + + +Build LCDd with the lircin Driver + + +You need to add lircin to the --enable-drivers=... list. + + + +Then simply run make. + + + + + +Configure LCDd to Use the lircin Driver + + +First of all you need to activate the driver by adding a Driver=lircin line +to your LCDd.conf + + + +<filename>LCDd.conf</filename>: Activate the lircin driver + + +Driver=mtxorb +Driver=lircin + + + + + +This activates the mtxorb driver as the output driver and the lirc driver +as the input driver. + + + +Then you have to modify the [lircin] section of your +LCDd.conf. + + + +<filename>LCDd.conf</filename>: The [lircin] Section + + +The [lircin] section of the LCDd.conf contains the +settings for the lircin LCDproc driver. + + + + +lircrc= + + +Normally all LIRC clients scan the file ~/.lircrc. +However, you might want to have a separate file to configure the +LCDproc lircin driver only. + + +This option enables you to specify the file you want the lircin +driver to scan. + + + + +prog= + + +All LIRC keys are assigned to a program using the prog=... option +in the ~/.lircrc (or the file you have specified +with lircrc=...). + + +The prog=... line must be the same as in your ~/.lircrc +(or the file you have specified with lircrc=...). + + + + + + + + + + + +Modify Your <filename>~/.lircrc</filename> + + +As mentioned above you can either modify the ~/.lircrc +or use a separate file for the lircin LCDproc driver (See +above for details). + + + +No matter which file you use, you have to add at least the following +lines to the file: + + + +<filename>~/.lircrc</filename>: Specify the keys for the lircin driver + + +begin + prog = lcdd + button = 2 + config = A +end + +begin + prog = lcdd + button = 4 + config = B +end + +begin + prog = lcdd + button = 6 + config = C +end + +begin + prog = lcdd + button = 8 + config = D +end + + + + + + +Which buttons you specify here depends on your RC and your LIRC configuration. +Anyways, config=A/B/C/D is neccessary to control the server menu of LCDd. +Of course you can define other keys. Those keys will not be handled by the +server but sent to a client. Refer to the documentation of the client you want +to use, to find out which keys are neccessary for that client. + + + + + diff --git a/docs/lcdproc-user/drivers/mtxorb.docbook b/docs/lcdproc-user/drivers/mtxorb.docbook new file mode 100644 index 0000000..4cf3f55 --- /dev/null +++ b/docs/lcdproc-user/drivers/mtxorb.docbook @@ -0,0 +1,221 @@ + +The Matrix Orbital Driver (MtxOrb) + + + This section covers the installation process for the Matrix Orbital LCD + module intended for use with LCDproc. + + + We will examine the installation process of the hardware in + small steps, as it is vitally important to pay close attention to detail during + hardware installation to avoid damaging equipment. + + + + Matrix Orbital LCD Modules + + LCDproc was born out of original tinkering by William Ferrell with + one of these LCD modules. Their ease of installation and use (as well + as the amazing amount of patience demonstrated by the folks at + Matrix Orbital whilst William figured things out) meant one less thing + to worry about during the early stages of LCDproc's life. + + + These 20x4 alphanumeric modules are connected via standard DB-9 cabling and + connectors. They draw either 5V or 12V, depending on the module purchased, + and are attached with a standard floppy cable connector (with a slightly + modified wire configuration). + + + Once connected, using them is a breeze. They can operate at any number of + different baud rates and serial configurations, but normally they run at + 19,200 baud, 8-N-1, making them quite quick. Sending ASCII to the module + will make it simply display that text at its current cursor position. The + module has a built-in BIOS that recognizes commands (sent by transmitting a + single-byte "marker" signifying that a command is on the way, followed by + the single-byte command character itself along with any parameters, if needed) + allowing the programmer to clear the screen, position the cursor anywhere, + define custom characters (up to 8 at a time), draw bar graphs and large numbers, + change the LCD's contrast, and so on. + + + The BIOS included also implements line-wrapping (i.e. writing past the + twentieth character on the first row will automatically move the cursor + to the first character on the second row), and screen scrolling (i.e. + writing past the twentieth character on the fourth row causes the whole + screen to scroll up one row, clearing the fourth line and positioning the + cursor at the first character on that line). + + + These modules are fast. Using the auto-line-wrap feature and disabling + the auto-scrolling feature, the screen can be updated thirty times per + second if *every* character on the screen is changed. If updating less + than the whole screen, the LCD can update faster than can be seen by + the human eye. This, of course, more than meets LCDproc's needs. + + + + Matrix Orbital Hardware Installation + + Regardless of what specific type of hardware you intend to use with LCDproc, + installation is usually straightforward, and requires only a few steps. Regardless, + you must use caution while working inside your computer system or with any hardware + attachments. + + + + Installing new hardware inside a computer system can be dangerous to both + system components and the installer. Use caution whenever adding a component + to the inside of your system, altering a power cable, or physically mounting + a device inside a computer system. + + + When installing hardware inside a computer, make sure it's turned off and that + its power is disconnected. This is especially important when making changes to + power cables (as some LCD modules require). + + + + Matrix Orbital LCD/VFD Module Installation + + The LCD and VFD modules from Matrix Orbital are relatively straightforward + to install. With a small, regular (flat-head) screwdriver, a spare floppy drive + power cable, and a bit of luck, installation will take less than an hour. + + + These installation instructions assume that you are installing the module into + a PC or PC-style system (one with AT- or ATX-compliant power cabling) and that + you have some idea of where you intend to permanently mount the module. For + mounting ideas and tips, refer to the section "Mounting" below. + + + Before you start + + Your Matrix Orbital LCD or VFD module should be clearly marked with an + indication of the module's power requirements. It should be either a 5 volt + or 12 volt unit. You should have this information available before proceeding. + + + + Power Cable Modification + + The first step in installing the module is making the necessary modifications + to a floppy drive power cable in order to provide power to the module. The + modifications must be made based on the module's power requirements -- either + 5V or 12V -- depending on which module you purchased. + + + A standard floppy drive power cable has a smaller connection than a "normal" + PC power connector. However, like a "normal" power connector, it has four + wires: one yellow, one red, and two black. The red wire provides +5V power, and + is "hot" or live when the system is powered up. The yellow wire provides +12V + power, and is also hot when the system is powered up. Both black wires are + ground. + [TODO: INCLUDE A FIGURE HERE SHOWING A "STANDARD" FLOPPY CONNECTOR] + + + One of the hot wires and one of the black wires will not be needed for your + module's power connection; they will be completely removed when the power cable + modification is complete. + + + + Do NOT make this modification to a power cable attached to a running + system! Electrocution resulting in personal injury and/or damage to the + system can result. + + + + Using a regular screwdriver, press down the small metal locking flap of one + of the two black wires on the small end of the cable, and pull the black wire + from the connector. Using a pair of needle-nose pliers, squeeze the other end + of the same black wire, and pull it out of the large end of the cable. This + black wire can be set aside; it will not be used for the module's power + connection. Either wire can be safely removed; you may safely remove either + wire. + [TODO: INCLUDE A FIGURE HERE SHOWING THIS PROCESS] + + + Next, using the same procedure, remove the unneeded hot wire. If your module + is 5V, you do not need the yellow (+12V) wire. Conversely, if your module is + 12V, you do not need the red (+5V) wire. The removed wire can be set aside; + it will not be used for the module's power connection. + [TODO: INCLUDE A FIGURE HERE] + + + The floppy power connector should now have only two wires attached to it. + Leave the larger end alone from now on; these connections are correct (the + larger end connects to your system's power mains). Move the two remaining wires + to the outside connectors on the small end of the cable. Orientation does not + particularly matter here; the connector will fit on the module's receptacle + in either orientation. + [TODO: A FIGURE HERE] + + + You should now have a properly modified power connector. When physically + attaching this connector to the module, the black (ground) lead should be + connected to the pin labelled GND, while the colored (+5V/+12V) lead should + be connected to the pin labelled +5V/+12V. + + + Test the power connection before connecting the data line or mounting the + module. Connect the module to the power connector, and the connector to your + system's power mains. Turn the system on. + + + + If the module does not immediately display its initial BIOS screen and light + up its backlight (or light up the screen if a VFD module is being used), + immediately power down the system, disconnect the module + and connector, and double-check the modification before trying again. Do NOT + leave the system on if the module does not immediately respond; module or + system damage could result. + + + + When the LCD powers up and displays its initial BIOS screen, you've gotten the + power connection wired properly and can now properly mount the module and make + its final connections. Matrix Orbital Corporation sells a PC bay insert mount + for the 20x4 and 20x2 modules (LCDproc, however, only supports the 20x4 at + present). The inserts provide an easy means of mounting the LCD modules inside + a PC using one (for the 20x2) or two (for the 20x4) 5 1/4" bays. + + + + Describing how to physically mount the module in a PC case is beyond the + scope of this document; LCDproc's website contains more detailed mounting + information and examples. + + + + + Serial Connection + + The LCD module uses a standard DB9 serial connector. You can attach the module + to your system using a direct cable to the motherboard, or by removing one of + your system's serial ports from the back of the case, then connecting it to a + standard serial cable to the module. + + + While connecting the serial cable to the module, be sure to configure the + module's serial interface settings. Typically, setting the module to its fastest + setting (19,200 baud, 8-N-1) is recommended. The speed settings can + be configured from the config file /etc/LCDd.conf. If not specified in the config file, + the Matrix Orbital module driver in LCDproc default to use these settings. + + + + + +Copyright + + +This section was originally part of the lcdproc.sgml file by William W. Ferrell wwf@splatwerks.org + + + +Slightly modified in order to include it in this document March 2002, Rene Wagner reenoo@gmx.de + + + + diff --git a/docs/lcdproc-user/drivers/ppttrouble.docbook b/docs/lcdproc-user/drivers/ppttrouble.docbook new file mode 100644 index 0000000..bca8008 --- /dev/null +++ b/docs/lcdproc-user/drivers/ppttrouble.docbook @@ -0,0 +1,187 @@ + +Parallel Port Troubleshooting + + +Unfortunately attaching an LCD module to a parallel port is not +trivial. + + +In most cases it requires soldering abilities and basic knowledge +of electronics. + + +The following hints might be helpful: + + +Check The Wiring + +Wiring errors can easily be made. If you are unexperienced +with the soldering iron better have someone solder it for +you. Display modules are sensitive to electro static +discharges, so touch an earthed surface (computer case, +water pipes...) before you handle these. + + + +Power Source Unregulated / Noisy + +Make sure your power supply delivers steady 5 Volts with- +out noise or interruptions. The bare wall plug in trans- +former is not suitable, though you can make it stabilized +by adding an 7805 and a few capacitors. +Some noise induced in the supply lines my be tricky to +track, even if you have an oscilloscope. + + + +Ground Lift + +The power supply wires and especially the GND wires should +be a little thicker than the other wires. If GND is not +thick enough (or not existent, see 1) the resistance of the +wire may cause differing GND potentials in the circuit. +This may lead to strange display behaviour. It may also be +wise to solder a 100nF capacitor directly to the GND and +VDD pins of the display. + + + +Latchup + +Never let the supply voltage get much below the io signal +voltage. It may lead to a latchup condition which will +destroy the controller chip on the display. + + + +Contrast + +If you don't see anything on your display it may be that +your contrast voltage is set wrong. Turn your contrast +potentiometer all the way to the end connected to GND. +Contrast is highest then. + + +Beware + +The module you got so ultra cheap may be an +enhanced temperature model which needs a negative +contrast voltage for sufficient contrast - see chapter +99 on how to make negative voltage. + + + + +Parallel Port Voltage + +Many modern mainboards and especially notebooks will not +nearly output 5V for a logic H as the older parallel ports +did, because the operating voltage of computers is lower than +5V these days. I have measured voltages between 2.5V and 4V +for logic H, which is barely within specification of the +HD44780. If you account RCL of your cable, this may not be +enough and can cause unreliable operation. + + + +Enable Signal Rise Time + +If you ever read the HD44780 datasheet you will notice that +somewhere in the 'signal timing' table is written: 'Enable +Signal Rise Time max. 20nS'. That means the Voltage on the +HD44780 pin called 'Enable' has to rise from 0 Volts to 5 +Volts within 20 Nanoseconds and the other way round. They +should better print that in big fat red letters, because +most HD44780s are really picky about the enable signal rise +time. + + +That is a Problem: If you count together the bad driving +characteristics of the parallel port combined with the +capacitance of flat ribbon cable you may easily get an +order of magnitude slower rise time. +Therefore you should only use really short cable ( shorter +than 50cm) for connecting the display to the parallel port. +It may also be useful to use pull-up resistors on the display +module or a schmitt-trigger. + + + +The rise time of a digital output can (usually) not be +altered by Software. + + + + +EMI + +The cable from the parallel port to the display may +be sensible to electromagnetic interference and may emit +electromagnetic radiation. If you place your cellphone near +the cable, you may get unexpected display readings, on +the other hand your house neighbour may not be able to listen +to his/her favourite radio station any more - so better use +shielded cable and put the display in a metallic case, perhaps +a computer case. + + + +One or Two Black Lines + +If you see one or two black lines on the display it means +nothing more than that the display is powered and contrast +voltage is present. If one or two black lines appear the +controller has not been reset properly by the on chip power +on reset generator. No need to worry - it will be reset by +the LCDd software. But if the +black line will not disappear +although the wiring is working, the controller on the display +may be defective. + + + +Software Too Fast + +If you have a super GHz computer it may happen that the signal +timing generated by LCDd is too fast. +Adjust DELAYMULT in the +source file to a bigger value. Parallel port wirings usually +don't permit to read back the busy flag of the controller chip, +so timing must be adjust so that the controller never is busy. + + + +LED Backlight + +Check whether you need a resistor for your LED Backlight and +which value it should have. If you forget the required resistor +the backlighting LEDs might become hot and draw excessive +current. + + + +HD44780 Compatible + +The original HD44780 controller that we advertise to support +has become the industry standard for alphanumeric character +displays. The original HD44780 is out of production. It has +many successors from many manufactures, which sometimes won't +tell you that their chips are 'compatible'. + + +To name a few: KS 0066, KS 0070, KS 0076, LC 7985, NT 3881, +SED 1278, ST 7066 ... + + + +Miscellania + +This text has originally been taken from a message by +Robin Adams robin@adams-online.de + + +Converted to docbook and slightly modified May 2002, Rene Wagner reenoo@gmx.de + + + + diff --git a/docs/lcdproc-user/how-to-obtain.docbook b/docs/lcdproc-user/how-to-obtain.docbook new file mode 100644 index 0000000..6373c44 --- /dev/null +++ b/docs/lcdproc-user/how-to-obtain.docbook @@ -0,0 +1,220 @@ + +How to Obtain LCDproc + + +Versioning + + +At the time of writing there were four versions of LCDproc floating around on the +Internet. + + + + + +LCDproc 0.4.1 + + +LCDproc 0.4.1 was the last "stable" release of LCDproc. It still uses the old +command line configuration. + + + +There are known security problems with LCDproc 0.4.1. A remote exploit is possible. +An attacker can make use of some buffer-overflows in the client communication +code of LCDd, in order to get root access to your system. +Therefore running LCDproc 0.4.1 is NOT RECOMMENDED! + + + + + + +LCDproc 0.4.2 + + +LCDproc 0.4.2 was meant to be the next stable release of LCDproc. As 0.4.1 +it uses the old command line configuration. + + + +The known issues about 0.4.1 had been fixed. Unfortunately the guy who had the last pending +patches on his box kind of "vanished" from the LCDproc mailing list. +Of course you can get 0.4.2 from CVS. BUT its current state is unknown. + + + + + + +LCDproc 0.4.3 + + +LCDproc 0.4.3 is the current stable release of LCDproc. It no longer uses the old +command line configuration, but introduces the configuration file /etc/LCDd.conf. +As well the driver API has slightly changed, which should not +make older drivers incompatible, but might cause some trouble. As well the way +LCDd reports messages (including error messages) has changed. + + + +Even though LCDproc 0.4.3 is the most stable version we can offer, it is still not perfect. + + + + + + +LCDproc 0.4.4 + + +LCDproc 0.4.4 will be the next stable release of LCDproc. + + + +The 0.4.x branch will only be slightly updated. E.g. we plan better support +of lcdproc (the client) for *BSD. Yet, the active development will move to +0.5 now. + + +As 0.5 will not be stable in the near future, we may also work on porting drivers +from 0.4.1 to 0.4.4 on demand. We do not have all the hardware LCDd supports. So, we +only work on drivers that can be tested by YOU. + + +As well, the development and inclusion of new drivers is possible. + + + + + + + +LCDproc 0.5 + + +LCDproc 0.5 is the developement version of LCDproc. Everything is possible ;) Drivers can already be +loaded at runtime. We will also work on client supplied menus and other nifty stuff. + + + +From time to time LCDproc 0.5 might not even compile due to drastic changes. +You have been warned! + + +Furthermore older drivers will NOT work with LCDproc 0.5 AT ALL! +Feel free to port a driver that has not been ported to 0.5 yet ;) + + + + + + + + + + +Download Last Day's CVS Version of LCDproc as a Tarball + + +There are nightly distributions of the CVS branches of LCDproc. You can download them from +http://lcdproc.sourceforge.net/nightly/ + + + +To extract the files run either + + + +$ tar xvfz lcdproc-CVS-*.tar.gz + + + +or + + + +$ bunzip2 -c lcdproc-CVS-*.tar.bz2 | tar xv + + + + + +Download The Latest Version of LCDproc from CVS + + +Of course you can download the latest stuff from CVS via anonymous login. + + + +Create a "cvs" directory somewhere on your machine (not really neccessary but useful): + + + +$ mkdir ~/cvs +$ cd ~/cvs + + + +Login to CVS: + + + +$ cvs -d:pserver:anonymous@cvs.lcdproc.sourceforge.net:/cvsroot/lcdproc login + + + +(Hit enter when prompted for a password.) + + + +Get the files from CVS: + + + +$ cvs -d:pserver:anonymous@cvs.lcdproc.sourceforge.net:/cvsroot/lcdproc checkout -r stable-0-4-3 lcdproc + + + +Once you've done that and want to update the downloaded files to the latest stuff +you can use the "update" command of CVS (Make sure you have logged in to CVS first.): + + + +$ cvs -d:pserver:anonymous@cvs.lcdproc.sourceforge.net:/cvsroot/lcdproc update -r stable-0-4-3 lcdproc + + + +Now that you have downloaded the files you can prepare them for compiling, but first +you should (you don't have to) copy them to another place on your machine: + + + +$ mkdir ~/lcdproc-cvs +$ cp -f -R ~/cvs/lcdproc ~/lcdproc-cvs/`date +%Y%m%d` +$ cd ~/lcdproc-cvs/`date +%Y%m%d` + + + + + + +apt-get + + +Debian GNU/Linux users can get the debian package of LCDproc, which is in the unstable and testing distributions. + + + +Provided apt-get is configured properly. You should be able to install the package running: + + + +$ su +Password: top secret +# apt-get install lcdproc + + + + + diff --git a/docs/lcdproc-user/installation.docbook b/docs/lcdproc-user/installation.docbook new file mode 100644 index 0000000..57ccff0 --- /dev/null +++ b/docs/lcdproc-user/installation.docbook @@ -0,0 +1,188 @@ + +Installation + + +Build LCDproc + + +Now that you have downloaded the LCDproc distribution you can +start building it. + + + + +If you have installed the debian package with apt-get (or another +debian tool), you can skip this this chapter. + + + + +If you're building this version from CVS, you'll need +autoconf, automake, aclocal & autoheader installed. + + + +If you have autoconf and friends, run: + + + +$ sh autogen.sh + + + +This produces the configure script and supporting files. It has allready +been run if you using the tarball distribution. + + + +Once the above command has run, the rest is pretty standard: + + + +$ ./configure --help + + + +Read about the options, figure out what to use. + + + +$ ./configure --prefix=/usr/local --enable-drivers=ncurses,cfontz + + + +Be sure to replace /usr/local with the prefixdir you want (e.g. /usr +for RedHat) and ncurses,cfontz with comma-separated list +of drivers you want. + + + +$ make + + + +Congratulations: You have just compiled your version of LCDproc ;) + + + + + +Install LCDproc Directly From The Sources + + +If you want to install LCDproc more or less permanently you +can run: + + + +$ su +Password: top secret +# make install + + + + +make install is absolutely OPTIONAL +You can also run LCDproc directly from the source directory. See +below for details. + + + + + + +Generate And Install Packages of LCDproc + + +As an alternative (which is actually better ;) to installing +directly from the sources you can generate packages using the +packaging tool EPM. + + + +First of all you may need to download EPM from +http://www.easysw.com/epm/ +and install it according to the instructions that are included +in its source distribution. + + +Debian users (who do not want to download the official debs via apt-get) +can of course use the debian package of epm: + + + +# apt-get install epm + + + + +There are of course other and maybe better ways to generate +packages for your system. The reason for us to choose EPM +was that it provide the developers with a tool that makes it +possible to write one list file for all platforms defining +what the resulting package is meant to look like. This way we +do not have to learn all the package managing tools of the +different platforms that are supported by LCDproc. + + + + +To generate an LCDproc package follow these instructions: + + + + +It is of certain importance that you have run ./configure with +the correct pathname settings for your system. Otherwise the +resulting package will install the files in the wrong directories. + + + + +$ epm -v -f native LCDproc + + + + +Generating an RPM package as a non-root user will fail, RPM wants +to generate the files from the tree under /usr/src/RPM, +which you do not have write access to as a non-root user. +If you want to generate the package as a non-root user anyway, you may +want to follow these instructions. + + + + +A workaround for the described problem is creating a file named +~/.rpmmacros +which contains: + + + + + + + + +~/rpm must contain the same tree usually found under +/usr/src/RPM + + + + +Unfortunately epm does not read ~/.rpmmacros +and of course returns warnings. +Don't worry! That's OK ;) + + + +In order to actually install the generated package follow the instructions +in your system's manual. + + + + + + diff --git a/docs/lcdproc-user/introduction.docbook b/docs/lcdproc-user/introduction.docbook new file mode 100644 index 0000000..7f51d09 --- /dev/null +++ b/docs/lcdproc-user/introduction.docbook @@ -0,0 +1,145 @@ + +Introduction + + +About this Document + + +This document was meant as a tutorial for LCDproc users. It tries to introduce +you into the world of LCDproc giving you an overview of the project. +After reading this document you will be able to set up your own LCDproc'ed system. + + + +Please note that this document is still "under construction". We hope to finish it +until the final release of LCDproc, which will probably take place in May or June 2002. +If you run into any trouble feel free to write to the LCDproc mailing list. +See http://lcdproc.omnipotent.net/mail.php3 +for details on how to subscribe to the list. + + +Therefore you might want to have a look at http://lcdproc.sourceforge.net/docs/, +to get the latest version of this document (, unless you want to generate it yourself from the +docbook files in the CVS). + + + +This document was written for LCDproc 0.4.3. At the time of writing there had already +been the "LCDproc User's Guide" written by William W. Ferrel in 1999. His version covered +an early version of LCDproc and therefore concentrated on Matrix Orbital displays. + + + +William's document was "recycled" for the description of the Matrix Orbital display driver +and for other parts of this document. + + + +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. + + + + + +What is LCDproc? + + +LCDproc is a client/server suite including drivers for all kinds of +nifty LCD displays. + + +The server 'LCDd' makes it possible to display text and other data on +an LCD display. As well LCDd can handle certain input devices. + + +Support for devices is added by drivers. We distinguish between output +and input drivers. +LCDd currently supports only one single output driver, which may at the +same time handle input. Nevertheless several input (only) drivers are +supported. + +Currently there are drivers for several serial devices: +Matrix Orbital, Crystal Fontz, Bayrad, LB216, LCDM001 (kernelconcepts.de), +Wirz-SLI and PIC-an-LCD; and some devices connected to the LPT port: +HD44780, STV5730, T6963, SED1520 and SED1330. +There are input (only) drivers for LIRC and joysticks. + + +Clients can connect to LCDd through common sockets. + + +Various clients are available. The "main" client +lcdproc, which is shipped with the LCDproc +distribution, can display things like CPU load, system load, memory +usage, uptime, and a lot more. + + + + + +The LCDproc Server - LCDd + + +LCDd is one of those well known *NIX daemons. +BUT it's not just *one* daemon. It's the one that is supposed to drive +your LCD ;) + + + +LCDd can either be run from the command line +or automatically by the init scripts shipped with the distribution. + + + +As other daemons, LCDd has to be configured. +In this respect a lot has changed since LCDproc 0.4.1. While LCDd retrieved +all its configuration settings from the command line in 0.4.1, it now has a +configuration file, which is normally /etc/LCDd.conf. + + + + + +The LCDproc "Main" Client - lcdproc + + +While LCDd only offer the functionality of +displaying text on a display, lcdproc actually +retrieves data worth displaying. + + + +lcdproc gets its information from the +/proc filesystem. + + + +lcdproc can connect to an LCDproc +server either on the local system or on a remote system as long as it +is reachable. It extracts the same statistics regardless of where it +sends this information. The statistics it gathers include CPU +utilization, memory utilization, disk utilization, network utilization, +system uptime, time, and date, and so on. It displays this information +in assorted ways, and can be tailored to taste. + + + + + +Other LCDproc Clients + + +As it is rather simple to write an LCDproc client, you can find various +clients on the Internet. + + +Unfortunately we cannot provide a list of LCDproc clients (yet). So, have +fun searching google or +freshmeat. Simply type 'lcdproc' +for the keyword. + + + + + diff --git a/docs/lcdproc-user/lcdproc-user.docbook b/docs/lcdproc-user/lcdproc-user.docbook new file mode 100644 index 0000000..bab6dcc --- /dev/null +++ b/docs/lcdproc-user/lcdproc-user.docbook @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + +]> + + + +&bookinfo; + +&introduction; +&how-to-obtain; +&installation; +&configuration; +&drivers; +&running; +&contact; +&license; + + diff --git a/docs/lcdproc-user/license.docbook b/docs/lcdproc-user/license.docbook new file mode 100644 index 0000000..ec33470 --- /dev/null +++ b/docs/lcdproc-user/license.docbook @@ -0,0 +1,464 @@ + +GNU Free Documentation License + + + + + + +Version 1.1, March 2000 + +
+Copyright (C) 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +
+ + +PREAMBLE + +The purpose of this License is to make a manual, textbook, + or other written document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by + others. + +This License is a kind of "copyleft", which means that + derivative works of the document must themselves be free in the + same sense. It complements the GNU General Public License, which + is a copyleft license designed for free software. + +We have designed this License in order to use it for manuals + for free software, because free software needs free documentation: + a free program should come with manuals providing the same + freedoms that the software does. But this License is not limited + to software manuals; it can be used for any textual work, + regardless of subject matter or whether it is published as a + printed book. We recommend this License principally for works + whose purpose is instruction or reference. + + + +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that + contains a notice placed by the copyright holder saying it can be + distributed under the terms of this License. The "Document", + below, refers to any such manual or work. Any member of the + public is a licensee, and is addressed as "you". + +A "Modified Version" of the Document means any work + containing the Document or a portion of it, either copied + verbatim, or with modifications and/or translated into another + language. + +A "Secondary Section" is a named appendix or a front-matter + section of the Document that deals exclusively with the + relationship of the publishers or authors of the Document to the + Document's overall subject (or to related matters) and contains + nothing that could fall directly within that overall subject. + (For example, if the Document is in part a textbook of + mathematics, a Secondary Section may not explain any mathematics.) + The relationship could be a matter of historical connection with + the subject or with related matters, or of legal, commercial, + philosophical, ethical or political position regarding + them. + +The "Invariant Sections" are certain Secondary Sections + whose titles are designated, as being those of Invariant Sections, + in the notice that says that the Document is released under this + License. + +The "Cover Texts" are certain short passages of text that + are listed, as Front-Cover Texts or Back-Cover Texts, in the + notice that says that the Document is released under this + License. + +A "Transparent" copy of the Document means a + machine-readable copy, represented in a format whose specification + is available to the general public, whose contents can be viewed + and edited directly and straightforwardly with generic text + editors or (for images composed of pixels) generic paint programs + or (for drawings) some widely available drawing editor, and that + is suitable for input to text formatters or for automatic + translation to a variety of formats suitable for input to text + formatters. A copy made in an otherwise Transparent file format + whose markup has been designed to thwart or discourage subsequent + modification by readers is not Transparent. A copy that is not + "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include + plain ASCII without markup, Texinfo input format, LaTeX input + format, SGML or XML using a publicly available DTD, and + standard-conforming simple HTML designed for human modification. + Opaque formats include PostScript, PDF, proprietary formats that + can be read and edited only by proprietary word processors, SGML + or XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML produced by some word + processors for output purposes only. + +The "Title Page" means, for a printed book, the title page + itself, plus such following pages as are needed to hold, legibly, + the material this License requires to appear in the title page. + For works in formats which do not have any title page as such, + "Title Page" means the text near the most prominent appearance of + the work's title, preceding the beginning of the body of the + text. + + + +VERBATIM COPYING + +You may copy and distribute the Document in any medium, + either commercially or noncommercially, provided that this + License, the copyright notices, and the license notice saying this + License applies to the Document are reproduced in all copies, and + that you add no other conditions whatsoever to those of this + License. You may not use technical measures to obstruct or + control the reading or further copying of the copies you make or + distribute. However, you may accept compensation in exchange for + copies. If you distribute a large enough number of copies you + must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated + above, and you may publicly display copies. + + + +COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more + than 100, and the Document's license notice requires Cover Texts, + you must enclose the copies in covers that carry, clearly and + legibly, all these Cover Texts: Front-Cover Texts on the front + cover, and Back-Cover Texts on the back cover. Both covers must + also clearly and legibly identify you as the publisher of these + copies. The front cover must present the full title with all + words of the title equally prominent and visible. You may add + other material on the covers in addition. Copying with changes + limited to the covers, as long as they preserve the title of the + Document and satisfy these conditions, can be treated as verbatim + copying in other respects. + +If the required texts for either cover are too voluminous to + fit legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + +If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a publicly-accessible + computer-network location containing a complete Transparent copy + of the Document, free of added material, which the general + network-using public has access to download anonymously at no + charge using public-standard network protocols. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + +It is requested, but not required, that you contact the + authors of the Document well before redistributing any large + number of copies, to give them a chance to provide you with an + updated version of the Document. + + + +MODIFICATIONS + +You may copy and distribute a Modified Version of the + Document under the conditions of sections 2 and 3 above, provided + that you release the Modified Version under precisely this + License, with the Modified Version filling the role of the + Document, thus licensing distribution and modification of the + Modified Version to whoever possesses a copy of it. In addition, + you must do these things in the Modified Version: + + +Use in the Title Page + (and on the covers, if any) a title distinct from that of the + Document, and from those of previous versions (which should, if + there were any, be listed in the History section of the + Document). You may use the same title as a previous version if + the original publisher of that version gives permission. + + +List on the Title Page, + as authors, one or more persons or entities responsible for + authorship of the modifications in the Modified Version, + together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than + five). + + +State on the Title page + the name of the publisher of the Modified Version, as the + publisher. + + +Preserve all the + copyright notices of the Document. + + +Add an appropriate + copyright notice for your modifications adjacent to the other + copyright notices. + + +Include, immediately + after the copyright notices, a license notice giving the public + permission to use the Modified Version under the terms of this + License, in the form shown in the Addendum below. + + +Preserve in that license + notice the full lists of Invariant Sections and required Cover + Texts given in the Document's license notice. + + +Include an unaltered + copy of this License. + + +Preserve the section + entitled "History", and its title, and add to it an item stating + at least the title, year, new authors, and publisher of the + Modified Version as given on the Title Page. If there is no + section entitled "History" in the Document, create one stating + the title, year, authors, and publisher of the Document as given + on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + + +Preserve the network + location, if any, given in the Document for public access to a + Transparent copy of the Document, and likewise the network + locations given in the Document for previous versions it was + based on. These may be placed in the "History" section. You + may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + + +In any section entitled + "Acknowledgements" or "Dedications", preserve the section's + title, and preserve in the section all the substance and tone of + each of the contributor acknowledgements and/or dedications + given therein. + + +Preserve all the + Invariant Sections of the Document, unaltered in their text and + in their titles. Section numbers or the equivalent are not + considered part of the section titles. + + +Delete any section + entitled "Endorsements". Such a section may not be included in + the Modified Version. + + +Do not retitle any + existing section as "Endorsements" or to conflict in title with + any Invariant Section. + + +If the Modified Version includes new front-matter sections + or appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + +You may add a section entitled "Endorsements", provided it + contains nothing but endorsements of your Modified Version by + various parties--for example, statements of peer review or that + the text has been approved by an organization as the authoritative + definition of a standard. + +You may add a passage of up to five words as a Front-Cover + Text, and a passage of up to 25 words as a Back-Cover Text, to the + end of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by + this License give permission to use their names for publicity for + or to assert or imply endorsement of any Modified Version. + + + +COMBINING DOCUMENTS + +You may combine the Document with other documents released + under this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice. + +The combined work need only contain one copy of this + License, and multiple identical Invariant Sections may be replaced + with a single copy. If there are multiple Invariant Sections with + the same name but different contents, make the title of each such + section unique by adding at the end of it, in parentheses, the + name of the original author or publisher of that section if known, + or else a unique number. Make the same adjustment to the section + titles in the list of Invariant Sections in the license notice of + the combined work. + +In the combination, you must combine any sections entitled + "History" in the various original documents, forming one section + entitled "History"; likewise combine any sections entitled + "Acknowledgements", and any sections entitled "Dedications". You + must delete all sections entitled "Endorsements." + + + +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and + other documents released under this License, and replace the + individual copies of this License in the various documents with a + single copy that is included in the collection, provided that you + follow the rules of this License for verbatim copying of each of + the documents in all other respects. + +You may extract a single document from such a collection, + and distribute it individually under this License, provided you + insert a copy of this License into the extracted document, and + follow this License in all other respects regarding verbatim + copying of that document. + + + +AGGREGATION WITH INDEPENDENT WORKS +A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, does not as a whole count as a + Modified Version of the Document, provided no compilation + copyright is claimed for the compilation. Such a compilation is + called an "aggregate", and this License does not apply to the + other self-contained works thus compiled with the Document, on + account of their being thus compiled, if they are not themselves + derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to + these copies of the Document, then if the Document is less than + one quarter of the entire aggregate, the Document's Cover Texts + may be placed on covers that surround only the Document within the + aggregate. Otherwise they must appear on covers around the whole + aggregate. + + + +TRANSLATION + +Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires + special permission from their copyright holders, but you may + include translations of some or all Invariant Sections in addition + to the original versions of these Invariant Sections. You may + include a translation of this License provided that you also + include the original English version of this License. In case of + a disagreement between the translation and the original English + version of this License, the original English version will + prevail. + + + +TERMINATION +You may not copy, modify, sublicense, or distribute the + Document except as expressly provided for under this License. Any + other attempt to copy, modify, sublicense or distribute the + Document is void, and will automatically terminate your rights + under this License. However, parties who have received copies, or + rights, from you under this License will not have their licenses + terminated so long as such parties remain in full + compliance. + + + +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised + versions of the GNU Free Documentation License from time to time. + Such new versions will be similar in spirit to the present + version, but may differ in detail to address new problems or + concerns. See http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing + version number. If the Document specifies that a particular + numbered version of this License "or any later version" applies to + it, you have the option of following the terms and conditions + either of that specified version or of any later version that has + been published (not as a draft) by the Free Software Foundation. + If the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + + + +How to use this License for your documents + +To use this License in a document you have written, include + a copy of the License in the document and put the following + copyright and license notices just after the title page: + +
+Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +
+ +If you have no Invariant Sections, write "with no Invariant + Sections" instead of saying which ones are invariant. If you have + no Front-Cover Texts, write "no Front-Cover Texts" instead of + "Front-Cover Texts being LIST"; likewise for Back-Cover + Texts. + +If your document contains nontrivial examples of program + code, we recommend releasing these examples in parallel under your + choice of free software license, such as the GNU General Public + License, to permit their use in free software. + + + + + diff --git a/docs/lcdproc-user/running.docbook b/docs/lcdproc-user/running.docbook new file mode 100644 index 0000000..30be47b --- /dev/null +++ b/docs/lcdproc-user/running.docbook @@ -0,0 +1,138 @@ + +Running LCDproc + + +Running LCDd + + +If you have installed the init-scripts you can simply start, stop +and restart LCDd with the init-script. + + + +Running LCDd from the command line + + +There are several reasons for running LCDd from the command line + + + +You don't want to install LCDd but run it from the source directory. +You want to do some debugging. +You want to get the output directly on stderr. +... + + + + +If you run LCDd as a "normal" user, it will not change to the user +specified in the config file. +For parallel port devices you will need root privileges anyway ;) + + + + +The simplest command that will run LCDd is the following. It is useful for +running LCDd from the source directory, e.g. after building. + + + +$ server/LCDd -c LCDd.conf + + + + + +The Command Line Options of LCDd + + +Running LCDd -h gives you an overview of the currently available +command line options, including a list of the compiled in drivers. + + + +<command>LCDd -h</command> + ] [ -d ] [ -a ] \ + [ -p ] [ -u ] [ -w + + + + + + + +Running lcdproc + + +You will probably more often run lcdproc from the command line than +you will run LCDd. + + + +The Command Line Options of lcdproc + + +Running lcdproc -h gives you an overview of the currently available +command line options. + + + +<command>lcdproc -h</command> + + + + + + +You will not be able to connect to a remote server, unless it listens to +the correct interface and port! See +LCDd.conf: The [server] Section +for details on the server setup. + + + + + + + + + diff --git a/docs/lcdproc.1 b/docs/lcdproc.1 index a7b149c..59064d1 100644 --- a/docs/lcdproc.1 +++ b/docs/lcdproc.1 @@ -1,9 +1,9 @@ .TH lcdproc 1 "1-aug-01" "LCDproc" .SH NAME -lcdproc - displays system status on LCDproc server +lcdproc - displays system status on LCDproc server (LCDd(8)) .SH SYNOPSIS .B lcdproc -[\-s \fIserver\fP] [\-p \fIport\fP] [\fImode\fP [\fImode\fP ...]] +[\-s \fIserver\fP] [\-p \fIport\fP] [\-d] [\fImode\fP [\fImode\fP ...]] .SH DESCRIPTION lcdproc connects to the LCDproc server to display status information about the system. .PP @@ -18,6 +18,9 @@ Set the hostname which LCDproc is running on, assumed to be localhost unless oth .B \-p \fIport\fP Set the port which LCDproc is accepting connections on, assumed to be 13666 unless otherwise set .TP 8 +.B \-d +Daemonize right after startup +.TP 8 .B \fImode\fP Where mode is one of the following letters: .RS @@ -44,8 +47,12 @@ connects to the LCDproc server and specifies the following modes: .PP +.Sh SEE ALSO +.Xr LCDd 8 .SH AUTHOR -LCDproc was written by William Ferrell (wwf@splatwerks.org) and Scott Scriven (scriven@cs.colostate.edu). +LCDproc was originally written by William Ferrell (wwf@splatwerks.org) and Scott Scriven (scriven@cs.colostate.edu). + +Since that time various people have contributed to LCDproc. The newest version of LCDproc should be available from here: diff --git a/docs/lcdproc.sgml b/docs/lcdproc.sgml deleted file mode 100644 index ad63413..0000000 --- a/docs/lcdproc.sgml +++ /dev/null @@ -1,674 +0,0 @@ - - - - - 1999-02-08 - LCDproc User's Guide - Installation and Client Development Guide - - - - - Introduction - LCDproc is a system status monitoring application that drives a - variety of different LCD-based display devices. It provides a powerful - framework for networked statistic gathering, adding new monitors or - LCD-aware applications, and adding new devices. - - The client shipped with LCDproc v0.4 can connect to an LCDproc - server either on the local system or on a remote system as long as it - is reachable. It extracts the same statistics regardless of where it - sends this information. The statistics it gathers include CPU - utilization, memory utilization, disk utilization, network utilization, - system uptime, time, and date, and so on. It displays this information - in assorted ways, and can be tailored to taste. - - - Supported Hardware - As shipped, LCDproc v0.4 supports LCD modules from Matrix - Orbital Corporation, HD447800-controlled LCDs, and can emulate an LCD with - the curses library or plain, raw, ugly text. - - - Matrix Orbital LCD Modules - - LCDproc was born out of original tinkering by William Ferrell with - one of these LCD modules. Their ease of installation and use (as well - as the amazing amount of patience demonstrated by the folks at - Matrix Orbital whilst William figured things out) meant one less thing - to worry about during the early stages of LCDproc's life. - - - These 20x4 alphanumeric modules are connected via standard DB-9 cabling and - connectors. They draw either 5V or 12V, depending on the module purchased, - and are attached with a standard floppy cable connector (with a slightly - modified wire configuration). - - - Once connected, using them is a breeze. They can operate at any number of - different baud rates and serial configurations, but normally they run at - 19,200 baud, 8-N-1, making them quite quick. Sending ASCII to the module - will make it simply display that text at its current cursor position. The - module has a built-in BIOS that recognizes commands (sent by transmitting a - single-byte "marker" signifying that a command is on the way, followed by - the single-byte command character itself along with any parameters, if needed) - allowing the programmer to clear the screen, position the cursor anywhere, - define custom characters (up to 8 at a time), draw bar graphs and large numbers, - change the LCD's contrast, and so on. - - - The BIOS included also implements line-wrapping (i.e. writing past the - twentieth character on the first row will automatically move the cursor - to the first character on the second row), and screen scrolling (i.e. - writing past the twentieth character on the fourth row causes the whole - screen to scroll up one row, clearing the fourth line and positioning the - cursor at the first character on that line). - - - These modules are fast. Using the auto-line-wrap feature and disabling - the auto-scrolling feature, the screen can be updated thirty times per - second if *every* character on the screen is changed. If updating less - than the whole screen, the LCD can update faster than can be seen by - the human eye. This, of course, more than meets LCDproc's needs. - - - - HD44780 Controller-Based LCDs - - These LCDs are controlled by the Hitachi HD44780 LCD controller, and - connect to a system's parallel port. Not much else is known about these - devices at this time. [Update this section]. - - - - LCD Emulation - - LCDproc can emulate an LCD on a curses terminal (or even on a dumb terminal - by writing raw text out, if you're that desperate). The output is confined to - a 20x4 character area, just like on a real LCD, and can be "swallowed" into - window manager panels such as fvwmbuttons. - - - - - LCDproc Documentation - - This document is intended to be full, complete documentation for - LCDproc. While some information presented in this document is present - in assorted files scattered across the LCDproc distribution tarball, - this document is meant to encompass all aspects of dealing with - LCDproc, from installation, all the way to developing custom clients - using LCDproc's client/server API. - - - README and INSTALL files will always be distributed with LCDproc, along - with the requisite copyright and licensing information, but this document - will eventually replace the content of the README and INSTALL files. - - - This documentation was written in SGML and - DocBook. SGML is a - generalized markup language (of which HTML is a subset), and DocBook is a set of - layout tools and markups using SGML that lends itself quite nicely to the publishing - of technical manuals and software documentation like this. - - - In Linux, one can produce DVI, PostScript, HTML, Unix Manual Pages and Info - pages from the same SGML/DocBook source using - SGMLtools. Take a look at this set - of tools if you have any large-scale documentation to write. It might have a bit of - a steep learning curve, but it's certainly worth the effort. - - - - - - Installation - - This chapter covers the installation process for both LCDproc, and the actual LCD - module intended for use with LCDproc. Since our experience has involved almost - exclusively the Matrix Orbital modules, we will spend little time on installation - instructions for other hardware. - - - If you have successfully installed LCDproc-compatible hardware and would care to - document how you did so, please e-mail the author of this book - (choadster@earthlink.net). - - - We will examine the installation process of LCDproc and the hardware it drives in - small steps, as it is vitally important to pay close attention to detail during - hardware installation to avoid damaging equipment, as well as during LCDproc's - installation, since things have become a little more complicated since LCDproc's - split into a client and server model. - - - First, hardware installation is discussed. If you are not using physical LCD - hardware to run LCDproc, you can safely skip the hardware installation sections and - move on to the software installation sections. - - - Hardware Installation - - Regardless of what specific type of hardware you intend to use with LCDproc, - installation is usually straightforward, and requires only a few steps. Regardless, - you must use caution while working inside your computer system or with any hardware - attachments. - - - Warning! - - Installing new hardware inside a computer system can be dangerous to both - system components and the installer. Use caution whenever adding a component - to the inside of your system, altering a power cable, or physically mounting - a device inside a computer system. - - - When installing hardware inside a computer, make sure it's turned off and that - its power is disconnected. This is especially important when making changes to - power cables (as some LCD modules require). - - - - Matrix Orbital LCD/VFD Module Installation - - The LCD and VFD modules from Matrix Orbital are relatively straightforward - to install. With a small, regular (flat-head) screwdriver, a spare floppy drive - power cable, and a bit of luck, installation will take less than an hour. - - - These installation instructions assume that you are installing the module into - a PC or PC-style system (one with AT- or ATX-compliant power cabling) and that - you have some idea of where you intend to permanently mount the module. For - mounting ideas and tips, refer to the section "Mounting" below. - - - Before you start - - Your Matrix Orbital LCD or VFD module should be clearly marked with an - indication of the module's power requirements. It should be either a 5 volt - or 12 volt unit. You should have this information available before proceeding. - - - - Power Cable Modification - - The first step in installing the module is making the necessary modifications - to a floppy drive power cable in order to provide power to the module. The - modifications must be made based on the module's power requirements -- either - 5V or 12V -- depending on which module you purchased. - - - A standard floppy drive power cable has a smaller connection than a "normal" - PC power connector. However, like a "normal" power connector, it has four - wires: one yellow, one red, and two black. The red wire provides +5V power, and - is "hot" or live when the system is powered up. The yellow wire provides +12V - power, and is also hot when the system is powered up. Both black wires are - ground. - [TODO: INCLUDE A FIGURE HERE SHOWING A "STANDARD" FLOPPY CONNECTOR] - - - One of the hot wires and one of the black wires will not be needed for your - module's power connection; they will be completely removed when the power cable - modification is complete. - - - Warning! - - Do NOT make this modification to a power cable attached to a running - system! Electrocution resulting in personal injury and/or damage to the - system can result. - - - - Using a regular screwdriver, press down the small metal locking flap of one - of the two black wires on the small end of the cable, and pull the black wire - from the connector. Using a pair of needle-nose pliers, squeeze the other end - of the same black wire, and pull it out of the large end of the cable. This - black wire can be set aside; it will not be used for the module's power - connection. Either wire can be safely removed; you may safely remove either - wire. - [TODO: INCLUDE A FIGURE HERE SHOWING THIS PROCESS] - - - Next, using the same procedure, remove the unneeded hot wire. If your module - is 5V, you do not need the yellow (+12V) wire. Conversely, if your module is - 12V, you do not need the red (+5V) wire. The removed wire can be set aside; - it will not be used for the module's power connection. - [TODO: INCLUDE A FIGURE HERE] - - - The floppy power connector should now have only two wires attached to it. - Leave the larger end alone from now on; these connections are correct (the - larger end connects to your system's power mains). Move the two remaining wires - to the outside connectors on the small end of the cable. Orientation does not - particularly matter here; the connector will fit on the module's receptacle - in either orientation. - [TODO: A FIGURE HERE] - - - You should now have a properly modified power connector. When physically - attaching this connector to the module, the black (ground) lead should be - connected to the pin labelled GND, while the colored (+5V/+12V) lead should - be connected to the pin labelled +5V/+12V. - - - Test the power connection before connecting the data line or mounting the - module. Connect the module to the power connector, and the connector to your - system's power mains. Turn the system on. - - - Caution - - If the module does not immediately display its initial BIOS screen and light - up its backlight (or light up the screen if a VFD module is being used), - immediately power down the system, disconnect the module - and connector, and double-check the modification before trying again. Do NOT - leave the system on if the module does not immediately respond; module or - system damage could result. - - - - When the LCD powers up and displays its initial BIOS screen, you've gotten the - power connection wired properly and can now properly mount the module and make - its final connections. Matrix Orbital Corporation sells a PC bay insert mount - for the 20x4 and 20x2 modules (LCDproc, however, only supports the 20x4 at - present). The inserts provide an easy means of mounting the LCD modules inside - a PC using one (for the 20x2) or two (for the 20x4) 5 1/4" bays. - - - Note - - Describing how to physically mount the module in a PC case is beyond the - scope of this document; LCDproc's website contains more detailed mounting - information and examples. - - - - - Serial Connection - - The LCD module uses a standard DB9 serial connector. You can attach the module - to your system using a direct cable to the motherboard, or by removing one of - your system's serial ports from the back of the case, then connecting it to a - standard serial cable to the module. - - - While connecting the serial cable to the module, be sure to configure the - module's serial interface settings. Typically, setting the module to its fastest - setting (19,200 baud, 8-N-1) is recommended. At present, the Matrix Orbital - module driver in LCDproc is hardwired to use these settings; using different - ones will require minor changes to the driver's code. - - - - - Other Display Types - - At present, we do not have any detailed information regarding the installation - of other types of LCDs. If you have any information that would be useful to - include here, please contact William Ferrell - (choadster@earthlink.net). - - - - - - LCDproc Distribution Layout - The current LCDproc distribution contains both the LCDproc server - and the LCDproc client. It also contains sparse documentation (this - document will hopefully solve this problem), and a sample Perl client. - [THIS WILL CHANGE -- REWRITE THIS PARAGRAPH] - - - Basic Layout - - LCDproc is distributed in a single archive containing both the client(s) - and the server: - - clients/ - docs/ - old/ - server/ - server/drivers/ - shared/ - tests/ - BUGS - COPYING - INSTALL - Makefile - Makefile.config - README - TODO - WHATSNEW - Contains the LCDproc client and the sample Perl client - Documentation (sparse at the moment) - Contains older source code, unused in compiling v0.4 - Contains the LCDproc server - Contains LCDproc's device drivers - Contains shared code - Contains test code not used in compiling - A list of known bugs in the current version - The GNU General Public License - Installation Instructions - File for the "make" utility, used to compile LCDproc - Contains compile-time user-tunable defaults for LCDproc - Read this file first! Contains basic information regarding LCDproc, - what it does, how it works, and how to start building it. - List of planned changes and improvements. - List of revisions that have been made to LCDproc throughout its - development. [This should be changed to ChangeLog] - - - - - A Stroll Through the Code - - This section attempts to document how LCDproc works. Both the server and - the client are explored at the source code level. This section was written - as an exercise for the author to help him better understand LCDproc's - inner workings, allowing him to better document LCDproc for end users and - developers. Feel free to skip past this entire section unless you really - feel like reading how LCDproc renders screens, manages clients, deals with - input, and handles trouble. - - - The LCDproc Server, LCDd - - LCDd is the central component of LCDproc. It is responsible for several - different activities: - - - Initializing the output device - Initializing the incoming socket - Listening for client connections and accepting them - Storing screens provided by clients - Storing stats provided by clients - Choose the best screen to display on the LCD based on order of - client and screen arrival, and by priority - Provide a rich screen-drawing widget set for clients to use - Render screens to the LCD - Gracefully handle dead sockets and clients - Gracefully remove screens and clients when asked to by clients or - the user - - - - To accomplish all this, LCDd splits into dozens of source files to handle - different bits of the job. We will examine each of these source files one by - one (and, to make things easier, in alphabetical order). Header files (*.h) - will not be included in this discussion. - - - server/client_data.c - - This file appears to contain code that handles the creation and destruction - of linked lists for client data. - - - - server/client_functions.c - - This file actually describes itself as its first comment! It contains - definitions for all the functions that the clients can run. They are to - be called only from server/parse.c. - - - Here the functions that clients call when connected to LCDd are actually - defined and performed. - - - - server/clients.c - - This file contains code allowing LCDd to handle client connections and - data structures. It contains functions to initialize the internal list - of clients, terminate client connections, add new clients to the list, - add, remove, and retrieve messages to clients' message queues, and - locating a client's socket. - - - - server/input.c - - This file contains functions that handle input from keypads, joysticks, - etc. - - - - server/main.c - - Where the action is. - - - This file contains LCDd's main() function and supporting code. It begins - life by configuring signal handlers, then by immediately initializing the - LCD drivers. (Huh?) It then parses the command line, configuring the - LCD driver appropriately, then initializes its internal lists and the - socket. - - Next, it forks into a daemon process (shedding its controlling terminal) - and enters the main loop. The main loop: listens for connections from - new clients and for input from already connected ones, parses all input - from connected clients, checks for input, then updates the screen list - and updates the LCD. - - - Also present are functions to handle graceful exits when various signals - are received, and a help screen. - - - - server/menu.c - - This appears to be code to handle server-generated menu screens on the LCD. - [I don't understand this file in the slightest ... study this harder later] - - - - server/parse.c - - This file contains code that parses input from the clients. - parse_all_client_messages() is called once each time through main()'s loop. - - - - server/render.c - - This file contains code that actually generates the full screen data to - send to the LCD. draw_screen() takes a screen definition and a counter as its - arguments. It builds the screen according to the definition, and using the - counter as a reference. - - - - server/screen.c - - This file stores all the screen definition-handling code. Functions here - provide means to create new screens and destroy existing ones. Screens are - identified by client and by the client's own identifiers for screens. - - - - server/screenlist.c - - This appears to be the screenlist handler that decides which screen to - display based on priorities and screen creation order. - - - - server/serverscreens.c - - This file contains code to allow the server to generate its own screens. - Currently, only the server status screen is provided, showing total number - of connected clients, and the combined total of screens they provide (this - count does not include the server's screens). - - - It is interesting to note that the server creates a special screen - definition for its screens, but uses the same widget set made available - to clients. - - - - server/sock.c - - This file contains all the sockets code used by the server. This contains - the code called upon by main() to initialize the listening socket, as well - as code to deal with sending messages to clients, maintaining connections, - accepting new connections, closing dead connections (or connections - associated with dying/exiting clients), etc. - - - - server/widget.c - - This file houses code that handles the creation and destruction of widget - objects for the server. These functions are called using the arguments - passed by the client, then they store the specified widget into a generic - container that is parsed later by the screen renderer. - - - - server/drivers/* - - These are the individual driver files. Each driver allows LCDproc to display - its output on a different device. A driver is responsible for accepting - LCD-like handling instructions from LCDd, and for returning input from the - device to LCDd. - - - Currently, drivers provided are MtxOrb, hd44780, curses, and joy. The - joystick (joy) driver doesn't provide output, but only input. - - - - - The LCDproc Client - - The client shipped with LCDproc performs all of the statistic gathering - previously performed by LCDproc v0.3.x. Instead of driving the LCD directly, - in this version it now connects to LCDd and sends its screens and data there. - - - In this implementation of the statistic-gathering portions of LCDproc, the - layout departs substantially from the older v0.3.x code. Each screen is - generated by functions stored in separate files -- one file per screen. - This keeps files smaller, and code much simpler to maintain and update. - - - The client appears to use files from the share/ tree as well. - - - clients/lcdproc/batt.c, chrono.c, cpu.c, disk.c, load.c, mem.c - - These files contain the functions implementing all the screens provided by - LCDproc. - - - Each contains several functions, mostly related to actual statistic gathering. - They are also apparently responsible for actually transmitting their screen - definitions to the server and answering the server's requests for statistic - updates. The functions here do *no* checking to determine if they are being - asked for. They *do* check to see if they need to create a new screen - definition or merely update it. It would appear that the client's main() or - other higher-level function is responsible for calling this function when the - server asks for an update. - - - - clients/lcdproc/main.c - - This file contains the LCDproc client's main() function, as well as a few - supporting functions. - - - It first declares and fills a modelist (used only internally by this client) - that determines which screens will run by default (if the user doesn't - specify a custom modelist on the command line). The first thing main() itself - does is configure the signal handlers. - - - Next, it parses the command line for options, yelling at the user if an - invalid or nonsensical argument has been specified. After it has done this, - it tries to open a socket connection to LCDd. If successful, execution - continues. If unsuccessful, the client exits gracefully. - - - Assuming a valid socket connection is established, it sends the "hello" - command to the server, introducing itself and convincing the server that yes, - it really *should* serve this client. Next, it calls the mode_init() function - which appears to set up data structures for the various modes, and then finally - the main_loop() function which executes indefinitely until the client is - killed or is asked to stop. Then the program exits cleanly. - - - main_loop() is defined in this file as well. The main loop listens for any - input from the server, and reacts on what it receives. It appears capable of - dealing with keypresses, listen/ignore signals, and menu activity. After it - has reacted appropriately to inputs, it runs the screen asked for by the - server. - - - The old main() is commented out, but included here for reference. Eventually, - this will be removed from LCDproc's source. For now, however, it serves as a - useful reference. - - - - clients/lcdproc/mode.c - - This file contains functions responsible for initializing mode screens and - calling the appropriate mode screen update function when asked to do so. - main_loop() passes the server's parsed messages to this function to enable it - to select which screen is called for. - - - This file also contains reread() and getentry() functions which are used by - many of the mode screens. - - - - - Shared Files - - Both LCDd and the LCDproc client make extensive use of linked lists and sockets - code. Much of that code is shared, and stored in the shared/ tree. - - - shared/config.c - - This file contains the beginnings of configuration file code. - - - - shared/LL.c - - This file contains all of the functions used in implementing LCDproc's - linked lists. Functions exist here to create new lists, destroy lists, - remove an entry from a list, add an entry to a list, move a pointer to - the beginning or end of a list, move a pointer to the next item in a - list, the previous item of a list, or to retrieve individual items from - a list. - - - - shared/sockets.c - - This file contains all the functions used in implementing LCDproc's socket - handling capabilities. Full bi-directional communication is implemented by - these functions. - - - - shared/str.c - - This file contains only one function, get_args(). It appears to parse - command lines (or command line-like strings) for arguments, and returns them - in a more useful form. - - - - - - diff --git a/docs/netstuff.txt b/docs/netstuff.txt index 64c7379..dc3cce7 100644 --- a/docs/netstuff.txt +++ b/docs/netstuff.txt @@ -159,8 +159,8 @@ screen_set #id [-priority integer] [-name "my_name"] [-duration integer] widget_add #screen #id type [-in #id] Add something onscreen Widget types can be any of the following: "string", "hbar", - "vbar", "title", "icon", "scroller", "frame", ... more later? - Widgets are drawn in the order you create them. + "vbar", "title", "icon", "num" "scroller", "frame", ... more + later? Widgets are drawn in the order you create them. You can put a widget inside a frame by adding "-in #id", where #id is the name of a frame. @@ -182,6 +182,8 @@ widget_set #screen #id data icon x y binary_data + num x number_between_0_and_9 + title text scroller left top right bottom direction speed text