
scanfw - a CCI scanner for mythbuntu/MythTV

Developed by: majoridiot
README Version 1.01
Perl Scripting: (C)2008 John Baab
(C)2008 by the mythbuntu Development Team

Incorporates code (C)by: Jim Lohmeyer, Jim Westfall, and Dan Dennedy, et. al.

Distributed as part of the mythbuntu distribution of MythTV under GPL v2 and later.

***************************************************************************
License:

This Package is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public
License along with this package; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

****************************************************************************

This README covers the installation and use of scanfw.  Please refer to the included
"SCAN_TIPS" file for more in-depth information and general firewire/MythTV tips.

INSTALLATION
============

The following packages are required to compile scanfw in an Ubuntu/mythbuntu 
environment:

 * build-essential
 * libraw1394-dev
 * libiec61883-dev
 * libavc1394-dev

You can install these packages with Synaptic, or via apt-get.

If compiling in a different environment, you will need to ensure the necessary build 
packages and development libraries are installed.

To compile, from inside the firewire_scanner directory, do:

   $ make clean
   $ make
   $ sudo make install

The scanner executable "scanfw" will be located in /usr/bin

The perl helper-script mythtv.firewire.channels.pl is also required.  You can either 
run this script from the firewire_scanner directory, or copy it to /usr/bin :

   $ sudo cp mythtv.firewire.channels.pl /usr/bin


PREPARING TO SCAN
=================

scanfw requires a text file of channel names and numbers to scan from.  This channel 
file is generated from the channels associated with the firewire tuner in the mythconverg
database.  It must be accurate and contain only valid channels that the stb can tune and 
receive.

Due to the way that the Schedules Direct service and mythfilldatabase interact, it is 
possible to have invalid channels added automatically and/or leftover channels in your 
database.

It is *strongly* recommended you perform the following steps to ensure sane channel 
information is retrieved from mythconverg:

1. Logon to Schedules Direct and check your line-up.  Make sure
   the active channels include *only* channels you receive and 
   intend to view/record via firewire.  Save any changes you make.

2. Run mythtv-setup re-retrieve the SD line-up in *both* steps
   3. and 4.

3. In 5. Channel Editor- review and confirm the channels list is
   accurate.  remove any residual invalid or duplicated channels
   if necessary- although re-retrieving the edited channel line-up 
   should have taken care of this.

4. After exiting mythtv-setup, allow mythfilldatabase to run and
   finish.

5. Run mythtv.firewire.channels.pl to dump the channels from mythconverg.
   You will need to redirect the output to a file, otherwise it will display 
   in the terminal.  An example of how to do this is:

      $ mythtv.firewire.channels.pl > channels.txt

   or, if running it from the firewire_scanner directory:

      $ ./mythtv.firewire.channels.pl > channels.txt

   Omitting the "> channels.txt" redirection will display the channels to 
   the screen, if you would like to see the data that will be dumped.

6. Open the text file and confirm the dumped list looks sane and 
   includes only good channels- edit as needed.  The format of the
   file is:

<total channels> <channel number> <channel name> <channel number> <channel name>...

To simplify quick changes, you can add or delete channels in the channel file 
manually. Just be sure to adjust the total channel count at the head of the file
as needed.

USING THE SCANNER
=================

*** The firewire scanner should only be run with the MythTV backend server stopped ***

to stop the backend:

 $ sudo /etc/init.d/mythtv-backend stop

Replace "stop" with "start" in the preceding command to restart the backend when
you are finished scanning.

The command syntax for scanfw is:

 $ scanfw -i <channel file> -p <channel number> [OPTION]...

Mandatory arguments:
  -i <filename>         channnel file
  -p <channel number>   priming channel

<channel file> is the .txt file generated by mythtv.firewire.channels.pl

 Options:
  -b <channel number>   beginning channel
  -c <channel number>   single channel scan
  -e                    encrypted and errored channels only
  -f <changer>          force channel changer
  -n <number>           number of channels to scan
  -s <seconds>          pause <seconds> before reading CCI of channel
                        (minimum 3, default 4, recommended 6+)
  -w <channel number>   watch CCI of channel (^c to stop)
  -h help               display usage information


For example, to perform a scan of all channels, using file channels.txt, 
priming channel 32 and default values:

  $ scanfw -i channels.txt -p 32

This is the minimum number of arguments allowable.

Some options can be combined to extend functions.  For example, you can scan a 
block of channels by setting a beginning channel and number of channels to scan.
To scan 15 channels, beginning with channel 906, the command would be something
like:

 $ scanfw -i channels.txt -p 32 -b 906 -n 25

The single channel scan (-c) and watch (-w) options have the added capability of 
being able to scan channels *not* included in your channel file- to allow for checking 
channels new to your cable line-up or to re-check the status of an encrypted channel 
that has been removed from your line-up. However, it is still necessary to provide 
the channel file as an argument.

scanfw will *not* make changes to MythTV settings, nor the information in the database.
Any changes such as disabling channels or changing tuner settings is your responsibility
and at your discretion.


OPTION OVERVIEW
===============

-b <channel number>        begin the scan at the provided channel number

-c <channel  number>       performs a one-time scan for the provided channel

-e                         show only encrypted and errored channels in the final scan
                           report

-f <changer>               force channel changer:
                             1 = SA3250HD
                             2 = SA4200HD (and some 3250s)
                             3 = SA4250HDC
                             4 = SA4250HDC alternate (and 4240HDCs with 4250 firmware)
                             5 = SA8300
                             6 = Motorola Fast (DCH and DCT series)
                             7 = Motorola alternate


-n <number>                sequentially scan this number of channels only

-s <seconds>               <seconds> is how long the scanner will wait before reading the
                           encryption status of the channel.  This setting can make the
                           difference between a reliable and unreliable scan.  Please read
                           the included "SCAN_TIPS" file for further explanation

-w <channel number>        "watch" the specified channel continuously and display
                           the status and time of each CCI change.  This can be 
                           useful for troubleshooting problematic channels.
                           ^c to terminate.

SCANNING
========

As it runs, scanfw attempts to maintain a stable connection to the stb and will attempt
to re-prime if it encounters errors.  You will be alerted to any errors and recovery
attempts as they occur.  The recovery process can take some time, depending on how
quickly a reliable connection can be re-established.

If scanfw is unable to recover, it will report the channel as errored and continue to 
the next channel.  When all the channels have scanned, scanfw will try to re-scan the
errored channels.  A final report will then be displayed, with totals and lists of clear,
encrypted and errored channels.  Errored channels can be re-scanned using a combination
of the -b and -n options, to scan the block around them.

It is important to have patience- especially when recovering from errored channels. You
need to give the scanner time to recover and not assume the process has hung- as it very
likely has not.  For particularly "bad" channels, it is not uncommon for recovery to take
a minute or more.

If the connection is especially bad, it is possible that the channel change to the priming
channel may fail and scanfw will appear "stuck".  If this happens, allow plenty of time
for scanfw to right the situation- sometimes it will take a few channels erroring before
it stabilizes the STB.  If scanfw fails to stabilize and the STB misses six or more
consecutive channel changes when priming for recovery, you can stop the scan, re-prime
manually and then resume the scan just before the errored channels using the -b option.

There is also a possibility that the stb may itself become unstable and severely lag when
changing channels.  In most cases, simply powering down the STB for a few moments is enough 
to stabilize it.  However, rebooting the stb by a hard reset or physically disconnecting 
the power may be required.

STB instability can be caused by changing the channels too quickly.  If you have problems
with stability when running scanfw, increase the pause duration with the -s option.

Please see SCAN_TIPS for more detailed information on scanning.

