pvrusb2 driver utilities

$Id: utils.html 2032 2008-06-30 02:17:38Z isely $

Mike Isely <isely at pobox dot com>

This page briefly describes the usage of the utilities included with the pvrusb2 driver distribution.

You can find the main driver page on the web at http://www.isely.net/pvrusb2/pvrusb2.html.

Overview

The utilities can be found in the utils subdirectory. They include the following:

• 94-local.rules - This is a udev configuration fragment which can be used in conjunction with udev-pvrusb2 to automatically create predictable device access nodes in the file system (see further).
• change-channel.sh - This is a bash program which provides an interface for managing channel IDs and changing channels through the driver's sysfs interface. This script works with a configuration file that associates channel IDs with frequencies; it does not need or use the sysfs frequency table logic in the driver. This was created and contributed by Per Christian Henden; for his e-mail address and a description on how to use the script along with a brief method to generate the frequency data from xawtv, please see the comments at the top of the script.
• decode_eeprom.cpp - This is the source for a utility that can parse out an FX2 load image from an eeprom image. The FX2 loads code from a resident eeprom using packets in the eeprom. This program can parse each packet and emit a set of s-records of the contained data (which can then be fed to a disassembler).
• decode_log.cpp - This is a decompiler, which is used to interpret the USB traffic flowing between the pvrusb2 device and the driver.
• fwextract.pl - This is a Perl program which handles extraction of firmware data out of Hauppauge's Windows driver files. See setup.html and firmware.html for more information about this program.
• fwfind.sh - This is a contributed bash program which further automates firmware extraction. This is discussed briefly on the setup.html page.
• old-extract-firmware.pl - This is the old firmware extractor created by Björn Danielsson. Use the newer fwextract.pl program instead; this is included here for historical reasons and also as a last resort fallback in case problems are encountered with the new extractor (but please contact me if you find yourself having to use it).
• pvrui.sh - This is a contributed shell script that uses the dialog utility to implement a nice interactive front end to the driver's sysfs interface. This script was written by Phil Endecott; see the comments at the top of the script for his contact information. Note: This script is somewhat broken right now; it needs to be updated to account for new types possible in sysfs and the fact that enumeration values can have embedded spaces.
• udev-pvrusb2 - This is a script fragment which can be used in conjunction with 94-local.rules to automatically create predictable device access nodes in the file system (see further).
• usbreplayprep.pl - This is a Perl script which can postprocess USB sniffer output into a compact form that the decompiler can parse. This also originally came from Björn however it has been modified to also preserve data coming from the device (older version only preserved data going *to* the device).

Fun with udev and the pvrusb2 driver

Thanks to an intrepid user, Roger Allen, who got sick of the non-deterministic assignment of device nodes, we have a tool here that can be used to configure udev to assign a predictable name to each device instance. The solution is contained in the two files here, udev-pvrusb2 and 94-local.rules. This is by no means the only way to do it, but it is a good example. One could also probably use a variation to change the group and mode of the sysfs interface files too...

Rather than explaining this in my words, here's the description in Roger's words (note: I replaced the serial numbers with obvious fake values):

After spending months checking dmesg to see which of my two WinTV-PVR-USB2 devices would win the race for /dev/video0, I finally got around to learning enough about udev rules to straighten out my mess. I have Comcast Chicago cable with a single settopbox which is feeding the composite of one of the boxes, while the other one is connected directly to the coax and tuning the few (31 and decreasing) available unecrypted analog cable channels. This is working under Fedora 8 with mythtv rpms from atrpms. I tried to keep it simple so it only uses the shell and grep. Fedora doesn't have a "video" group, so this is using "mythtv" instead. I modified the mythbackend to run as "mythtv" instead of "root". Other dists will probably want to change the GROUP and/or OWNER or not use OWNER at all in the udev rule. The rule creates symlinks for /dev/comcasta and /dev/comcastd for Analog and Digital. There are comments in udev-pvrusb2 describing how to use it with mythtv-setup. I'm sure the shell script could be better written, but it works for me.

This mythtv backend also has a Kworld ATSC-110 using /dev/video2, which the script successfully leaves alone, so it should play nice with other video devices.

The single line udev rule goes into /etc/udev/rules.d/94-local.rules or whatever file your Linux distribution likes: [copy of 94-local.rules]

# local rules by rja for moria

# pvrusb2
# Create a symlink /dev/comcasta pointing to WinTV-PVR-USB2 with serial sn-7653922 tuning comcast analog
# Create a symlink /dev/comcastd pointing to WinTV-PVR-USB2 with serial sn-8257134 using composite comcast digital
KERNEL=="video[0-9]*", PROGRAM="/usr/local/bin/udev-pvrusb2 %m", SYMLINK+="%c", OWNER="mythtv", GROUP="mythtv"

The /usr/local/bin/udev-pvrusb2 script (don't forget to make it executable) is: [copy of udev-pvrusb2]

#!/bin/sh
#
# program: udev-pvrusb2
#
# author: Roger J. Allen - rja at rogera.net
# Wed May 28 12:54:18 CDT 2008
#
# help udev assign consistent device name
# for WinTV-PVR-USB2 by its serial number
#
# argument 1 is a device minor number from udev
# test which sysfs entry matches this minor number
# output consistent device name for udev to create a symlink
#
# in mythtv-setup "Capture Card Setup"
# set "Video device:" to the symlink instead of /dev/video*
# for capturecard videodevice
#
# sn-1234567 returns "comcasta" for comcast analog tuner input
# udev will create /dev/comcasta symlink
# sn-7654321 returns "comcastd" for comcast digital composite input
# udev will create /dev/comcastd symlink
#
# udev rule for Fedora 8 with my custom owner and group settings
#
# KERNEL=="video[0-9]*", PROGRAM="/usr/local/bin/udev-pvrusb2 %m", \
#        SYMLINK+="%c", OWNER="mythtv", GROUP="mythtv"
#

SerialNo1="sn-1234567"
Symlink1="comcasta"
SerialNo2="sn-7654321"
Symlink2="comcastd"

if [ 1 = $(grep -c $1 /sys/class/pvrusb2/$SerialNo1/v4l_minor_number) ]
then
	echo $Symlink1
	exit 0
elif [ 1 = $(grep -c $1 /sys/class/pvrusb2/$SerialNo2/v4l_minor_number) ]
then
	echo $Symlink2
	exit 0
fi
exit 1

Unless you break into my home and steal my WinTV-PVR-USB2s, change the serial numbers and symlink names to taste. If you have more than two devices, just modify the udev-pvrusb2 script.

You can mangle the bits any way you want. If you find that it needs tweaking for other Linux distributions, then please post your fixes.

Roger J. Allen
rja {at] rogera.net

Sniffing and decompiling USB traffic

There is a free USB sniffer that can be run under Windows for capturing all traffic between a USB device and its driver. The home page for it is here. Using this tool we can learn about how the Windows driver operates the device. If you want to explore, download that tool and follow the related instructions.

To help with understanding the log data from the sniffer, there are two tools provided with this driver:

The first tool is usbreplayprep.pl, which will preprocess the USB sniffer data into a more compact form. This tool was originally written by Björn but I have since modified it to provide more data. The version provided here saves both directions of traffic; the previous one only saved data going in the driver-to-device direction.

The second tool is decode_log, which is compiled from the similarly named C++ source file. This program interprets the output from usbreplayprep.pl and produces a concise listing of all the commands and data moving to / from the device and the driver. (This tool can also capture and save the encoder firmware if seen as part of the log.)

The decompiler is a 2-weekend hack that I wrote in C++ and must be built first. Run make in the utils directory to build this tool. Note that this program has no other dependencies beyond needing C++ so it should be a straight-forward build.

To capture and decompile a session with the device when run with the Windows driver, do the following:

1. Boot windows, start the sniffer and enable it, and plug in the device.
2. Run your TV app for a little while. NOTE: The sniffer log data can get ENORMOUS so you may not want to run it for long. Also the capture process does slow things down so the video playback in the TV app might get choppy, but that's OK.
3. Copy the log data to your Linux system or reboot to Linux
4. Run usbreplayprep.pl < data.log >data.txt where data.log is the name of the log output from the sniffer.
5. Run decode_log < data.txt > data.src and the decompiled output will be in data.src.

The decompiler also has an option for saving off the encoder firmware captured, which is useful when one has to figure out the firmware extraction details for a newer Hauppauge driver snapshot. There's lots more about that feature described in firmware.html.