This is a "plugin" for the Video Disk Recorder (VDR).

Written by:                  Frank Schmirler <vdrdev@schmirler.de> 
Project's homepage:          http://vdr.schmirler.de/

Latest version available at: http://vdr.schmirler.de/

See the file COPYING for license information.

Description:
------------
With this plugin you can import the EPG of a remote VDR. It can either
use SVDRP or streamdev's VTP to download the EPG.

Requirements:
-------------
- plugin svdrpservice >= 0.0.2 (available via http://vdr.schmirler.de)

Installation:
-------------
- cd VDR/PLUGINS/src
- tar xzf vdr-epgsync-<VERSION>.tgz
- ln -sf epgsync-<VERSION> epgsync

Now compile and install epgsync (and svdrpservice) as usual and add
both plugins to the script starting your VDR (e.g. runvdr). No options
required, so simply append:

  -P epgsync -P svdrpservice

Since svdrpservice-0.0.4 you can already specify the server IP and port
on the commandline. It will then serve as the default for all plugins
using svdrpservice:

  -P epgsync -P 'svdrpservice 192.0.2.1:6419'

Check the svdrphosts.conf (or streamdevhosts.conf) file on the remote
VDR: The IP of the VDR running epgsync must be listed or otherwise the
connection will be refused.

Configuration:
--------------
Before you can connect, your local VDR must know the IP address of the
remote VDR. Either configure a default IP in the svdrpservice plugin or
enter it in epgsync's setup.

The plugin setup offers the following options:

- Hide mainmenu entry
The mainmenu entry of epgsync allows you to trigger an epgsync at any
time. If you don't need this or if you are using a keymakro to call the
mainmenu entry you can hide it with this option.

- Server IP
P address of SVDRP server. Leave empty or enter "0.0.0.0" if you want
to use the default IP configured in the svdrpservice plugin.

- Server port
SVDRP port on server. Since VDR 1.7.15 the default port is 6419, before
it was 2001. If you prefer VTP, its default port is 2004. The special
value 0 uses the default port configured in svdrpservice.

- Connection attempts
Defines how often epgsync will try to establish the connection to the
server. For most users the default 1 should be sufficient. However if
e.g. the client uses WOL to wake the server it might not be available
immediately. The first retry will be after 1 second. The delay will be
doubled after each attempt.

- Update "now" and "next" first
Enable this option if you want to import the "What's on now/next"
entries first. It uses the SVDRP commands "LSTE now" and "LSTE next".
Especially useful for those who start with an empty epg.data file.

- Sync channel by channel
Determines how the EPG is downloaded. See notes below.

- EPG sync on startup
Start syncing when the plugin is started.

- EPG sync timeout (h)
Perform an epgsync regularely when enabled.  You will need this option
only in special cases. As long as your client syncs on startup
regularely and receives EPG information via DVB stream (e.g. using
streamdev's "Filter Streaming" option) you should be fine without this
option. This is not an exact timeout but a minimum delay in hours
between two syncs. Every successful manually or SVDRP triggered sync
will reset the timeout. This setting won't trigger a sync right after
plugin start. Use the previous option instead.

- Map channels by
Mode "ID", the default, simply copies the EPG data it receives,
effectively mapping channels by their channel ID. In "ID, Name" mode,
if no local channel corresponds to a channel ID from EPG, an attempt
is made to find the channel by name. Finally in "Name, ID" mode,
epgsync searches for a channel by name, prefering channels with a
different ID. You can use this mode to copy EPG to analogue channels.
Note: When looking up a channel by name, case is ignored. Both, the
long and the short channel names are considered.

- Target channels
Restrict the EPG import to certain channel types.

Recommended settings
--------------------
The quick answer for the impatient:

Use "Sync channel by channel: no" if
- you connect to VTP port
- or need to be fast
Use "Sync channel by channel: yes" if
- you connect to SVDRP port
- or encounter bandwidth related problems with "no"
- or want to share the SVDRP connection with other local plugins

Use "Update now and next first: yes" if
- you start VDR with an empty epg.data
- or you selected "Sync channel by channel: yes"
Use "Update now and next first: no" otherwise

The long answer:

With "Sync channel by channel: no", epgsync will issue "LSTE" without
any arguments. The complete EPG information of the remote VDR will be
downloaded in one piece. This is fast, so the remote SVDRP port won't
be blocked too long. On the other hand it will temporarily allocate
quite a bit of memory. Besides it will request a dedicated svdrpservice
connection. This is ok for VTP as the VTP server can handle multiple
connections at a time. With SVDRP it might be an issue if there are
more local plugins which want to connect to the same SVDRP server. As
the SVDRP server processes only one connection, either epgsync or the
other plugins will win - which ever is first. The other might timeout.

"Sync channel by channel: yes" is the "economy mode". It takes
considerably longer but the connection can be shared with other local
plugins. I had no problem running e.g. remoteosd at the same time.

It depends on "Map channels by", how this mode actually works: If set to
"ID", epgsync loops through the local channel list, starting with the
first. If a schedule is available for a channel "LSTE <channel id>"
is sent, the reply is processed and the thread sleeps for a few millis.
Note that in this mode epgsync won't import the EPG of a channel
which does not have a local schedule. To always get the EPG of all
channels you should configure "Update now and next first: yes". This
will import the results of "LSTE now" and "LSTE next" beforehand.

If "Map channels by" is not set to "ID", epgsync sends the "LSTC" command
to get the remote channel list. For each channel in this list, epgsync
sends an "LSTE <channel number>", processes the reply and sleeps for a few
millis. So in the end epgsync imports the EPG of all remote channels. It
is not necessary to enable "Update now and next first".

SVDRP
-----
You can trigger an EPG sync with the following SVDRP command:
  PLUG epgsync SYNC