source: npl/mediabox/lcdproc_edwin/src/docs/lcdproc.sgml @ c5c522c

<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">

<book>
  <bookinfo>
    <date>1999-02-08</date>
    <title>LCDproc User's Guide</title>
    <subtitle>Installation and Client Development Guide</subtitle>
  </bookinfo>
  <toc></toc>

  <chapter>
    <title>Introduction</title>
    <para>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.
    </para>
    <para>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.
    </para>
    <sect1>
      <title>Supported Hardware</title>
      <para>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.
      </para>
      <sect2>
        <title>Matrix Orbital LCD Modules</title>
        <para>
          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.
        </para>
        <para>
          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).
        </para>
        <para>
          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.
        </para>
        <para>
          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).
        </para>
        <para>
          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.
        </para>
      </sect2>
      <sect2>
        <title>HD44780 Controller-Based LCDs</title>
        <para>
          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].
        </para>
      </sect2>
      <sect2>
        <title>LCD Emulation</title>
        <para>
          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.
        </para>
      </sect2>
    </sect1>
    <sect1>
      <title>LCDproc Documentation</title>
      <para>
        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.
      </para>
      <para>
        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.
      </para>
      <para>
        This documentation was written in SGML and 
        <ULINK URL="http://www.oasis-open.org/docbook/">DocBook</ULINK>. 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. 
      </para>
      <para>
        In Linux, one can produce DVI, PostScript, HTML, Unix Manual Pages and Info
        pages from the same SGML/DocBook source using 
        <ULINK URL="http://www.sgmltools.org/">SGMLtools</ULINK>. 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.
      </para>
    </sect1>
  </chapter>

  <chapter>
    <title>Installation</title>
    <para>
      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.
    </para>
    <para>
      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).
    </para>
    <para>
      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.
    </para>
    <para>
      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.
    </para>
    <sect1>
      <title>Hardware Installation</title>
      <para>
        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.
      </para>
      <Warning>
        <Title>Warning!</Title>
        <para>
          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.
        </para>
        <para>
          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).
        </para>
      </Warning>
      <sect2>
        <title>Matrix Orbital LCD/VFD Module Installation</title>
        <para>
          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.
        </para>
        <para>
          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.
        </para>
        <Tip>
          <Title>Before you start</title>
          <para>
            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.
          </para>
        </tip>
        <sect3>
          <title>Power Cable Modification</title>
          <para>
            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.
          </para>
          <para>
            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]
          </para>
          <para>
            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.
          </para>
          <Warning>
            <title>Warning!</title>
            <para>
              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.
            </para>
          </Warning>
          <para>
            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]
          </para>
          <para>
            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]
          </para>
          <para>
            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]
          </para>
          <para>
            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.
          </para>
          <para>
            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.
          </para>
          <Caution>
            <Title>Caution</Title>
            <para>
              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),
              <EMPHASIS>immediately</EMPHASIS> 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.
            </para>
          </Caution>
          <para>
            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.
          </para>
          <Note>
            <title>Note</title>
            <para>
              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.
            </para>
          </Note>
        </sect3>
        <sect3>
          <title>Serial Connection</title>
          <para>
            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.
          </para>
          <para>
            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.
          </para>
        </sect3>
      </sect2>
      <sect2>
        <title>Other Display Types</title>
        <para>
          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 
          (<ULINK URL="mailto:choadster@earthlink.net">choadster@earthlink.net</ULINK>).
        </para>
      </sect2>
    </sect1>
  </chapter>
  <chapter>
    <title>LCDproc Distribution Layout</title>
    <para>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]</para>

    <sect1>
      <title>Basic Layout</title>
      <para>
        LCDproc is distributed in a single archive containing both the client(s)
        and the server:
        <SimpleList columns=2>
          <Member>clients/</Member>
          <Member>docs/</Member>
          <Member>old/</Member>
          <Member>server/</Member>
          <Member>server/drivers/</Member>
          <Member>shared/</Member>
          <Member>tests/</Member>
          <Member>BUGS</Member>
          <Member>COPYING</Member>
          <Member>INSTALL</Member>
          <Member>Makefile</Member>
          <Member>Makefile.config</Member>
          <Member>README</Member>
          <Member>TODO</Member>
          <Member>WHATSNEW</Member>
          <Member>Contains the LCDproc client and the sample Perl client</Member>
          <Member>Documentation (sparse at the moment)</Member>
          <Member>Contains older source code, unused in compiling v0.4</Member>
          <Member>Contains the LCDproc server</Member>
          <Member>Contains LCDproc's device drivers</Member>
          <Member>Contains shared code</Member>
          <Member>Contains test code not used in compiling</Member>
          <Member>A list of known bugs in the current version</Member>
          <Member>The GNU General Public License</Member>
          <Member>Installation Instructions</Member>
          <Member>File for the "make" utility, used to compile LCDproc</Member>
          <Member>Contains compile-time user-tunable defaults for LCDproc</Member>
          <Member>Read this file first! Contains basic information regarding LCDproc,
            what it does, how it works, and how to start building it.</Member>
          <Member>List of planned changes and improvements.</Member>
          <Member>List of revisions that have been made to LCDproc throughout its
            development. [This should be changed to ChangeLog]</Member>
        </Simplelist>
      </para>
    </sect1>
    <sect1>
      <title>A Stroll Through the Code</title>
      <para>
        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.
      </para>
      <sect2>
        <title>The LCDproc Server, LCDd</title>
        <para>
          LCDd is the central component of LCDproc. It is responsible for several
          different activities:

          <SimpleList>
            <Member>Initializing the output device</Member>
            <Member>Initializing the incoming socket</Member>
            <Member>Listening for client connections and accepting them</Member>
            <Member>Storing screens provided by clients</Member>
            <Member>Storing stats provided by clients</Member>
            <Member>Choose the best screen to display on the LCD based on order of
              client and screen arrival, and by priority</Member>
            <Member>Provide a rich screen-drawing widget set for clients to use</Member>
            <Member>Render screens to the LCD</Member>
            <Member>Gracefully handle dead sockets and clients</Member>
            <Member>Gracefully remove screens and clients when asked to by clients or
               the user</Member>
          </SimpleList>
        </para>
        <para>
          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.
        </para>
        <sect3>
          <title>server/client_data.c</title>
          <para>
            This file appears to contain code that handles the creation and destruction
            of linked lists for client data.
          </para>
        </sect3>
        <sect3>
          <title>server/client_functions.c</title>
          <para>
            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.
          </para>
          <para>
            Here the functions that clients call when connected to LCDd are actually
            defined and performed.
          </para>
        </sect3>
        <sect3>
          <title>server/clients.c</title>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>server/input.c</title>
          <para>
            This file contains functions that handle input from keypads, joysticks,
            etc.
          </para>
        </sect3>
        <sect3>
          <title>server/main.c</title>
          <para>
            Where the action is.
          </para>
          <para>
            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.</para>
          <para>
            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.
          </para>
          <para>
            Also present are functions to handle graceful exits when various signals
            are received, and a help screen.
          </para>
        </sect3>
        <sect3>
          <title>server/menu.c</title>
          <para>
            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]
          </para>
        </sect3>
        <sect3>
          <title>server/parse.c</title>
          <para>
            This file contains code that parses input from the clients.
            parse_all_client_messages() is called once each time through main()'s loop.
          </para>
        </sect3>
        <sect3>
          <title>server/render.c</title>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>server/screen.c</title>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>server/screenlist.c</title>
          <para>
            This appears to be the screenlist handler that decides which screen to
            display based on priorities and screen creation order.
          </para>
        </sect3>
        <sect3>
          <title>server/serverscreens.c</title>
          <para>
            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).
          </para>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>server/sock.c</title>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>server/widget.c</title>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>server/drivers/*</title>
          <para>
            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.
          </para>
          <para>
            Currently, drivers provided are MtxOrb, hd44780, curses, and joy. The
            joystick (joy) driver doesn't provide output, but only input.
          </para>
        </sect3>
      </sect2>
      <sect2>
        <title>The LCDproc Client</title>
        <para>
          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.
        </para>
        <para>
          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.
        </para>
        <para>
          The client appears to use files from the share/ tree as well.
        </para>
        <sect3>
          <title>clients/lcdproc/batt.c, chrono.c, cpu.c, disk.c, load.c, mem.c</title>
          <para>
            These files contain the functions implementing all the screens provided by
            LCDproc.
          </para>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>clients/lcdproc/main.c</title>
          <para>
            This file contains the LCDproc client's main() function, as well as a few
            supporting functions.
          </para>
          <para>
            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.
          </para>
          <para>
            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.
          </para>
          <para>
            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.
          </para>
          <para>
            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.
          </para>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>clients/lcdproc/mode.c</title>
          <para>
            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.
          </para>
          <para>
            This file also contains reread() and getentry() functions which are used by
            many of the mode screens.
          </para>
        </sect3>
      </sect2>
      <sect2>
        <title>Shared Files</title>
        <para>
          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.
        </para>
        <sect3>
          <title>shared/config.c</title>
          <para>
            This file contains the beginnings of configuration file code.
          </para>
        </sect3>
        <sect3>
          <title>shared/LL.c</title>
          <para>
            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.
          </para>
        </sect3>
        <sect3>
          <title>shared/sockets.c</title>
          <para>
            This file contains all the functions used in implementing LCDproc's socket
            handling capabilities. Full bi-directional communication is implemented by
            these functions.
          </para>
        </sect3>
        <sect3>
          <title>shared/str.c</title>
          <para>
            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.
          </para>
        </sect3>
      </sect2>
    </sect1>
 </chapter>
</book>