lcd-stuff
=========


Description
-----------

lcd-stuff is a client for lcdproc written in C.


Features
--------

    * display of e-mail using POP3, IMAP and local mailboxes
    * MPD control
    * display of news items using RSS
    * display of the weather from weather.com
    * play web radio with MPlayer
      (because it has support for almost every format, especially
      RealAudio, which MPD hasn't)


Requirements
------------

    * 20×4 display
    * lcdproc, of course
    * CMake
    * C compiler
    * glib
    * mail
      - libetpan
    * weather
      - nxml
      - curl (required by nxml)
    * mpd
      - libmpd (>= 0.12.0)
    * rss
      - mrss
      - nxml
      - curl (required by nxml)
    * mplayer (optional, only at runtime)


Installation
------------

    * mkdir build
    * cd build
    * cmake ..
    * make
    * make install

If you don't have all libraries installed and you don't need the features, you
can use following parameters for the cmake run to disable the libraries and
their corresponding features:

   -DBUILD_RSS=OFF              disables rss
   -DBUILD_WEATHER=OFF          disables weather
   -DBUILD_MAIL=OFF             disables mail
   -DBUILD_MPD=OFF              disables mpd


Usage
-----

Just as every lcdproc client. Type "lcd-stuff -h" for more information. An
example configuration file is supplied with lcd-stuff (lcd-stuff.conf). The
documentation for all the various parameters is contained below.


Keys
----

mail, rss:      Up and Down select previous or next item

mpd:            Up: when playing (i.e. not pause), selects the next tile
                    when pausing, then stops playback
                Down: toggles between play and pause

mplayer:        Up: toggle between play and pause
                Down: Stop


Remote Interface
----------------

This program itself has a remote interface to be controlled from another
computer. See the [network] entry of the configuration file below. By default,
the network interface is disabled for security reasons!

The only client that implements the interface is the mplayer client.

It's a simple text protocol:

    mplayer command args

And command can be one of:

    streams                 Returns a list of stream names, the same as
                            shown in the menu.
    play <number>           Plays stream <number>. Counting starts with 0.
    pause_play              Toggles playback and pause of the current stream.
    stop                    Stops playing the current stream.

In the scripts directory of the source distribution, there's a sample client
written in Python that implements these commands. It's both meant as usable
client and as example.


Configuration file
------------------

The configuration file is in a INI-style format. As parser, the glib2
"Key-value file parser" is used which is documented at
http://developer.gnome.org/doc/API/2.0/glib/glib-Key-value-file-parser.html.

In the description below, following place holders are used

    <str>                   A simple text which may contain spaces. There's
                            _no_ need to escape spaces with backslash or
                            something else.
    <no>                    A continuous number, starting with 0 and increased
                            each time. You'll see below the sense of this
                            <no> stuff.
    <int>                   A number in decimal representation.
    <list>                  Not any arbitrary string but a string from a list
                            that is listed in the description on the right.
    <bool>                  "true" or "false"

Now, the options for each client are explained. It's legal to leave out a client
in the configuration file which means that this client doesn't get displayed.

    [mail]

    name=<str>              This is the name that is shown as title for the
                            mail screen.
                            Default: Mail

    interval=<int>          The update interval in seconds at which lcd-stuff
                            looks for new mails.
                            Default: 300

    number_of_servers=<int> The number of mail servers to check. The number is
                            read to retrieve the information that is specific
                            for the mail server below.
                            Default: 0

    name<no>=<str>          The name for the server which gets displayed in the
                            title.
                            Default: Server name

    type<no>1=<list>        The type of the server, currently "pop3" and "imap"
                            are supported. For local mailboxes, "maildir" (for
                            the maildir format which stores mails in three
                            subdirectories named "cur", "tmp" and "new),
                            "mbox" (for the mbox format, which stores all
                            mails in a single file) and "mh" (stores each
                            mail in a file, but all in one directory)
                            are supported.
                            Default: pop3

    server<no>=<str>        The server that contains the mailbox, e.g.
                            "pop3.gmx.net" if your mail provider is GMX.
                            For local mailboxes use "localhost".
                            Default: no default

    user<no>=<str>          The user name for the login. Not required when
                            using local mailboxes.
                            Default: empty string

    password<no>=<str>      The password for the login. Please set the
                            permissions of the file so that no other user
                            from your system can read your mail passwords.
                            Not required when using mailboxes.
                            Default: no default

    mailbox_name<no>=<str>  When type=imap, this variable holds the name of the
                            mailbox to check for new mail. For pop3, this is
                            ignored. For local mailboxes, you have to specify
                            the full path for the box, e.g.
                            /home/user/mail/inbox.
                            Default: INBOX

    hidden<no>=<bool>       Show only the number of mails in the first line but
                            don't browse through the mails with author and
                            subject
                            Default: false

    [rss]

    interval=<int>          The update interval at which the RSS feeds are
                            retrieved. Currently, there's no check if the
                            feed was updated, always the complete titles
                            are retrieved and updated.
                            Default: 1800 (= 30 min)

    number_of_feeds=<int>   The number of RSS feeds to retrieve. The number is
                            read to retrieve the information that is specific
                            for the RSS feed below.
                            Default: 0

    url<no>=<str>           The URL to the feed.
                            Default: no default

    items<no>=<int>         The number of items to retrieve. This is counted
                            from new to old, so if e.g. items=10, the 10 latest
                            items are shown.
                            Default: 0

    name<no>=<str>          The name that is shown in the title for the feed.
                            Default: no default

    [weather]

    name=<str>              The title that is used for the weather screen.
                            Default: Weather

    interval=<int>          The update interval for the weather.
                            Default: 3600 (= 1 h)

    citycode=<str>          The city code that can be retrieved from
                            http://www.weather.com/. Just enter your city
                            in the search box, click on the city. Then you
                            can extract the code from the URL. For example,
                            GMXX0096 stands for Nürnberg in Germany.
                            Default: no default

    unit=<str>              Switches between metric units like Celsius
                            ("metric") and imperial units like Fahrenheit
                            ("imperial").
                            Default: metric

    [mpd]

    name=<str>              The title for the MPD screen.

    server=<str>            The server name, can also be "localhost" if
                            the MPD server is running on the same machine.
                            Default: localhost

    port=<int>              The port number where the MPD accepts connections.
                            Default: 6600

    timeout=<int>           Timeout for MPD connections in seconds.
                            Default: 10

    [mplayer]

    name=<str>              The title for the mplayer screen that is displayed
                            if you select a station from the lcdproc menu.
                            Default: Webradio

    <str>=<str>             For each stream, a key value pair with station=url
                            must be used. This should save typing instead of the
                            scheme which is used for E-Mail and RSS feeds [1].
                            If the URL is a play list, then the prefix
                            "playlist " has to be used. This is simply because
                            mplayer cannot determine if it's a playlist
                            automatically but the starter has to give the
                            "-playlist" parameter.
                            Examples:
                            DLF=http://dradio-ogg.t-bn.de/dlf_high.ogg
                            Bayern2=playlist ...
                                    ...http://www.br-online.de/streaming/...
                                    ...bayern2radio/bayern2radio_m20.red.smil


    [network]

    Adding this entry without any key/values enables the network interface.
    By default, the network interface is disabled.

    DON'T USE THIS OPTION IF YOUR COMPUTER IS DIRECTLY CONNECTED TO THE
    INTERNET. IT'S DESIGNED FOR SMALL HOME NETWORKS ONLY!

    port=<int>              The port where a remote client can connect to.
                            Default: 12454


License, Author
---------------

lcd-stuff was written by Bernhard Walle <bernhard@bwalle.de>. It's
licensed under the terms of the GNU General Public License version 2.