About the widget

The Azureus Dashboard Widget provides a compact, friendly interface for monitoring and managing BitTorrent downloads. It's especially useful for remote torrent management — for instance, if you use a machine other than your main workstation for BitTorrent downloads — but works just as well for controlling Azureus on your local machine.

For users of Mac OS X 10.4, the Azureus Dashboard Widget is a pleasant alternative to the Swing Web Interface, TorrentFlux, VNC, or ssh + screen + btdownloadcurses.py. Multiple instances of the widget are allowed, so if you need to you can control more than one machine at once.

Technical Crap

For any who are dorky enough to want to know how it works: the XML/HTTP plugin provides a web-service-like mechanism for executing many of the same methods that are available to all Azureus plugins. It listens on a port you specify; POST an XML string to that port containing the method you want to invoke, and you'll get an XML file back that describes the results.

The Azureus Dashboard Widget uses Ajax (the JavaScript XMLHttpRequest object) to communicate with Azureus in this manner. All the remote requests are asynchronous, so the widget doesn't hang while it's waiting for data.

Requirements

• Mac OS X 10.4 (Tiger). The widget is reported to work under 10.3.9 using Amnesty Widget Browser, but I can't verify this personally. The widget will not work on Windows XP.
• Azureus (duh) running on any platform. Azureus must be running — the widget is not a BT client, just a frontend, so Azureus still has to do all the work.
• The XML over HTTP plugin for Azureus. This plugin can be installed through Azureus (see directions below).

The widget will talk to an Azureus installation on any platform — Windows, OS X, Linux, etc. But the widget itself will not work on Windows XP.

Setting up the widget

For the purposes of these instructions, the phrase "Azureus box" refers to the machine running Azureus. If this machine is also the machine running the widget, then pay attention to all the stuff about the "local machine."

1. Install the XML/HTTP Plugin.

   The plugin can be installed through Azureus (Plugins > Installation Wizard...) or from the Azureus web site.

2. Configure the XML/HTTP Plugin.

   Go to Plugins > XML/HTTP Interface section of Azureus preferences. (You can get there through Tools > Options or Azureus > Preferences, depending on your platform.)

   The following items must or can be changed:

   • Port: The default is 6884, which will likely suffice. If you need to, you can set this to whatever you wish, as long as it's not a port that Azureus is already using. This is the port you'll enter on the back of the widget. If you're not running Azureus locally, make sure this port isn't blocked by firewall on the Azureus box. If the Azureus box is outside your LAN and behind a router, you might also need to forward this port on your router.
   • Access: "All" is the default. You might want to make this more restrictive. If Azureus will be running on the local machine, then you may change this to "local." You can also specify an IP address (or a range of IP addresses).
   • Enable password: You may enter a username and password to restrict access. You'll need to enter them on the back of the widget as well.

   The following items currently cannot be changed:

   • Protocol: Must be set to "http." It's likely a future version of the widget will support "https."
   • Mode: Must be set to "full." In theory, some of the widget's functions would work in "view" mode, but this has not been tested.

   Next, go to the Files section of preferences. Check Save to default data directory and specify a directory. Next, go to Files > Torrents. Make sure Save .torrent files is checked and that a directory is specified. You can pick any directory you like.

   Once you've saved these options, it's a very good idea to restart Azureus. Some preferences require a restart to take effect.

3. Configure the widget.

   

   If you download the widget with Safari, it'll already be unzipped and installed. If not, then unzip the file and move Azureus.wdgt to /Users/[you]/Library/Widgets. (If you're running 10.4.2, just double-click Azureus.wdgt and you're done.)

   Whe the widget first runs, it will flip over automatically so that you can tell it where to look for your Azureus box.

   • Enter your hostname and port in the top bar. The hostname is the IP address of your Azureus box. If Azureus is running on the local machine, it'll be 127.0.0.1; if it's within the same LAN, it'll likely look like 192.168.X.X or 10.0.X.X. The port is whatever you specified in the XML/HTTP preferences.
   • Enter an update interval in seconds. This value tells the widget how often it should ask for updated data. If your Azureus box is local or on the same LAN, then this value can be very low. If not, then it should be a bit higher. If you're getting timeout errors, increase this value.
   • If you've specified a username and password in the XML/HTTP preferences, check the "Use login" box and enter them here.

   When you're ready, click Done. If you've done everything right, you'll see your active torrents.

Using the widget

1. The frog. Drag new torrents from the finder and drop them on the frog to add them.
2. The main view. Click on a torrent to select it, or use the arrow keys to cycle through torrents. The highlighted torrent's details are displayed below. To scroll through torrents you can use the scrollbar, the arrow keys, or your mouse's scroll wheel (or two-finger trackpad scrolling).
3. The details view. Shows stats and controls for the highlighted torrent: Name, status (time remaining, if applicable), connected/total seeds, connected/total peers, share ratio, upload and download speeds, and all relevant controls.
4. The status bar. Shows total upload and download speeds. Clicking the arrow on the left will refresh the data. When the widget is requesting data from the server, this arrow is replaced with a spinner.

Troubleshooting/Bug Reports/Feature Requests

My widget is not bug-free and does not handle errors as well as I'd like. But before contacting me about widget problems, please try the following things:

1. Make sure you're running a recent version of Azureus. It doesn't have to be the bleeding-edge version, and I'm not sure exactly which version you need, but updating has solved problems for some.
2. If your widget can't connect to Azureus at all, do this: first, temporarily disable "Enter password" (if you have it checked) in your preferences. Next, open up a web browser and type in http://[your IP]:[your port]/process.cgi (so, for example, http://192.168.1.101:6884/process.cgi). If you get a response like "Invalid XML Plugin request received," then the plugin is working, which means the problem is likely in the widget. If you don't get a response at all, then the problem is with Azureus or your network.

If the widget is the problem, then feel free to contact me. If not, you'd probably find the Azureus community more helpful. I'll do my best to help you out, but I don't guarantee I'll respond.

You can reach me at azureus@andrewdupont.net. If you're sending a bug report, please give me as much information as possible, including: whether you're using the widget locally, over LAN, or over WAN; which version (10.4.x) of OS X you're running; and, if possible, any steps I can take to recreate the behavior.

Credits

All the code was written by me, Andrew Dupont — except for the libraries Scroller.js, Animate.js, and AppleLibrary.js, whose authors and licenses are contained in their respective files.

The interface was a collaboration between myself and David Bushell.

Thanks

I am especially grateful to David Bushell, also known as Slizer, for his interface mock-up, which he allowed me to use however I wish. This widget was uglier before he came along. David's ImageShack widget is very cool and worth trying.

Thanks also to goons with Macs for their feedback, encouragement, and bug reports.