vdr/README

On Screen Menu for the Video Disk Recorder
------------------------------------------

These files contain the source code of an on screen
menu for a video disk recorder based on the DVB driver
of the LinuxTV project (http://linuxtv.org).
For details about the "Video Disk Recorder" project please
refer to http://www.cadsoft.de/people/kls/vdr.

The author can be contacted at kls@cadsoft.de.

Yet another "set-top-box"?
--------------------------

The "set-top-boxes" available from commercial companies all have
one major drawback: they are not "open". This project's goal is
to build an "open" digital satellite receiver and timer controlled
video disk recorder, based upon open standards and freely available
driver software (of course, the hardware still has to be bought).

The on screen menu system is simple, but shall provide all the
possibilites necessary to perform timer controlled recording,
file management and, maybe, even "on disk editing". The menus
of commercial set-top-boxes usually are a lot more fancy than
the ones in this system, but here we have the full source code
and can modify the menus in whatever way desired.

Compiling and running the program:
----------------------------------

Make sure the files from this package are located in a
directory that is "parallel" to the DVB directory of the
driver source for the Siemens DVB-S PCI card (refer to
http://linuxtv.org/dvb/siemens_dvb.html for more information
about that driver). For example, if the DVB driver was
extracted into the directory /home/kls/vdr/DVB, then this
package should be extracted into /home/kls/vdr/OSM.

In order for the menu colors to work correctly you may want
to replace the function RGB2YUV() in DVB/driver/dvb.c with

static u32 RGB2YUV(u16 R, u16 G, u16 B)
{
        u16 y, u, v;
        u16 Y, Cr, Cb;

        y = R * 77 + G * 150 + B * 29;  // Luma=0.299R+0.587G+0.114B 0..65535
        u = 2048+B * 8 -(y>>5);    // Cr 0..4095
        v = 2048+R * 8 -(y>>5);    // Cb 0..4095

        Y = y >> 8;
        Cb= u >> 4;
        Cr= v >> 4;

        return Cr|(Cb<<16)|(Y<<8);
}

(this may no longer be necessary with driver versions after 0.03c).

After extracting the package, change into the OSM directory
and type 'make'. This should produce an executable file
named 'osm', which can be run after the DVB driver has been
installed. There may be several warnings about "implicit declaration
of function `int asprintf(...)'" during the compilation, which I was
unable to avoid (anybody know how to avoid them?). Just ignore them,
the program will work, anyway.

There are two macros you can use to customize the 'osm' program
at compile time. Adding "DEBUG_REMOTE=1" to the 'make' call
will use the PC's keyboard as input device instead of the "Remote
Control Unit" (see http://www.cadsoft.de/people/kls/vdr/remote.htm).
Adding "DEBUG_OSD=1" will use the PC screen (or current window)
to display texts instead of the DVB card's on-screen display
interface. These modes are useful when testing new menus if you
only have a remote connection to the VDR (which, in my case, is
located in the living room and has neither a monitor nor a keyboard).

Configuration files:
--------------------

There are three configuration files that hold information about
channels, remote control keys and timers. These files are currrently
assumed to be located in the directory from which the 'osm' program
was started (this will become configurable later). The configuration
files can be edited with any text editor, or will be written by the
'osm' program if any changes are made inside the on-screen menus.
The meaning of the data entries may still vary in future releases,
so for the moment please look at the source code (config.c) to see
the meaning of the various fields.

There is no way of adding or deleting channels or timers yet, this
will be implemented later.

Learning the remote control keys:
---------------------------------

The remote control configuration file 'keys.conf' that comes with
this package contains the codes for the "d-box" remote control unit.
If you want to use a different remote control unit, simply delete
the file 'keys.conf' and restart the 'osm' program. The program will
then start a key learning session in which it first attempts to determine
the basic data transfer mode and timing of your remote control unit,
and then will ask you to press one key after the other so that it can
learn the various key codes. You will at least need to provide an "Up"
and a "Down" key, so that you can switch channels. The rest of the key
definitions is optional, but the more keys you define, the more you
will be able to navigate through the menus.

If the program has been built with "DEBUG_REMOTE=1", it will use the
key configuration file 'keys-pc.conf', so that you won't loose data
when switching between normal and debug mode.

Navigating through the On Screen Menus:
---------------------------------------

The "Main" menu can be called up with the "Menu" key of your remote
control unit. The "Up" and "Down" keys are used to select a specific
item. The "Left" and "Right" keys can be used to change options, and
the numeric keys allow direct input of numeric data. The "Ok" key
confirms any changes (or switches to a channel in the "Channels" menu).
The "Back" key goes back one level in the menu structure, discarding
any changes that might have been made in the current menu.

In the "Timers" menu, the current timer can be enabled or disabled with
the "Right" or "Left" key, respectively (enabled timers are marked with ">").
"Ok" here opens the "Edit timer" menu.

Textual options, like channel names or recording file names, can be edited
by pressing the "Right" button (which puts brackets around the current
character as in "[R]TL"), selecting the desired character position with
"Left" and "Right", and changing the character with the "Up" and "Down"
keys. "Ok" then confirms the changes.

The "Red", "Green", "Yellow" and "Blue" buttons have special meanings
in the various menus and are listed at the bottom of the on-screen-display.

At any point in the menu system, pressing the "Menu" key again will
immediately leave the menu system.

What do you think?
------------------

So, what do you think about this project? Does it make sense? Were you
able to use it? Do you have suggestions on how to improve it?
Please send email to kls@cadsoft.de if you'd like to comment on this.