$Id: pvrusb2.html 2449 2010-04-24 20:15:41Z isely $
Mike Isely <isely at pobox dot com>
The home location for this page is here.
If you have any suggestions for improving either this web page or the driver itself, please drop me a message.
Contents
Contacting People / Discussion List
Overview
Download
Setup
Usage
FAQ
Utilities and Misc
Bugs
Change History
If you wish to contact me, my e-mail address is spelled out at the top of this page.
There is also a pvrusb2 e-mail discussion list, hosted here at this site. This is a mailman-operated list, so you can subscribe, unsubscribe, access your subscription, scan archives, etc via the web. (You can also initiate a subscription by sending a message to <pvrusb2-subscribe at isely dot net>.) Any pvrusb2 relevant topic there is fair game. Posting to the pvrusb2 list is limited to just subscribers, but I encourage you to subscribe to the list. The main web page for the discussion list can be found here.
Note also for those who use chat systems, the IRC channel #pvrusb2 exists on freenode. When I'm logged in, I tend to idle there, with the handle "mcisely". I also have that same handle on AIM, jabber, googletalk, and Yahoo (but not on MSN). Unfortunately these days I have a hard time actually being "there" and IRC doesn't really have a good means to show when one is away. Feel free to ping me if you'd like, but if I fail to answer then I'm probably elsewhere - in which case e-mail is a better bet to find me.
The pvrusb2 driver described on this site is a Linux driver which operates a particular class of USB-hosted analog TV tuners that include hardware mpeg encoding capability. A video4linux (V4L) interface is currently presented to the application. In addition to the V4L interface, there is also a sysfs interface and a DVB interface (currently just for streaming digital tv on hybrid devices).
Another driver similar to the pvrusb2 driver is the ivtv driver. The primary difference between ivtv and pvrusb2 is that ivtv targets PCI-hosted tuners while the pvrusb2 driver focuses on USB-hosted tuners. Though the two drivers share a lot of common logic and internal hardware (all physically shared via the V4L core), ultimately their control pathway is different enough that the two drivers must be, well, two different drivers.
The pvrusb2 driver is designed for USB-hosted TV tuners which contain a Conexant cx23416 (or similar) mpeg encoder chip. This encompasses a class of USB analog and hybrid tuners which advertise the ability to encode video and audio into an mpeg stream - directly in the hardware - an ideal feature for use in PVR applications such as MythTV.
A USB-hosted tuner is an external device, connected to the PC through a USB connection. A USB 2.0 high-speed capable bus is usually expected but an mpeg compressed stream configured with default bit rates can in fact work acceptably well even over a USB 1.1 full-speed pathway. Compared to PCI card based TV tuners, a USB-hosted TV tuner is suitable for laptop, xbox, or embedded device applications where there would otherwise not be a PCI slot available. The cx23416 mpeg encoder chip consumes more power than can be supplied over the USB cable so one should expect these types of tuners to always require an external power brick.
The pvrusb2 driver was originally written with the Hauppauge PVR USB2 device in mind (hence the name, see further), however the PVR USB2 is actually a very popular evolution of a common reference design. There are other (less common) variations that exist from other vendors. The following subsections summarize currently supported devices.
The most common pvrusb2-driven device is the Hauppauge WinTV PVR USB2, which is a USB 2.0 hosted TV Tuner. Though this device is no longer for sale new within the US (thank you, FCC... NOT), at this moment (March 2009) you might still find an example at pricegrabber. This device is an analog tuner, but it has a hardware mpeg encoder, which makes it ideal for use in PVR applications. Functionally, the "PVR USB2" device is very similar to Hauppauge's line of "PVR-nnn" PCI based tuner cards - except this device of course uses USB instead of PCI.
Please note carefully the name above: WinTV PVR USB2, which unfortunately is very close to the similar sounding Hauppauge WinTV USB2 (note the lack of "PVR" in the name) which is in fact a completely different and less capable device from Hauppauge. The pvrusb2 driver will therefore never work with a WinTV USB2. (See here for a driver that should work with the WinTV USB2 hardware.)
There are two major variants of the PVR USB2 hardware in circulation. They can be physically distinguished by the white sticker on the underside of the device - the retail boxes are identical, unfortunately. You can also distiguish the two variants through the USB ID reported to the host when the device is plugged in.
This driver is intended to work with all hardware versions. The driver is equally stable in all cases. See the Bugs section for more details. Also, the firmware situation and chip-level modules are different in the two cases, which may impact how you set things up. The documentation on this site covers all model variants.
Over time I've been collecting a census of the various Hauppauge model variants in circulation. You can find the current results in models.txt; please e-mail me if you would like to add your device to the tally.
The Hauppauge WinTV HVR-1950 is a hybrid tuner and the successor to the older PVR USB2. It has all of the features of the PVR USB2 (analog TV and FM tuners, hardware mpeg2 encoder, composite / s-video capture inputs). Plus it can tune ATSC digital broadcasts as well as analog. It is also physically smaller than the PVR USB2. This item can be found at pricegrabber.
The Hauppauge WinTV HVR-1900 is a similar device but is intended for DVB-T reception instead of ATSC (thus it is marketed in the UK and not in the USA).
The pvrusb2 driver fully supports these devices (analog and digital) however FM radio support isn't there yet, owing to some subtle hardware issues. The analog side operates exactly the same as the common predecessor PVR USB2. The pvrusb2 driver's DVB interface is used to access the digital side.
The HVR-1950 and HVR-1900 "look" the same to the pvrusb2 driver; thus anywhere I refer to one, the other always applies. Warnings / caveats about the HVR-1950 in particular likely also apply to the HVR-1900. Throughout the rest of this documentation these will be referred to as "HVR-1950" hardware.
The OnAir Sasem and OnAir Creator devices are hybrid tuners. There is no FM radio. The digital side is handled via DVB and the analog side through the usual means in the pvrusb2 driver. Their operation is identical from the application point of view (minor internal differences, handled by the pvrusb2 driver). They are fully supported by the pvrusb2 driver.
Throughout the rest of this documentation these will be referred to as "OnAir" hardware.
The GOTVIEW USB 2.0 DVD2 and USB 2.0 DVD Deluxe are tuners from a Russian(?) vendor. I don't speak / read Russian, but thanks to another user of both of these devices I've implemented some minor changes that allow this device to work. I've had a few pings from people asking if the pvrusb2 driver could be made to work with this device, and after some trial & error, it is working (including the FM radio for the "DVD 2" - the "DVD Deluxe" does not have an FM radio).
Where it matters, this documentation will refer to the "GOTVIEW USB2.0 DVD2" and "GOTVIEW USB2.0 DVD Deluxe" as simply "Gotview" hardware
This driver is very much a work in progress. Its history started with the reverse-engineering effort by Björn Danielsson whose web page can be found here. From there Aurelien Alleaume began an effort to create a video4linux compatible driver for the original PVR-USB2 29xxx series device. His web page about this driver can be found here. However after October 2004, work there seemed to have stopped and repeated attempts to contact him over several months since then were not successful. The driver hosted here picks up from that point. I have been maintaining / improving this since February 2005.
There are three variations of this driver available. One is here on this site. Another is hosted within the official video4linux Mercurial source tree, and the third variation is available in the Linux kernel tree, as of version 2.6.18. I maintain them all and they are closely related. You can use any; the "master" version is currently the standalone version on this site; the others are derived from here. As for deciding which you might want to try: The version in the kernel is of course considered to be the most stable, so if you are using 2.6.18 or later (and your hardware is supported by that particular vintage of kernel) then just stick with that. The version in V4L is more bleeding edge than the kernel and what's in V4L today is expected to always be what gets into the next kernel release. If you want a more recent version of the driver and if you are already into building & running all of V4L then the V4L version is probably what you want. If on the other hand you want the absolute latest version available and just want to get this one driver working (damnit!) and don't want to learn about Mercurial (V4L's source code manager), and you don't like the idea of pulling in 50+ modules just to run one piece of hardware, then you may prefer to run the standalone version hosted here. It's up to you. Right now the way I do development is that the standalone version is the "primary" version. All others derive from this version. To update the V4L version I process the sources through a Perl script that reconfigures the driver for use inside of V4L (strips out source files and code that don't make sense there, and enables some bits for in-V4L-tree operation that might otherwise be shut off). The kernel version is processed out of V4L. I'm using Subversion to maintain the driver sources and do diff / patching as needed for any changes from that come back my way, regardless of variation.
Note: Even if you choose to run the in-kernel version or V4L hosted version of this driver, you will still need to obtain (extract or otherwise fetch) and install the firmware. There is an extraction script but it is not part of the V4L repository or the kernel tree. If you need just the extraction script (something normally contained in the standalone driver snapshot), you can download a reasonably recent version from here: http://www.isely.net/downloads/fwextract.pl. However, please see here for additional important information regarding how to obtain the firmware.
An aside: The fwextract.pl program code itself is written without anything specific to the pvrusb2 driver. It is a general purpose generic binary extractor that uses configuration records appended to itself in order to know how to find target images. Thus it can be applied to other drivers, other extraction tasks if so desired. All that is required is configuration data which the script itself can generate during a training process. I long ago GPL'ed this code so other developers are welcome to try it if desired; contact me for information about additional features in fwextract.pl that help with its configuration.
If you have trouble getting the driver to work, please read through this site again - there are a lot of details here and it is easy to miss something. Also, I've written a short FAQ covering common situations that people have found themselves in. Try scanning the mailing list archives here. If none of that helps, send me a message or subscribe and post to the mailing list (information here) - it's entirely possible that you might have encountered something new and thus I want to hear about it so I can address the problem for everyone...
Driver snapshot downloads can be found here.
The latest firmware extractor (also included in each driver snapshot) can be found at http://www.isely.net/downloads/fwextract.pl
The encoder firmware for OnAir hardware can be found at http://www.isely.net/downloads/autumnwave-v4l-cx2341x-enc.zip.
To operate your pvrusb2-driven device in Linux, there are several prerequisites and a number of things you must do first.
You must satisfy at least these prerequisites before the driver will work:
The Prerequisites / Compatibility section of setup.html has the details for the above.
There are 3 basic steps you must complete in order to operate your PVR USB2 device in Linux:
If you are trying the in-V4L or in-kernel driver version, then the compilation steps above are a part of the surrounding build and so you don't have to do anything special there. However even in that case you still have to deal with the firmware part of the puzzle.
The following sections of setup.html have the details for getting your PVR USB2 device working:
Driver compilation and installation
Firmware retrieval and installation
Support Modules
The page usage.html has everything you ever wanted to know about using this driver, but contained below is a basic summary to get you going.
Plug in your tuner device and after a few seconds the driver should be ready to go. Progress can be monitored through the kernel log.
Provided that you have udev installed on your system (a fairly safe assumption these days), then within a few seconds after the driver initializes, you should see something like this appear in your system: /dev/video0 (if this is the only video device in your system). If you're not running udev, then you need to make sure that appropriate /dev entries have been configured into your system; details for that (e.g. correct major / minor numbers) are a V4L specific issue and outside the scope of documentation. Really, save yourself a headache and just use udev...
Once you have a valid /dev entry, then you can start playing! Any V4L application which can handle mpeg stream data should be able to work. You can also just "cat" /dev/video0 and you'll get a stream for whatever the device is currently configured to capture (television, radio, composite, or s-video).
In addition to the V4L API, there is limited support for DVB - for handling the digital side of hybrid devices (e.g. HVR-1950, OnAir).
This driver also implements a sysfs-hosted interface, which can be found in /sys/class/pvrusb2/sn-xxxxxx or /sys/class/pvrusb2/unit-c (depending on whether the hardware type reports a serial number or not). Through that interface you can operate the device right from your shell prompt without need for any kind of utility program(s). The driver snapshot even includes some contributed shell scripts that do exactly this.
For significantly more information how to use this device, please don't forget to examine usage.html.
I've written up a short (but unfortunately now very old) list of common mis-steps and solutions encountered by people trying the driver. If you have any suggestions for things to add here, please let me know. Hopefully you can find your situation described here.
The driver package includes a few utilities and miscellaneous info related to operation of this device. This topic can be found in utils.html.
The driver itself also implements an optional debug interface. It must be compiled into the driver. Information about the debug interface can be found in dbgifc.html.
Stability appears to be pretty decent overall. Well except for what's below... Current known problems:
There is a new problem with initialization of the original 29xxx devices - sometimes it just fails to initialize. This only happens with newer kernels, on certain machines. I have not been able find a pattern to this at all except to conclude that the trouble is apparently not inside the pvrusb2 driver. Rather it appears that with just the "wrong" hardware, timing, and kernel version, then the 29xxx device's FX2 firmware won't correctly initialize with the Linux USB core. We're not even in the pvrusb2 driver when the trouble starts. This only affects the original 29xxx device series; 24xxx devices and everything else since then seems to be fine. Hopefully not too many people are affected by this...
I have already done a lot of work trying to bracket the symptoms. Rather than repeat it all here, there are two posts on the pvrusb2 list that summarize everything I've learned about this. You can find the posts here, and here. Any suggestions?
For all hardware device types, there are certain values for horizontal resolution which produce distorted video. This might be a hardware limitation, so I might "solve" this by just causing the driver to round-away from the bad values. Currently this formula can be used to predict if a given horizontal resolution is watchable:
watchable = ((hres - 1) >> 1) & 1) != 0
For a given choice of "hres", if "watchable" is true then it should work.
For all hardware device types, there is a problem with distortion in the audio when the volume is set too high. The pvrusb2 driver starts with the volume set to the max, so you get the distortion. A while back (I think kernel 2.6.15 and previous), the msp3400 chip-level driver scaled back the requested audio gain so that "maximum" worked out to be a reasonable maximum for the part (apparently). Versions of msp3400 after that point eliminated the scaling, so now "maximum" is simply mapped by that chip-level driver to be the largest value possible that can be programmed into the chip. The pvrusb2 driver currently doesn't attempt to scale this value - it just passes the value through, untouched, to whatever chip-level driver is interested - so now the result is clipping when the volume is at the max.
Though the msp3400 chip is specific to the 29xxx model series, the same problem appears with the cx25840 chip in the 24xxx model series and Gotview hardware as well. The workaround is easy: lower the volume. Empirical testing here (on both types of devices) suggests that right now 58000 is a good value for maximum gain distortion free audio.
Probably the right thing to do here is to have the pvrusb2 driver attempt to scale the volume as appropriate for the model / hardware since it's really only at that place where we know what's "right" for the entire combination of hardware that defines the device as a whole. This has been on my to-do list for a while, but it just hasn't been a priority for me since the workaround is fairly trivial (e.g. just reduce the volume).
Note: the default volume level is set now at a point where there isn't any distortion.
There is a problem on older 29xxx hardware (saa7115 + msp3400 chips) with the audio when switching away from the FM radio - the audio drops out. This definitely happens when switching to television mode. Changing frequencies after that point seems to clear it. The problem appears related to recent changes that implement V4L sub-device support.
Current missing features:
No FM support on HVR-1950 (still, as of March 2009). Solving this requires some enhancements to the cx25840 chip-level driver and possibly also the pvrusb2 driver. Not a showstopper, but this will take some additional time.
No VBI support. This is a much harder problem. In fact I find it amusing that apparently the Windows driver doesn't support VBI either. However after a short conversation with the current ivtv maintainer, I understand now how they made it work in ivtv and I believe a similar implementation should be possible here. Update: With the extinction of NTSC OTA television here in the USA, it is highly unlikely that I will ever implement this ability. For one thing, I will now have an extremely hard time testing it.
No raw video support. i.e. uncompressed video frame data that one would see from a capture card that does not have an mpeg encoder. The pvrusb2 driver was never written with raw video in mind - and until recently it was thought not to even be feasible. However a workable solution is understood now and I will see about implementing it - but it will be a large driver change.
Limited DVB support. If you are using a hybrid tuner, then a DVB interface is available for the digital side of the tuner, but that's it. A long term goal is to have the V4L and DVB sides on equal footing.
No support for any v4l I/O methods except for standard read() style streaming. This is not such a big problem that one might think - the other two v4l I/O methods are really intended for fast transfer of very large amounts of video data with hard record boundaries. What we have here however is a simple byte stream with significantly lighter bandwidth demands (after all, this is compressed mpeg2 video data we're talking about). The v4l spec discourages use of read() since there's no way to frame such data - but in our case there is no framing needed anyway so it isn't a real issue. However, for completeness - and once raw video support appears - the other two methods need to be implemented. The driver as it exists now has an abstraction layer on top of which this may be done; it just hasn't been done yet.
Change history can be found here: history.html
Note: If you are viewing a local sandbox copy of this page, the file history.html will not exist. This file is generated from change_history.txt which you can find in the same directory.
Feel free to e-mail me (address at the top of this page) if you have any questions or just want to say hello...
Mike Isely