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.

This program requires the card driver version 0.04 or higher
to work properly.

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 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.

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

There is no default 'keys.conf' file, so if you compile the program
without 'DEBUG_REMOTE=1' you will have to go through a "teach-in"
session that allows the program to learn your remote control codes.
It will first attempt 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 and
control recording/replaying.
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.

The default PC key assignments are:
             
  Up, Down, Left, Right     Crsr keys in numeric block
  Menu                      '5' in numeric block
  Ok                        Enter
  Back                      Backspace
  0..9                      '0'..'9' in top row
  Red, Green, Yellow, Blue  'F1'..'F4'
  Record                    'r'
  Pause                     'p'
  Stop                      's'
  Begin                     'B'
  SearchForward             'f'
  SearchBack                'b'
  SkipForward               'PgDn' in numeric block
  SkipBack                  'PgUp' in numeric block

If you prefer different key assignments, simply delete the file
'keys-pc.conf' and restart 'osm' to get into learning 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.