||<tablestyle="float:right; font-size: 0.9em; width:30%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents(3)>>||
<<Include(MythTV/Header)>>

'''''~+scanfw currently supports only Motorola cable boxes using the fast channel changing method. If this fails with your Motorola STB, please PM majoridiot for a fix. A Scientific Atlanta Version is in development and will be available for testing very soon. A forum announcement will be made when source and binaries are available.+~'''''

= scanfw =

Using a firewire connection to a cable set-top box (STB) as a MythTV tuner can be troublesome and an ongoing battle, due to channels being encrypted. scanfw was developed as a tool for MythTV users, to help identify and troubleshoot the encryption status of channels in their cable lineup.

It is very important to note that scanfw is only a tool and will likely require regular use to ensure a stable line-up. It is '''''not''''' a one-time magic bullet to solve all of your MythtTV firewire woes and using it as such may cheat you you out of channels you could be using.

== Installation ==

You can either compile scanfw yourself or download the most recent pre-compiled binaries and mythtv.firewire.channels.pl.

The source files can be found [[https://wiki.ubuntu.com/majoridiot|HERE]]

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.

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:

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

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

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

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

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

*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< >
-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 25 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

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

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

= Encryption Pitfalls =

Encryption of cable channels and the ability or inability to record them varies widely by
cable system and region. Depending on your cable provider, you may have full, conditional
or no encryption applied to your channels- and this may change from day to day or vary by
show.

It is important to always keep in mind that scanfw produces only a *snapshot* of your channels
for that particular moment in time. There is no guarantee that the encryption status will
remain that way. To get an accurate overview of the encryption status of your channels, you
will need to spend the time and effort to make multiple scans initially and then make a regular
practice of re-scanning periodically- especially if your recordings and/or LiveTV are failing.

The following encryption issues were encountered during the development of scanfw and are
important to keep in mind, as they may apply to your cable system/STB as well:

*Some channels assert encryption conditionally and/or by time of day- e.g. only during prime-time. It is also fairly common for a "normally clear" channel to assert encryption for certain programs only. This can be especially true for "original" or "exclusive" broadcasts.

*It is possible that a "normally encrypted" channel will report as clear if the channel is scanned during a commercial that does not have encryption asserted. This reinforces the need for more than one scan and for closely monitoring the program material being viewed by the scanner on the tv.

*When tuning a new channel, it is not uncommon for the CCI to cycle the encryption status back and forth for a few moments before stabilizing. Some channels are reliably worse than others and can take a number of seconds to stabilize the CCI. These channels may yield a false-positive for encryption if not given sufficient time to stabilize before scanning.

*It is possible for a channel to have bogus (malformed?) CCI information. Scanning these channels yields 50/50 reliability- depending entirely on the data or lack thereof. Testing has shown that these channels will usually display empty CCI, DRM, etc. when checked manually via the STB diagnostic screens but seem to be OK for recording. It is unknown at this time what causes this issue, other than it stems from the cable head.

= Scanning Strategies =

'''''REMEMBER THAT THE MYTHTV BACKEND SERVER MUST BE STOPPED WHEN SCANNING'''''

scanfw may need to recover itself from unstable situations by re-priming the STB. It is
critically important that the priming channel you provide with the -p option be a known-
reliable channel to prime with. For cable systems with analog channels, it is usually a
good bet to pick one of these, as they are normally unencrypted and stable. You can use
mythprime combined with manual channel changes to help determine a reliable priming channel.

Before scanning, you need to determine how much time it takes for your STB to acquire and
display a channel after a channel change. You should do this for both SD and HD channels,
looking for the *longest* average time- and then add at least two seconds to it. This is a
reasonable number to use for the -s option for a "quick scan", which is set at 4 seconds by
default. Although it is not recommended, you can set -s as low as 3 seconds.

When performing your scans, you should (if possible) watch the output of the scan, the stb
display and the tv, to be sure the scanner and stb are in synch and that the tv is acquiring
the channel properly. Some STBS do not like rapid channel changes and will skip or ignore
channel changes or become unstable. Increasing -s will usually fix these issues.

For the best results, you should scan the channels you want to record during the time of day
you would normally be recording. e.g. Late-night scans can have little relevance if you record
a lot of prime-time, etc.

A quick-scan, using the default of -s 4, will give you a fairly accurate snapshot of your
channels. However, due to the cycling CCI issue previously mentioned, quick scans can also
yield false-positives for encryption on clear channels- and vice-versa. Quick scans are good
for getting an overall picture of things, to help you narrow your focus to possible problem
channels, but should not be solely relied upon for configuring your final line-up.

The most accurate results are obtained by giving the stb plenty of time to stabilize after a
channel change, before scanfw reads the CCI. A value of -s 8 or more has been found reliable
at helping weed out problem channels that may report falsely.

= Scan Results: What Do I Do With Them? =

So you've invested the time and effort to do all of these scans, re-scans, etc. and now have
a fairly good idea of which channels are always or conditionally encrypted... but what do you
do with this information? The answer is totally up to you.

The "safest" thing to is to disable any channel that is encrypted, regardless of whether it is
conditional or not. This is your best bet for never missing recordings due to encryption- but
possibly at the expense of losing access to a channel that is clear the majority of the time.

Conditionally-encrypted channels can still be used by setting up recoding rules, etc. to handle
known conditionally-encrypted programs via an alternate method; e.g. pvr capture via coax.
MythTV is a highly-configurable environment and there are many rules and settings that can be
employed or developed to help you get the most out of your firewire connection. Given correct
setting and rules, the only problem with enabling channels with conditional encryption is when
tuning LiveTV to an encrypted program. Worst case, you will have occasional failed recordings
that you can develop rules to handle in the future.

You are encouraged to share your results and any rules, configs or work-arounds in the forum
or mailing lists. Your solution may be a lifesaver for a lot of other MythTV users.

= Source Files =

The latest source files for scanfw and other mythtv-related firewire tools can be found [[https://wiki.ubuntu.com/majoridiot|HERE]]