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:


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.