1999-02-08 Installation and Client Development Guide 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. 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. 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. 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]. 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. 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. 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. 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). 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. 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. 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. 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. 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). 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] 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] 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. 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. This file appears to contain code that handles the creation and destruction of linked lists for client data. 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. 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. This file contains functions that handle input from keypads, joysticks, etc. 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. 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] This file contains code that parses input from the clients. parse_all_client_messages() is called once each time through main()'s loop. 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. 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. This appears to be the screenlist handler that decides which screen to display based on priorities and screen creation order. 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. 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. 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. 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 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. 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. 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. 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. 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. This file contains the beginnings of configuration file code. 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. This file contains all the functions used in implementing LCDproc's socket handling capabilities. Full bi-directional communication is implemented by these functions. 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.