pvrusb2 driver usage information

$Id: usage.html 2476 2010-05-30 21:19:12Z isely $

Mike Isely <isely at pobox dot com>

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

This page describes how to use the driver, including module options, interface control, and information about driver-specific effects with certain apps.


Driver logging / parameters
Hotplug behavior / recovery
V4L apps
xine and vlc
DVB Interface
Sysfs Interface
IR handling
Radio Mode
Frequency Table
Playing well with others

Driver logging / parameters

The level of log verbosity within the pvrusb2 driver is controlled through a global bit mask variable whose name is debug. This mask is set initially at compile time; you might want to change it. Set / clear bits in this mask to enable / disable various forms of logging to the kernel. The default value of this bit mask is currently fairly quiet.

The debug bit mask definitions are all contained in the driver source inside pvrusb2-debug.h. The bits are generally organized in order of increasing noise level. There are three ways to adjust these bits:

There are a number of module parameters you may specify to the pvrusb2 module when it is loaded; none however are strictly needed. Note that these parameters are also all visible at run-time by examining the directory /sys/module/pvrusb2/parameters/. Most parameters there are read-only (because they only are looked at during initialization). However as pointed out above the debug parameter in particular can be changed at any time simply by echoing a new value into its file name within that directory.

Note that unless otherwise pointed out, these parameters are global to all instances of the driver (i.e. if you have two PVR USB2 devices plugged in the effect is the same on both corresponding driver instances). The following parameters exist:

(Think ConTroLCHanGe - yeah I stink at creating names.) This enables an optimization in the driver involving update when controls are changed. The default value of zero means that any control change are always propagated to all affected logic. If the value is set to one, then a given control change will only be propagated if the new value is actually different than the previously known value. Enabling this can speed up frequency changes (slightly) for applications that insist on dumping out piles of other redundant control changes at the same time.
This controls logging verbosity. This is a bit mask, though unfortunately you get to specify it as a decimal number (get out your hex / decimal calculator). The bit definitions are in the header pvrusb2-debug.h, and a default value is set near the front of pvrusb2-main.c. You can change this mask at any time via sysfs (the directory just mentioned above); the effect will be immediate.
This prevents the pvrusb2 driver from attempting to automatically, explicitly load an IR handling module (e.g. ir-kbd-i2c). The default state of this option is "0", i.e. "disbable_autoload_ir=0". (Note that for the 20090509 standlone snapshot this option defaulted to "1".) Previously the pvrusb2 driver made no attempt to load any such module since lirc is also a valid choice and autoloading one particular choice will interfere with other possible choices. However there are changes coming which force this issue so now the pvrusb2 driver normally will attempt to autoload "ir_video" (which will cause ir-kbd-i2c to be pulled in). But if you don't want that to happen, set this option to "1". See the IR handling section for further information about this.
This parameter when set to non-zero enables a full scan of the internal I2C bus as part of the initialization of the device. The results of the scan will go to the kernel log; driver operation itself is unaffected.
This parameter defines a wait time to be used after forcing a reset of the device hardware. The units are milliseconds. The idea here is to allow the hardware some settling time after a reset, before we start poking at it again. The default is currently zero (because at the moment it appears that there is no wait time needed).
This parameter when set to non-zero enables the issuance of a USB-standard reset command to the PVR USB2 device when it is probed. It might help recover from a stuck device (which is why I implemented it) but I haven't actually seen it help when I've tried in the past. It is on by default since it shouldn't hurt. Important note for later kernels: This parameter is deprecated. It is fact no longer implemented for the in-V4L driver or for the standalone driver in any kernel 2.6.27 or later. In those cases using it can lead to a fatal deadlock between the driver and the USB core. I only continue to list it here for older kernels.
This parameter allows you to enable / disable the IR receiver on a per device basis. This parameter takes a list of comma-separated values; each value is used for successive instances of the driver (i.e. you can disable IR reception per-instance). By default IR reception is enabled. To disable the IR receiver, specify a zero here for each specific instance to disable. (Any other value currently indicates that IR should be enabled.) This feature is useful in cases where there are multiple PVR USB2 (or other IR-receiving) tuners and you want to designate one specific instance as the IR receiver. Note that actual IR reception is handled by code outside of this driver; what this option does is to prevent that outside code from detecting the IR receiver chip in devices where you have disabled reception.
This parameter when set to non-zero permits the driver to forcibly reload the microcontroller firmware as a recovery strategy from a failed device initialization. It is off by default because I haven't it found it to be too helpful.
This parameter allows you to force the driver to use a specific v4l minor device number for the radio device (assuming that the requested value isn't already allocated elsewhere). This parameter takes a list of comma-separated values; each value is used for successive instances of the driver (i.e. you can specify this per-instance). Some advice: If you find yourself having to play with this option, I suggest instead that maybe you should try setting up udev.
This parameter allows you to specify a tolerance level for dealing with USB streaming errors. This parameter takes a list of comma-separated values; each value is used for successive instances of the driver, providing you a way to raise the tolerance level for a specific device that you know might be connecting through flakey intervening hardware. The default is zero, which means no errors are tolerated at all and if one is encountered the stream will be terminated. Otherwise a non-zero tolerance value specifies how many consecutive errors will be ignored before the stream is errored-out. (If a URB succeeds after a failure, the running error count will be reset back to zero, thus what this option does is permit the driver to tolerate a certain level of spurious errors.) Note that errors ignored means that data will be lost and there will likely be a discontinuity in the stream data. You might realize that this parameter is "pasting over" what is probably a real problem in your USB controller, cabling, and/or core driver software. Don't use this lightly. I would suggest this as an act of last desparate resort if you can't otherwise solve your flakey hardware problem. Realize that even with a non-zero tolerance value, errors during control transfers are still not tolerated at all and will likely kill the stream - if you're lucky. It would be much better to just solve the underlying problem(s) in your system - but if you can't, then well I guess you can just tell the pvrusb2 driver here to try and tolerate some level of junk.
This parameter allows you to override the v4l tuner type associated with the device. Normally the correct value is detected through a scan of data from the device's internal eeprom. If however there is a problem with that (which has been known to happen in the past due to bugs, missing mappings, etc) and if you know what the correct actual type should be, then you can use this parameter to work around the problem. This parameter takes a list of comma-separated values; each value is used for successive instances of the driver (i.e. you can specify a tuner type per-instance).
This parameter allows you to force the driver to use a specific v4l minor device number for the vbi device (assuming that the requested value isn't already allocated elsewhere). This parameter takes a list of comma-separated values; each value is used for successive instances of the driver (i.e. you can specify this per-instance). Some advice: If you find yourself having to play with this option, I suggest instead that maybe you should try setting up udev. Important: VBI is not yet implemented, so this option doesn't do much. But it's documented here since the option technically is present.
This parameter allows you to force the driver to use a specific v4l minor device number for the video device (assuming that the requested value isn't already allocated elsewhere). This parameter takes a list of comma-separated values; each value is used for successive instances of the driver (i.e. you can specify this per-instance). Some advice: If you find yourself having to play with this option, I suggest instead that maybe you should try setting up udev.
This parameter allows you to specify the initial video standard to use with the device. This is a per-instance driver option. The value is interpreted to be a bit mask as defined by the V4L v4l2_std_id type. Note that even if you use this option, an application can still change the video standard choice to something else. Also, if the choice falls outside the set of supported video standards as reported by the eeprom, then that set is expanded to include this value.

Hotplug behavior / recovery

The pvrusb2 driver should be robust enough now that it can survive about any hardware abuse you can throw at it. There are no known situations where it should ever generate a kernel oops. You should be able to plug / unplug the hardware or insert / remove the driver (or just about any support module) to your devious heart's content and the Linux kernel should just keep merrily going on its way. (Obviously if you find out otherwise, please let me know.)

There is one potential issue however with the device itself. From experiments I have done, it seems that if the device is in the middle of transaction with the driver, that unplugging the device at that instant can leave it in a useless (maybe crashed?) state. The only recovery is to power cycle the device. I have tried numerous approaches to implementing automatic recovery in the driver, but there doesn't seem to be any strategy possible that guarantees recovery. However I did the next best thing: If the driver detects that the device might be jammed, it will log a message suggesting that the device be power cycled. The driver should come through all this just fine of course. (Update 4-Jan-2006: It has been a very long time since I've seen this problem repeat; it might have been something else long since fixed in the driver.)

V4L apps

This driver provides an implementation of the video4linux version 2 and version 1 driver APIs. Any v4l application which can handle an mpeg2 stream should in theory be able to use this driver. (Unfortunately there seem to be very few v4l apps which can...) If the v4l app you want to use does not support decoding of an mpeg2 stream from the driver, then it will definitely not work.


One application you can try is xawtv 4.x. Note that anything before version 4 will definitely not work with this since earlier versions did not support mpeg2 decoding.

Note that when you compile xawtv, make sure that you've configured it for mpeg2 video decoding and mp3 audio decoding. The app's configuration process tries to detect what libraries you have installed on your system, and if it doesn't find what it is looking for then it will silently disable parts of itself, i.e. no mpeg2 decoding. Inspect the configuration output and make sure it looks OK...

The xawtv application seems to have a number of rough edges. Best advice is to make sure you're running a recent snapshot. Some specific details:


Another application that works is mplayer. There are three ways to use mplayer: You can tell mplayer it's dealing with a V4L tv device, you just pass it /dev/video0 (or whatever the right name is on your system) as the "file" to play, or you can run mplayer in pvr mode.

The first method does not work. The second method (pass the device name as a plain file argument) however works well. The reason why you just can't tell mplayer it is talking to a V4L tv device is because once you do that then mplayer goes "dumb" and decides to only attempt streaming of uncompressed video (i.e. no mpeg2 streaming), which of course won't work since our hardware here produces mpeg2...

Unfortunately that second method also means you can't use mplayer to control the various V4L specific attributes of the device (e.g. frequency, volume, etc) since after all in this case mplayer is unaware that it is working with a V4L device. This means that when running mplayer you must do something else alongside mplayer in order to control the device. Basically we're talking about an arrangement where mplayer is showing you the output but you have to use some other method to provide control input. I test a lot with mplayer, and in my case I just use the driver's sysfs interface. But I've heard of other stories where people have used for example xawtv (3.x) in parallel with mplayer, or even an ivtv utility (e.g. ivtv-tune) to control the device. The pvrusb2 driver supports multiple opens of course so you should be able to use any other app (or just sysfs) as a control interface while mplayer is running (or before starting it).

Then there's also that third method: pvr mode. In this case you prefix the device path with "pvr://", e.g. "pvr://dev/video". Doing this causes mplayer to use the V4L API similar to that first non-working method however now an mpeg stream is expected. Thus you get the best of both worlds. In addition, when in this mode mplayer enables another option "-pvr" that gives you access to the extended mpeg encoder controls available from V4L drivers (such as pvrusb2) which use a hardware mpeg encoder (read the mplayer man page for details). This should work well with the pvrusb2 driver, though I personally have not exercised this a lot.

Several people have encountered problems reading pvrusb2 output with mplayer if the the avisynth.dll codec is installed in mplayer. This can be found in /usr/lib/win32/avisynth.dll. I can't profess to know what that codec might provide (or even if it is a codec) since I don't use it. However for those who have encountered problems in mplayer with this driver, removing this codec solves the problem.

One issue I've seen with mplayer: It sometimes poorly handles things when the mpeg2 stream is temporarily disrupted. A disruption can happen if for example you change the channel, or if the RF signal is lost. This seems to confuse mplayer in such a way as to cause the audio and video to get out of sync. If the "gap" is small enough then mplayer seems able to bring things back into sync within a few seconds. But the larger the gap, the less likely it is that it will recover. How do I know this is mplayer and not the driver? Because if I instead cat the video stream into a file, introduce a gap there, and then later play that file with mplayer, then it works fine. It seems that mplayer is sensitive to real-time pauses in the video, and since playing back the recorded file means there is effectively no real-time pause, then it's fine. I can make this issue happen using both 24xxx and 29xxx devices, but it seems more likely to be a problem with 29xxx devices. This might be because 29xxx devices might simply be a little slower in reacquiring video sync after a channel change (the digitizer chip is different between the two).

xine and vlc

Similar to mplayer, xine and vlc are reported to work provided you treat the device file as just a normal file with mpeg contents. There is a v4l mode apparently for xine (I haven't tried it), but I've heard that it is very immature and definitely does not work with this driver when run in that manner. I've been told that these example invocations should work:

xine - < /dev/video
vlc - < /dev/video

For vlc, I've heard later reports where the above didn't work. I'm really not a vlc expert, but I've also seen this work:

vlc stream:///video/video0
cat /dev/video0 | vlc stream:///dev/stdin


It is possible to get Kaffeine to work with this driver (streaming only?) using the following MRL:



This is a relatively new application - built with Tcl/Tk - designed to provide a simple means to just watch and record TV programs. The author, Christian Rapp, has using the pvrusb2 driver as one of his test targets so it should play quite well with the driver. This project was recently moved to sourceforge: http://tv-viewer.sourceforge.net

I've also periodically used this project as another means to test the driver. Anyone considering xawtv should probably give this a try as well.


The MythTV application of course is the holy grail for this driver. I got sucked into this whole effort because of this desire. This driver is known to work well in MythTV.

If you want to try MythTV, here are some tips:

The MythTV wiki has a nice page (http://www.mythtv.org/wiki/Hauppauge_WinTV-PVR-USB2) about using the pvrusb2 driver. The page's author (I didn't write it) apparently put it together from his own experiences with the device in combination with the driver and the notes you see from the various parts from the pvrusb2 web site here. The additional perspective provided by that article might provide further clarity on the subject.

MythTV is of course also a DVB application. It should work fine with the DVB interface provided by the pvrusb2 driver, when operating the digital side of a hybrid device. You should be able to specify both the V4L and DVB interfaces to MythTV, which would then allow you to fully utilize the hardware.

Note that in the case of hybrid devices supported by this driver with DVB, only one interface (V4L or DVB) can be opened / streamed at a time. After all, there's really only one tuner here - it just operates in two modes. It is possible under certain conditions that MythTV may erroneously try to open both interfaces at the same time, which of course fails and you don't get a recording. When you first configure MythTV there is a way to relate the two interfaces so that MythTV won't collide with itself. However even when you do this, it still won't stop a collision if you have EPG enabled on the digital side. The term "EPG" refers to the Electronic Program Guide, which is a means where MythTV can get upcoming program information from the station(s) themselves. However if you do this then MythTV opens the DVB interface and listens for that information, without regard to whether or not it wants to use the analog side, thus the analog side gets locked out and you get errors. So, cutting to the chase, you probably do not want to enable EPG when you use this driver (unless of course you don't ever use the analog side or maybe you have two devices and want to dedicate one to just EPG retrieval and digital recording).


I think one of the best v4l TV apps out there is tvtime. It's got a clean and simple interface, yet is very powerful and just produces a wonderful video image.

Unfortunately tvtime does not support mpeg2 decoding and thus has no chance of working with the pvrusb2 driver.

Realize that this isn't so much a deficiency of tvtime as it is a result of its overall architecture. The tvtime app is designed to work directly with uncompressed video frames from a capture device. As such, it relies on the capture device for video frame timing, and hardly has to bother with audio (since for an analog capture card the audio is usually directly shunted to the line-in of your sound card). To support mpeg2, tvtime not only must decode the frames, but it must also generate its own timing. It must also deal with audio decoding and therefore also implement its own communications pathway into your sound subsystem. And it must do all that while keeping the audio and video in sync. None of that is impossible, but I have been told that it pretty much completely contradicts the internal architecture of tvtime. It seems doubtful that tvtime will ever support a v4l device which speaks mpeg2. It'd be great if it did handle mpeg2 - that nice interface is something I dearly miss. But I'm not holding my breath for it to happen.

Other V4L info

Please contact me if you find other apps which work, and I'll list them here.

This v4l implementation should allow for multiple opens. Said another way, if you have one application reading video from /dev/video0, it should be possible to have another application still open /dev/video0 and successfully manipulate driver controls. Of course, only one application at a time can stream video. A second attempt at streaming will be greeted with an I/O error.

DVB Interface

The pvrusb2 driver exports a limited DVB interface. This will be created if the device being handled is a hybrid (i.e. has a digital tuner). Right now the only means to access the digital side is through the DVB interface. Similarly the DVB interface does not operate the analog side, which is why this interface is currently only made available for hybrid devices.

I have not yet gained a lot of experience in playing with DVB apps, however the DVB interface is well defined so I would expect about any DVB supporting app to be able to operate the digital side of pvrusb2-supported hybrid tuners through this interface.

MythTV is a well known app that uses DVB. This driver should work with it. For more information, see the MythTV description here.

In the long term I would like very much to put the V4L and DVB interfaces on an equal footing. It would be a lot simpler conceptually if all features were equally available through both interfaces. The fact that the hardware mpeg encoder can make the analog side "look" like a digital stream should in theory make DVB operation of the analog not impossible. But right now this is not the case, and thus the DVB side is limited to digital tuning and the V4L side is limited to analog tuning.

Sysfs Interface

There is an additional interface available with this driver. In parallel with the v4l interface, you can access all driver controls via sysfs. Once the device is plugged in and the driver is loaded, try this:

# cd /sys/class/pvrusb2/sn-XXXXXXX

where XXXXXXX is the serial number of your device (just let tab-completion do the hard work here or use "*" since unless you have multiple tuners there will only be one file there anyway). Now use "ls" and you'll see a whole bunch of directories all starting with "ctl_". Here is what my system looks like:

londo:~# cd /sys/class/pvrusb2/sn-6829718/
londo:/sys/class/pvrusb2/sn-6829718# ls
bus_info_str                   ctl_video_b_frames
ctl_audio_bitrate              ctl_video_bitrate
ctl_audio_crc                  ctl_video_bitrate_mode
ctl_audio_emphasis             ctl_video_bitrate_peak
ctl_audio_layer                ctl_video_chroma_median_filter_bottom
ctl_audio_mode                 ctl_video_chroma_median_filter_top
ctl_audio_modes_present        ctl_video_chroma_spatial_filter_type
ctl_balance                    ctl_video_gop_closure
ctl_bass                       ctl_video_gop_size
ctl_brightness                 ctl_video_luma_median_filter_bottom
ctl_channel                    ctl_video_luma_median_filter_top
ctl_contrast                   ctl_video_luma_spatial_filter_type
ctl_freq_table_channel         ctl_video_median_filter_type
ctl_freq_table_value           ctl_video_spatial_filter
ctl_frequency                  ctl_video_spatial_filter_mode
ctl_hue                        ctl_video_standard
ctl_input                      ctl_video_standard_mask_active
ctl_master_state               ctl_video_standard_mask_available
ctl_mpeg_audio_mode            ctl_video_temporal_decimation
ctl_mpeg_audio_mode_extension  ctl_video_temporal_filter
ctl_mute                       ctl_video_temporal_filter_mode
ctl_resolution_hor             ctl_volume
ctl_resolution_ver             debugcmd
ctl_saturation                 debuginfo
ctl_signal_present             device
ctl_srate                      power
ctl_streaming_enabled          subsystem
ctl_stream_type                uevent
ctl_treble                     unit_number
ctl_usb_speed                  v4l_minor_number
ctl_video_aspect               v4l_radio_minor_number

(The device and driver links you see there by the way are standard things which point off to other parts of sysfs where the driver's and device's lower level control files can be found. There are also other bits and pieces showing here that help with debugging the driver or learning things about how it is set up.)

Note: As said above, the "XXXXXXX" part of the path is the device's serial number. It is possible that the driver might not be able to retrieve a serial number from the device (if there were problems reading the device's PROM). In this situation, the sysfs implementation here will substitute the device's unit id using the form "unit-X" (instead of "sn-XXXXXXX") where "X" is the letter for the unit assigned to the device instance.

Each ctl_ directory has some subset of these files:

You can read any of these files just by cat'ing it out. All are read-only except for cur_val and custom_val, most of which can be set by just writing the new value into it (a few of those controls are actually completely read-only). The incoming value must be either an integer within the legal range specified by min_val and max_val, a legal enumeration constant (for enumerated controls), a true / false or yes / no literal (for boolean controls), or a bit mask assignment (for bit mask controls) in order for the assignment to "take". Otherwise the program doing the write should get back an EINVAL or ERANGE error status.

Bit mask controls have a somewhat more complex expected format in order to support the setting and clearing of individual bits within the mask. The values you write in are expected to be a set of whitespace-seprated bit names. If just the names are used then the entire mask is set to just those bits. If however each bit name is prefixed with a "+" or a "-", then just those corresponding bits will be set or cleared (respectively) without affecting the other bits in the mask.

The contents of the custom_val file is determined entirely by the specific control itself; there is no defined format unlike with cur_val. This will only appear if the control has a way to format its own value. Currently it is only used to show video standard mask values, where this custom form adheres closer to normal conventions for expressing multiple standards. If the control in question is writable, then this may be writable as well (in which case the control will parse the symbolic value itself to determine the desired underlying internal value). If none of this makes sense to you, then you can just safely ignore the existence of the custom_val file.

I initially put together this interface to make it easier to debug the driver, independent of an application like xawtv (in fact, see dbgifc.html for further info on debug aspects of this interface). But the possibilities here are obvious. For example, it is possible open the /dev/ entry into mplayer and then completely control everything else with this sysfs interface while mplayer is running. (I routinely test the driver this way.) One could write a shell script control program with this interface...

Please be aware that with this interface one has complete run of all the driver's controls. There are certainly combinations of settings which, uh, won't work very well. But as I said, I had initially put this here to make it easier to debug the driver. It was either this or invent a pile of new ioctl()'s and write a test program to operate those settings (the ioctl() approach is what ivtv does).

In the driver source tree, there is a file doc/controls.txt which annotates each of the controls with information about what it is expected to do, what effects may or may not happen, and whether certain settings work or not. I put this together after experimentation with the device. Others may find it handy so I've made the results available.

IR handling

The IR receiver within the model 29xxx series devices is an I2C part that is already understood by the lircd software package (0.7 or later). A long long time ago Aurelien's driver hardcoded something here which made the IR receiver into another source for /dev/input, but I had stability problems with this and just decided to rip it out in favor of letting more stable external software handle this function.

The IR receiver within the early model 24xxx series devices is some glue logic and firmware within the FX2 microcontroller that is operating the device. There's no actual I2C interface and thus no way for any external chip-level driver to reach into the pvrusb2 driver and operate the part. The pvrusb2 driver handles this situation by operating this feature itself and presenting the results as an emulation of the I2C chip that would otherwise be present in 29xxx devices. Thus, even though those early 24xxx devices don't actually have the expected chip, everything still works properly and outside logic (e.g. lirc) still thinks it is talking to a normal Hauppauge I2C-based IR receiver.

Later 24xxx models (the "MCE" version) included an IR blaster, and with that change the IR landscape there changes again. In that case the IR receiver is an I2C device again but its interface is alien to what had been used in the 29xxx models. The pvrusb2 driver makes no attempt to emulate anything here and just stays out of the way. However lirc should still be able to work with this device (just a different low level driver is inserted, try the one used for the "PVR-150").

The HVR-1950 / HVR-1900 models contain an IR receiver / blaster that I believe resembles that from the later 24xxx models and in theory should also work with lirc in the same manner. However I have not heard any reports of success there yet (if somebody gets this to work, tell me)...

It appears that onair hardware has an IR receiver, but I do not know if it is usable.

Generally, making IR reception work is mostly just a case of install lircd and go (see important note at the end of this section about ir-kbd-i2c). It's the same thing you would do to get IR working in ivtv. In other words, grab lirc, build it, modprobe the appropriate driver into the kernel and when configured with the correct lircd.conf (one appropriate for the PVR USB2's included remote is provided with the standalone pvrusb2 driver), it will "just work". The I2C driver will discover the internal I2C bus made available by the pvrusb2 driver, probe that bus, and attach itself when it finds the IR receiver chip it will be looking for. For later devices (e.g. HVR-1950) you will likely need a much more recent version of lirc.

Note that if you are a Debian user, there is an lirc-modules-source package which you can in theory just install and build against your kernel tree. I and others have found that package to be broken. It won't compile cleanly. (See here for the current situation with this package.) You're probably better off just using the vanilla version from the lirc web site.

There is a second but limited way to make IR work with the pvrusb2 driver, if you dislike lirc and would prefer something which works with a /dev/input style interface. Included as part of the V4L core is the module ir-kbd-i2c.ko. If you insert that module into your kernel, then it will drive the I2C chip and present the results via /dev/input. This is true for kernels up to 2.6.29. Note: This only works for 29xxx and earlier non-MCE 24xxx devices; for other devices the IR hardware is too different to be handled by ir-kbd-i2c.

For kernels 2.6.30 or later things are messier at the moment. The I2C internal infrastructure changes such that now the pvrusb2 driver must explicitly issue a call that binds clients like ir-kbd-i2c into its I2C bus. Thus, just modprobe'ing ir-kbd-i2c won't work without help. In fact, it's entirely likely that lirc won't work either until / unless some changes are made there. Right now I'm not very clear on this. However to support ir-kbd-i2c, the pvrusb2 will try to autoload it where appropriate, regardless of kernel version. This means that if you are using lirc, then there may be some interference from ir-kbd-i2c. When I say "appropriate" what I mean is that the attempt will only be made if the device in question has an IR receiver that is known specifically to work with ir-kbd-i2c (e.g. currently only 29xxx and early 24xxx models). In an attempt to still allow lirc to work (if it will work at all), there's a module option available. Specifiy "disable_autoload_ir_video=1" and the pvrusb2 driver's autoloading of ir-kbd-i2c will be suppressed.

Radio Mode

As of the 20061227 snapshot, the pvrusb2 driver supports operation of the FM tuner where possible in the hardware. Many thanks go to Pantelis Koukousoulas for implementing the key pieces. So far I've only tested this with mplayer and kradio, but a lot should be possible. To use the PVR USB2 as an FM radio, you really only need to do two things:

  1. Change the input selection to "radio".
  2. Set the desired frequency to be tuned.

That is trivially done through sysfs, but it can also be easily done through the normal V4L api as well. Once in radio mode, just stream data as you normally would. The result is still an mpeg stream; video will be blank and the audio will be the radio station you have tuned. Other things to be aware of:

Getting a full mpeg stream with (blanked) video embedded is kind of wasteful. Usually you really only want the more familiar mp3 audio stream packaged within that full mpeg stream. The driver doesn't (currently) do anything to process the mpeg stream; it only passes on what it gets from the hardware and right now all that we can do in the hardware is spit out mpeg. But there's no reason why you can post-process the data in a user process. You can use the app mpeg2desc to filter for the audio stream. For example:

cat /dev/video0 | mpeg2desc -a0 >/tmp/audio_data.mp3

To get regular old pcm, go one step further, with the help of mpg123:

cat /dev/video0 | mpeg2desc -a0 | mpg123 >/tmp/audio_data.wav

The mpeg2desc program can be usually found as a tool within the dvdauthor package, and mpg123 (or mpg321) is usually available in various distros. Credit again to Pantelis Koukousoulas for suggesting this.

A somewhat less clever variation of the above is also possible with a single invocation mplayer:

mplayer -vo null -ao pcm:file=/tmp/audio_data.wav /dev/video0

That last trick is actually useful for getting digital audio out of just about any stream format - if mplayer has a codec for it, then you extract out the digital audio from it.

Frequency Table

There is a frequency table implemented inside this driver. It is not available for v4l, but it can be used with the sysfs control interface. You must program it first before using it, but once programmed it becomes possible to change the channel just by, well, writing the new channel number to the driver. The table size is currently limited to channel numbers 1 through 500 (far in excess of anything anyone should need), and the channel ids must be integers not something cute like station call letters.

Note: You do not need to program this frequency table or otherwise even touch it when using this driver with any v4l application. This table is not even visible in the v4l API; it is only present here to make it easier to debug the driver using sysfs.

The frequency table must be programmed a slot at a time. You do this by first selecting the slot's id (a.k.a. the channel number) into the freq_table_channel variable through sysfs. Once selected, you can read / write the frequency (in Hz) for that slot using the freq_table_value variable through sysfs. Repeat this process for all channels to be programmed. Yes, this is just begging for a shell script to do the dirty work. Thanks to Per Christian Henden, one example of such a script exists now in the utils subdirectory (see utils.html for more information about this).

Once you've programmed the desired slots in the table, just "change the channel" by writing the desired channel number to the channel variable through sysfs. That's it.

The frequency can still be set as before by writing the actual frequency to the frequency variable. If that is done, then the channel will be implicitly set to zero, which means "none". Thus the channel and frequency variables at all times stay consistent with each other and there's no loss of flexibility or any implied confusion.

The frequency variable can of course be read back at any time to see what the actual frequency is, regardless of whether it was set directly or implied by a channel setting. And of course the channel variable can be read back at any time to find out what the current channel is or if it is not being used due to the frequency being directly set (in which case the value read back will be zero).

Why do this? Well it was dirt-cheap easy to implement, and it does help with debugging, though in a minor way. Besides it's cool to do. OK, OK. Enough playing and back to the real rework...

Playing well with others

The following is a summary of issues / tips when using this driver alongside other software or in less-typical environments.

Playing well with ivtv

Even though the PVR USB2 hardware is a USB device while everything else driven by ivtv is a PCI device, there really is more than a passing resemblance among them. As such it's no coincidence that both happen to share the same chip-level drivers. This is in fact where the chip-level drivers in the ivtv subdirectory of the standalone driver snapshot came from. Even the same cx23416 mpeg2 encoder - which is the heart of ivtv - is also used in the PVR USB2 device. If you have / need to also use ivtv, it should be possible for this driver to coexist with it. Any ivtv-provided chip-level drivers should also work fine with the PVR USB2 driver, thus the two drivers should be able to coexist nicely on the same system.

Playing well with xbox

The X-box has an internal I2C bus, and the code that was hacked together for it makes the assumption that it is the only I2C bus that can possibly exist on an xbox. That assumption becomes false when a PVR USB2 device is introduced, unfortunately. The problem here is that the I2C driver code for the xbox tries to attach to the PVR USB2's I2C bus, causing dangling pointers in the xbox driver code and chaos ensues. If you have an xbox, I have a patch for the xbox I2C driver code that makes it play nicer (it's still a horrible hack though). Contact me for the patch.

Playing well in v4l

The v4l system in Linux is undergoing rapid development. This can cause issues for an out-of-tree driver like the pvrusb2 driver. The standalone version of the pvrusb2 driver goes to some length to detect and interoperate correctly with whatever surrounding v4l environment it finds itself operating inside of, however it can be hard to keep up. The in-V4L version of the pvrusb2 driver is less complex in this area since it can always assume exactly what v4l environment in which it is running. If you find you are having problems with the pvrusb2 standalone driver and you suspect v4l incompatibilities as the cause, then contact me or check the mailing list for chatter about such a problem. And of course you can elect to simply update to the latest v4l repository snapshot, with its included in-V4L version of the pvrusb2 driver.

V4L vs DVB interactions

Hybrid devices are handled in the pvrusb2 driver with both V4L and DVB interfaces. Internally it's all one driver under unified control, but externally the two interfaces make it look like two drivers. So what interactions can happen between the interfaces?

Digital tuning in the pvrusb2 driver is implemented as logically another input choice. Thus if you use sysfs to enumerate the choices for ctl_input you'll also see a "dtv" choice for the digital tuner.

In theory the V4L side can simply select the "dtv" input and stream digital TV. However the current architecture of the V4L/DVB subsystem makes this impossible, due to the fact that digital tuning is tightly entangled with the DVB subsystem. The only way to perform digital tuning at the moment is through DVB, simple as that. There are some ideas to solve this, but it's still a work in progress.

The DVB interface currently has no ability to select an input choice. This causes an issue in the pvrusb2 driver since the "dtv" input choice must be selected in order to perform digital streaming.

The above two issues led to implementation of a special feature in the pvrusb2 driver, both to prevent inoperable hardware configurations from being run and to keep V4L and DVB from stepping on each other. The feature is known as "narrowing". It works like this: When a given interface is opened, the list of legal input selections in the driver is automatically narrowed to that which is usable for the open interface. Thus when a V4L app opens the V4L interface, the "dtv" choice is dropped from the list of inputs - and when a DVB app opens the DVB interface, every choice except the "dtv" choice is dropped from the list of inputs.

If the current input selection is no longer valid after the narrowing step, the driver immediately switches to one of the remaining choices.

The effect of the narrowing operation is canceled when the interface that caused the narrowing is closed.

If the set of remaining valid input choices becomes empty, then it is a disallowed narrowing operation and the interface which caused it will get back an error. This prevents simultaneous opening of the V4L and DVB interfaces - the second one to open will be denied with an error because the other interface has already narrowed-away the desired input choice(s).

Along a similar line of reasoning, the V4L radio device behaves in a similar manner. If the radio device is opened, then the set of input choices is narrowed to be only the radio - therefore the radio become active when the V4L radio interface is opened.

You can observe this behavior through the sysfs interface - dump the enumerated list of input selections under various conditions and note how the list changes depending on what interface is open.

All of the above is long-winded way of saying the the pvrusb2 driver currently enforces mutual exclusion between the V4L and DVB interfaces - when one is open, the other will be denied. Any app wanting to use both interfaces (e.g. MythTV) must be aware of this.