User Documentation

Last Updated: September 25, 2003


PVRBOT reads TV guide data, finds shows matching titles you specify, shedules show recording events and programs a personal video recorder (PVR) or VCR with timer events to record the shows.

PVRBOT uses a computer controlled infrared remote control unit to program timer events on your PVR or VCR.  This means you do not have to make any modifications to your PVR or VCR.

Just tell PVRBOT which shows you want to record and it will do the rest.


1)  a computer that can run Java programs and that has an available serial port.

2)      a supported PVR

3)      a supported computer controlled infrared remote device

4)      TV service that has program listings on a supported Web guide source.

Supported Hardware and TV Guide Sources

PVRBOT is designed so that people with NO programming experience can use it to control supported hardware and services.  People with modest Java programming experience will be able to add support for new PVRs, tv guide sources, and infrared devices. Hopefully PVR owners in the Open Source community will rise to the challenge and add support for as many devices as possible.

For instructions on how to add support for new hardware, please see the developer’s documentation.  However, if you wish to simply download PVRBOT and run it, the currently supported devices are:

Supported Computers & OSs

I have personally run PVRBOT on Windows 98 and RedHat Linux 9.0. However, the following OSs should also work.

Supported Personal Video Recorders (PVR)

Supported Infrared Devices

Supported Web TV Guide Sources


You can experiment with PVRBOT even if you do not have a computer controlled infrared device.  PVRBOT will parse TV listings, construct schedules, and send commands to the serial port. You can check the schedule logs to see how PVRBOT is doing.


Sorry, to support multiple platforms and OSs it is difficult to bundle the software as an installation drop. If anybody feels inclined to package the lastest stable releases into installable drops I would really appreciate it.

1)      Download and install a Java Runtime Environment (JRE).  Sun provides JREs free of charge for many hardware configurations at http://java.sun.com/j2se/1.4.2/download.html. The JRE will be sufficient unless you want to develop Java applications of your own.

2)      Download and install a Java communications library to provide access to your serial ports.  Sun provides libraries for Windows and Solaris x/86 at http://java.sun.com/products/javacomm.  Be sure to follow the installation instructions in the download.  They describe where the comm.jar and the *.properties files have to go.  If you don’t put them in the right place Java will not be able to detect the serial ports.  Instructions for getting Linux serial ports working with Java can be found in this excellent HOW-TO: (thanks to the author). One hint for the Linux folks. This HOWTO worked perfectly for me except Linux insisted on calling my COM1 port /dev/ttyS2 (instead of the expected /dev/ttyS0). On Linux you may want to use the dmesg command to see what Linux has really mapped your COM ports as.

3) Download and install xmltv from http://sourceforge.net/project/showfiles.php?group_id=39046. Follow the installation and configuration instructions provided by the cool folks at xmltv. Windows users are lucky, there are binary downloads available. Unix users will have to make it from the PERL source.

4)      Download the latest PVRBOT binary distribution from http://sourceforge.net/project/showfiles.php?group_id=67473 and unzip it to its own directory.


The configuration files are found in the pvrbot\config directory and in the directory where you installed xmltv.

1) First you must configure an xmltv grabber to download the listings for your area from the web and write them to a *.xml file. It is VERY important that you configure xmltv to skip the channels you do not receive. Failure to do this may prevent PVRBOT from successfully programming your PVR. Also you should make sure that you invoke xmltv with a --days options that is set to a reasonable number to get enough days of data at once. I recommend --days 10. Instructions on configuring and running xmltv can be found in their documentation.

2) Configure your Windows Scheduler or Unix crontab to run xmltv periodically. XMLTV should run one or two days more often than the --days command to make sure you don't run out of tv guide data. So if you run xmltv --days 10 you should configure the scheduler to run xmltv every 8 or 9 days. You should configure your Windows scheduler or crontab to run xmltv on a regular basis. My xmltv grabber command line looks like:

tv_grab_na --output ~/pvrbot/data/listings.xml --days 8

2)      Edit pvrbot.properties.  Comments in this file will explain what each value does and what the defaults are.  The most important values are:

a. xmltv listings file name. (Important. the xmltv.dtd file included with the XMLTV distribution must reside in the same directory you write your xmltv listings into)

b.      controllerClass

c.       pvrClass

d. daysToRead (This must be set to the same number, or 1 less, than what you used for your xmltv --days parameter). Yes this is dumb and is a relic from the bad old days when I did my own HTML parsing. It will likely be removed some day ... but until then it is important that it is set properly.

2)      Edit 1623PC.properties.  Comments in this file will explain what each value does and what the defaults are.  The most important values are:

a.       portName

b.      usePowerSensor

4)      Edit titles.txt.  This file tells PVRBOT which titles you are interested in recording.  Comments in the file describe the format of the file.

Running PVRBOT

1) Set you your Windows scheduler or Unix crontab to run your xmltv grabber on a regular basis. Every 7 days for instance.

2) Run pvrbot.bat.  PVRBOT will read data from the web and schedule the shows you want to watch.  You should just leave PVRBOT running all the time.  It will get new guide data when it needs to and program new events to your PVR as required. I have had success running PVRBOT from a Windows autoexec.bat file and a Linux etc/rc.local file. Important Note: PVRBOT will want to see a xmltv listings file when it starts, so wait for the first run of xmltv to occur before you run PVRBOT.

2)      By default PVRBOT only attempts to program timer events to your hardware PVR at 4:00 am.  To force PVRBOT to program your PVR immediately run pvrforce.bat.  PVRBOT will begin programming your PVR within 30 seconds.  PVRBOT itself must be running before pvrforce.bat will do anything.

3)      Editing titles.txt will cause PVRBOT to automatically reschedule events.  However, PVR programming will only occur at 4:00 am unless you run pvrforce.bat as well.

4)      PVRBOT will reprocess files automatically if dependant files change. For example, if the xmltv listing file is replaced by a newer version, PVRBOT will automatically do a title search and reschedule shows.

5)      Deleting pvrbot\data\schedule.dat will cause PVRBOT to reschedule shows.  Typically this is not required since PVRBOT will reschedule shows each time titles.txt is changed or new guide data is read from the Internet.

Stopping PVRBOT

Whenever PVRBOT starts it creates a file data\pvrbot.lock.  Delete this file and PVRBOT will exit within 30 seconds.

Adding Support for new Hardware to PVRBOT

PVRBOT is an open source project and is designed to allow easy expansion with support for new PVRs, IR Controllers and guide data sources.

To do this you will need to be moderately proficient at Java programming.

For further information please see the Programmer’s Guide.

Reporting Problems

Links to user and developer forums and mailing lists can be found on the PVRBOT home page at: http://pvrbot.sourceforge.net


I originally wrote PVRBOT for myself and I do use it all the time. However, I hope other people can get as much use out of it as I do. If you do use it please drop me an email, I would love to hear from you. I would also like suggestions on how to make the installation and running process more straightfoward. Especially for novice computer users.