README

   1 * fmtools: simple Video for Linux radio card programs
   2 *
   3 * Russell Kroll <rkroll@exploits.org>
   4 *
   5 * Program support page: http://www.exploits.org/v4l/fmtools.html
   6 *
   7 * Released under the GNU GPL - See COPYING for details.
   8
   9 Package information
  10 ===================
  11
  12 This is a pair of hopefully useful control programs for Video for Linux
  13 (v4l) radio card drivers.  The focus is on control, so you may find these
  14 programs a bit unfriendly.  Users are encouraged to investigate the source
  15 and create wrappers or new programs based on this design.
  16
  17  fm      - a simple tuner
  18  fmscan  - a simple band scanner
  19
  20 fm
  21 ==
  22
  23 This is a small controller that will send commands to your v4l radio
  24 cards.  It was written mostly so I could have something to send commands
  25 at the drivers being created or debugged here.
  26
  27 I'll discuss the options a little, but it should be fairly simple to run.
  28
  29 The usual mode of operation is to tell the radio to come on to a given
  30 freqency.  In these examples, 94.3 will be used since that's a station
  31 that happens to get tuned here frequently.
  32
  33 To turn the radio on to that frequency at the default volume, you'd do
  34 "fm 94.3" and call it done.  If you wanted to crank it up to full volume,
  35 another argument would be needed and the command becomes "fm 94.3 65535".
  36 Volumes range from 0 (off) to 65535 (full intensity).  This is a direct
  37 link to the value used in the v4l API by the actual drivers.
  38
  39 There is a -q option that will suppress messages about tuning, volume
  40 changes, and so forth.  Keeping your tuner quiet may not seem like such
  41 a useful thing at first, but it can be very handy inside an IRC script.
  42 Having a program scribble on your channel window when you do /KILO
  43 or similar is not enjoyable.
  44
  45 Besides direct tuning, there are also "on" and "off" commands.  They will
  46 turn the card on and off (mute) as you may have guessed.
  47
  48 Finally, there is volume control.  To go up a notch, use +.  To go down
  49 a notch, use -.  Simple.
  50
  51 fm configuration
  52 ----------------
  53
  54 You can create a file called .fmrc in your home directory that contains
  55 values for the default volume and default volume stepping.  This way,
  56 you can have your radio card always come on at a certain volume when you
  57 don't explicitly list it on the command line.  The volume stepping
  58 controls how much the volume changes during a - or + operation.
  59
  60 This file is not required for operation of the program, and it will not
  61 even give so much as a peep if it doesn't find it.  The defaults are
  62 used when you don't specify values.  The values are 12.5% for default
  63 volume and 10% for default volume stepping.
  64
  65 Here's what a real .fmrc might look like ...
  66
  67 VOL 32000
  68 INCR 6554
  69
  70 Here we say the default volume is 32000 - just shy of 50%.  Then we
  71 say the increment value for volume changes with + and - is 6554 -
  72 approximately 10%.  These values were obtained by playing around with
  73 the numbers until things behaved the way I wanted.   Be aware that some
  74 cards only have a couple of volume steps, so you may not notice a change
  75 right away.
  76
  77 The Cadet hardware, for example, has two settings: off and *VERY LOUD*.
  78 Any volume setting will turn it on.  The Aztech card has 4 settings (off,
  79 low, medium, high) and you'll notice it change when you cross the
  80 boundaries.  The Aimslab RadioReveal card is actually based on analog
  81 volume control, with 10 steps emulated within that range.
  82
  83 There are some other options available:
  84
  85 -d - select device.  If you have more than one v4l radio card in your
  86      system for some reason, use -d <device> to select the right one.
  87      This is probably only useful if you like writing drivers for these
  88      things.
  89
  90 -o - override card frequency range - Some radio card drivers don't
  91      actively enforce the frequencies that you can tune to.  Use this
  92      switch and fm will send any frequency you want to the driver.  This
  93      alone will not make an unmodified card receive frequencies from
  94      outside the design range.  You have to change the tuner hardware in
  95      order to enjoy such broadcasts.
  96
  97 -t - select tuner - Certain cards have multiple tuners - usually used for
  98      different bands.  The ADS Cadet driver is known to support this,
  99      specifically using 0 for FM and 1 for AM.  To tune AM frequencies,
 100      remember that fm expects MHz style input, and do the following:
 101
 102      For 1200 kHz, enter 'fm -t 1 1.2', since 1.2 MHz == 1200 kHz.
 103
 104      Yes, tuning am frequencies with 'fm' seems backwards, but that's
 105      life.  Crafty hackers may want to add some code to make the program
 106      check argv[0] and behave differently.
 107
 108 fmscan
 109 ======
 110
 111 This simple little program will command your radio card through the radio
 112 band and show which ones have a accumulated signal strength of 50% or
 113 higher.  This process can take awhile, and can vary greatly depending on
 114 the radio card in use.
 115
 116 By default, the range scanned is 87.9-107.9 MHz in .2 MHz steps, since
 117 that's the standard band here in the USA.  Users in other regions should
 118 set the appropriate information for best results.
 119
 120 This program may not do much if your radio card's driver doesn't support
 121 fine tuning in 1/16000 MHz offsets.  By default, v4l assumes 1/16 MHz
 122 tuning units, which introduces evil rounding errors on many frequencies.
 123 If in doubt, grep for VIDEO_TUNER_LOW in your driver's source.
 124
 125 v4l /dev entries
 126 ================
 127
 128 By default, these programs use /dev/radio0 to access the hardware.  This
 129 can be changed with -d <device> if you have more than one.   If you have
 130 been using v4l radio cards for awhile, you may already have a /dev/radio.
 131 That is now "legacy", and should be symlinked to /dev/radio0.  To create
 132 the proper device entry, either do "make devices" as root, or create it
 133 by hand with mknod (c 81 64).
 134
 135 The proper device listing looks something like this in 'ls -la' ...
 136
 137 lrwxrwxrwx   1 root     root           11 Jan 20 03:19 /dev/radio -> /dev/radio0
 138 crw-r--r--   1 root     root      81,  64 Jan 20 03:19 /dev/radio0
 139
 140 Other cards follow the same pattern - radio1 would be (81, 65), and so on.
 141
 142 The owner and permission data should be set to values that agree with
 143 your system's personality.  If it's mostly a solitary system with few or
 144 no users, the above settings will be fine.
 145
 146 However, if you have other people running around on your system,  consider
 147 making the device part of a "radio" group or maybe even "console" if you
 148 use such a thing.  That will keep random individuals from doing odd things
 149 to your radio like changing it to a classical station while you're
 150 listening to some death metal (or vice versa).  You have been warned.
 151
 152 Old interim Linux 2.1 /dev/radio interface
 153 ==========================================
 154
 155 Around 2.1.60, there was another /dev/radio specification that controlled
 156 two boards - namely the AIMSLab RadioTrack and later the Aztech/Packard
 157 Bell radio card.  This didn't last very long, as the entire radio card
 158 driver tree was eventually redone under the expanded Video for Linux API.
 159
 160 These programs are not compatible with that interface.  Very few things
 161 are.  If you are still using it, you should throw it away and upgrade to
 162 the v4l drivers.  There have been many improvements since then, and you
 163 will be able to use the fmtools programs on your card.