
astuner 3.1 - The AfterStep Radio Tuner.
By David Muench
cc@spork.neonexus.com
http://www.neonexus.com/cc/

Extensively modified by Keith Dart <kdart@techie.com>
<http://www.employees.org/~kdart/>

This program uses code from Rob Malda's ascd, and as of 3.0 it also uses
Matthew Kirkwood's Linux kernel radio support. Thanks to both of you.
This means that it only works with Linux kernels 2.1 and above. Hopefully,
the timing will be right and the new AfterStep will be released about the
same time as the kernel 2.2. Then most users can use this applet. 

WHAT IT IS:

This program will control your AIMS RadioTrack or Reveal RadioReveal
FM radio cards. I personally have an AIMS, but the two seem to be identical
with the exception that the AIMS is still made, and Reveal has gone belly
up. If you want one of these cards, Walmart might still have a Reveal one
laying around on the top shelf if you dig, but the company is out of
business. You may not care though since they are $25 or less this way.
If you want an AIMS lab one, their web site is at www.aimslab.com, and you
can purchase them through Tiger Direct (1-800-888-4437). I paid $39.99 for
mine via Tiger, and got a free coaster with it (Prodigy Internet CDROM).
The cards don't require a sound card and have their own small amps on board. 

I've also added a "fake IPC" now. [changed that to a real IPC using FIFOs.
-kwd] Other programs can now tell astuner to do things. This is useful for a
lot of things. The example program that comes with it, cmdtuner, can be used
to control the radio from the command line. I use it from my DEC vt220 I have
connected to my machine to control the radio from there. But the real reason
it's there is... I recently got a remote control for my box (from
www.onsale.com), and the daemon for that that I am writing will be able to
control astuner now. The idea will be to have all the little afterstep applets
have an IPC like this. So the remote control (or anything, something like
cmdtuner maybe) can control ascd and so on.  Another great usefulness would be
an alarm clock. You can now turn on and off your radio via a crontab and
cmdtuner. Pretty neat.

A neat project for someone might be to write a small app that launches when
asclock is clicked on that will add and delete alarms from your crontab.
Ideally you could have it turn on the radio, or start up ascd, perhaps with
a random cd and track using ascdc and a cd changer.. Lots of possibilities.

HOW TO MAKE IT GO:

This program was written under Linux. As of astuner 3.0, it will only work
under Linux. Some people may not like that, but I took an informal survey of
people who use astuner on the afterstep mailing list and they all ran Linux.
If you want to use it on another os, just get astuner 2.0. You'll also need
libXpm and flex (libfl), along with libX11 and so on..

Note to those upgrading: There may be configuration file
changes/additions/deletions. Always check the version history at the bottom
of this file and the sample ~/GNUstep/Library/AfterStep/astuner for changes you
may need to make to your config file.

Also, you need to make a /dev/radio device. Type this to make it:

mknod /dev/radio c 10 152

Note, you must be root to do that. You also must make sure your user has
write access to it:

chmod +rw /dev/radio

Run:
xmkmf
make
make install

The make install step usually has to be done as root.

Copy astunerrc into your home AfterStep directory as
~/GNUstep/Library/AfterStep/astuner if you don't already have one, and edit it
according to the comments in there.

Then stick it in your Wharf section of your ~/GNUstep/Library/AfterStep/wharf :

*Wharf - - Swallow "astuner" astuner &

That's about it. The controls are easy, left-right buttons are station,
the little up/down buttons are volume, the red button is to turn the radio
on and off, and the P button cycles through your presets. Left clicking on
it jumps to the next preset, right clicking jumps back one, and middle
clicking sends you to the start of the preset list. Also, the color
of the station LED's will change depending on how strong the signal is. If
it's well tuned, they will be bright green, otherwise they will be cyan.

cmdtuner is equally easy to use, if you want the help screen just type
cmdtuner with no arguments.

David Muench
cc@spork.neonexus.com
http://www.neonexus.com/cc/

See the file COPYING for the GPL info..

BUGS:

  - Does not properly clean up its FIFO file when closed by the window
	manager.

  - After turning the radio on, there is no way to turn it all the way off.
	This is not really an astuner bug, it's a limitation of the device
	driver.

  - Mail me if you find more.

FUTURE PLANS/POSSIBILITIES:

  * Little red indicator that flashes when you push a button <mitch@palmtop.net>
  * Right click on the tuning buttons for fine tuning <mitch@palmtop.net>
  * Major code cleanup <me!>
  * If you have other ideas, email me them. Remember, we are constrained to
    working inside a 48x48 icon here..

REVISION HISTORY:

version 0.1
Original Release (yay it works!)

version 1.0
Added a config file (/etc/astunerrc)
New graphics (complete with a power LED) from Robert Forbes <bokeyf@gte.net>
Fixed a bug (eek!) where if the radio was off and you hit a tuning button,
  the radio would turn on correctly, but you'd have to hit the power button
  twice to get any response to turn it off again.
Added presets! Just define them (up to 20) in the config file.
Added tuning signal indicator

version 1.1
Argh, forgot to remove a line of debugging code that would spew stuff over
  the console. No big deal, but might as well fix it..

version 2.0
Added a fake ipc (InterProcess Communication) system.
Added a new program, cmdtuner, a command line program to tell astuner what
  to do via the new fake ipc.
Now you can right click on the presets button to back up a station, or
  middle click to go to the start of the list. Thanks to Roman Mitz
  <rmitz@milliways.res.cmu.edu> for this nice patch.

version 3.0
Updated that pesky version number from 0.1.. Whoops. :)
astuner now uses the Linux kernel driver for access to the radio card, which
  means it's no longer setuid root.
Fixed tiny typos in the README.
Removed the port command in the config file since the kernel takes care of
  that now and added the device command to tell where your /dev/radio is.
Added station callsigns. It now uses that info from the config file, and if
  you are on a preset station it will switch back and forth from the station
  number to the callsign every 4 seconds. Suggested by bokeyf@gte.net.

version 3.1
Maintenance assumed by Keith Dart <kdart@techie.com>
Rewrote most of the tuner control section to make it more modular.
Updates for the latest (2.1.x) /dev/radio device driver IOCTLs. 
Changed astuner/cmdtuner IPC to use named pipes.
Fixed station display bug (errors in XPM file).
The rc file is now in users home directory. Can now enter frequencies
directly in MHz. Internally, they are stored as fixed point integers to avoid
rounding errors. In fact, they are never treated as floats.

