README

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