Provided by: icom_20040912-1.1_amd64 bug

NAME

       icom - remote control for ICOM transceivers and receivers

SYNOPSIS

       icom  [  -r  radio ] [ -c channel ] [ -m mode ] [-o offset ] [ -g frequency ] [ -f file] [
       -adk ]

DESCRIPTION

       This program controls ICOM radio transceivers and receivers with  the  CI-V  option.  Most
       recent  ICOM  radios  already  have  this  option;  older  radios can be converted with an
       appropriate adapter mounted inside the radio. Up to four CI-V radios can be connected to a
       single serial port using a level converter such as the CT-17, which includes a MAX232 chip
       and not much else.

       The program implements a virtual radio with a bank of memory channels corresponding to the
       particular  radio model. Each channel can hold frequency, mode and, in the case of VHF/UHF
       FM radios, transmit duplex offset. The virtual radio also  includes  a  variable-frequency
       oscillator  (VFO)  scratch  register,  which  controls  the actual receiver frequency, and
       several values used to control the  tuning  and  mode  selection  functions.  Most  radios
       support USB, LSB, AM, CW and RTTY modes; some support narrow/wide filters and some support
       FM modes as well. Additional features that can be controlled on some  radios  are  antenna
       selection,  scan control, main dial tuning step and several other functions implemented in
       the various radio models.

       The actual VFO frequency, mode and transmit duplex offset is controlled  directly  by  the
       program.  All  other  registers and memory channels are accessed via the VFO, which can be
       loaded from a selected memory channel, modified and written back to the same or  different
       channel.  When  implemented,  the  actual  secondary VFO is controlled by loading from, or
       exchanging contents with, the VFO. Other functions, such as tuning step, tuning  rate  and
       compensation for the actual radio oscillator frequency errors, are performed in software.

       The  program  knows  about  most early and late model ICOM radios. The program can be told
       which model is present or directed to scan for all known models and report each one found.
       A  number  of  diagnostic  tests  are  performed  on the selected radio to determine which
       options are present and to initialize to  a  known  state.  The  program  detects  certain
       anomalistic  behavior  of  some  radios  and  adjusts  its operations to make the behavior
       conform to the model virtual radio.

       The program operates in one of three modes: keyboard batch, and keypad. In keyboard  mode,
       commands  and  arguments  are  entered  from  the keyboard following the icom> prompt, one
       command per line, and the complete command set is  available.  In  batch  mode,  the  same
       commands  and arguments are read from the file specified as an option in the command line.
       In keypad mode, commands and arguments are entered from the keyboard  and  numeric  keypad
       following  the  >  prompt. In this mode, most routine keystrokes use the numeric keypad to
       enter arguments, and the arguments are followed by a  single  character  representing  the
       command  name. Shortcut arrow keys on the keyboard (not the numeric keypad) are used to do
       routine things like tune up/down or increase/decrease the tuning rate.

       Options on the command line can be used to select the radio model and  set  the  frequency
       and  mode.  Using  a suitably crafted Unix crontab file, it is possible to tune a radio to
       different frequencies used by a shortwave broadcaster throughout  the  day,  for  example.
       With  the  minimuf program (available in a separate distribution), it is possible to build
       shell scripts that predict the most likely frequencies and tune the radio accordingly.

       The program includes features to control scanning on some radios and transmit duplex/split
       on  others.  It  also  includes  an  optional  feature  to  control the audio codec on Sun
       workstations. This feature can be used in connection with multimedia conferencing programs
       developed  by  the  Internet  research  community.  The receiver audio is connected to the
       workstation and a MBONE session started with the vat audio tool running. A remote operator
       can  control  the  receiver  via a telnet session and use the feature to control the gain,
       select the input port and mute the speaker as necessary.

BASIC OPERATION

       Most commands and command line options take arguments,  although  many  arguments  can  be
       defaulted.  Unsigned  floating-point frequency arguments specify an absolute VFO frequency
       in MHz, if less than 1000, and in kHz otherwise. Signed  floating-point  (preceded  by  an
       explicit  +  or - character) frequency arguments specify an offset relative to the current
       VFO frequency in kHz.  Signed  or  unsigned  floating-point  offset  arguments  specify  a
       transmit  duplex, split or beat-frequency oscillator (BFO) frequency offset in kHz. Signed
       or unsigned integer step arguments specify a tuning step in Hz. Unsigned  integer  channel
       arguments  specify  a memory channel number ranging from 1 to the highest available in the
       particular radio. A channel number specified as '.' means the currently  selected  channel
       and  '$'  the highest channel available. Other numeric and character string arguments take
       values according to the help menus described below.

       Since the most common function is tuning the radio to different frequencies or scanning  a
       band of frequencies, a compact convention is provided. In either keyboard, keypad or batch
       modes, a valid signed or unsigned floating-point number occurring as the first token on  a
       command line is an implicit command to set the VFO frequency and may be followed by a mode
       specification. In addition, for most commands and arguments, a question mark '?' appearing
       in  either  a  command  or  argument  position causes help information for that command or
       argument to be displayed. The information is in two columns - the first shows a command or
       option name string, while the second column shows a brief description of the function.

       The  program  exits  when command line options are processed and the command line includes
       any option other than -r, -i or -f. This is designed for use in shell  scripts  where  all
       functions  can be completed using only command line options. Keyboard mode is signalled by
       the prefix icom>, while keypad mode is signalled by the prefix > and  batch  mode  has  no
       prefix. Keyboard and batch commands are terminated by the ENTER key on either the keyboard
       or numeric keypad. Keypad commands are terminated by a special character depending on  the
       command.

       A  radio must be selected before any command which controls it. This can be done using the
       radio command in either keyboard or batch modes  and  the  -r  command  line  option.  The
       behavior of the radio command with no argument depends on whether a radio has already been
       selected. If not, the program scans the CI-V bus for all known radios  and  for  each  one
       found  displays  a capability line showing the radio name and tuning range. If a radio has
       already been selected, only its capability line is displayed. The radio command with valid
       argument can be used at any time to reselect a different radio, but only one can be active
       at any given time.

       The chan command selects the memory channel and  transfers  its  contents,  including  the
       frequency,  mode  and  transmit  duplex  offset  to the VFO. The freq command sets the VFO
       frequency, but does not affect the mode. Likewise, the mode command sets the mode  without
       affecting  the frequency. For VHF/UHF radios, the duplex command sets the offset; however,
       at least with the 271, there appears no obvious means to set the sign of this offset.  The
       write  command writes the VFO frequency, mode and offset to the memory channel, destroying
       its prior contents.  The clear command clears the memory channel  for  those  radios  that
       support it.

       Some  ICOM radios do not compensate the local oscillator (LO) when the mode is changed and
       the BFO is shifted in the passband. This has the unfortunate effect of detuning the  radio
       by  an  amount up to 3 kHz when the mode is changed. When one of these radios are detected
       during initialization, the program rewrites the frequency each time the mode  is  set.  In
       the  case  of  transceivers  with  general-coverage receivers, care should be given to the
       setting of the GENE-HAM switch. If in the HAM position, it is not possible to change to  a
       frequency  outside the ham bands. Since the setting of this switch is saved along with the
       frequency and mode in a channel and apparently cannot be changed using radio commands, the
       setting may have to be done manually.

TUNING OPERATIONS

       The  keyboard  mode  can  be  very  awkward when searching a band for signals, since a new
       command must be used every time the frequency is changed.  The  keypad  command  puts  the
       program  in keypad mode and changes the prompt string to ">". In this mode, arguments such
       as frequency, tuning step, etc., can be entered directly from  the  keyboard  and  numeric
       keypad.  Of  course,  the  keypad  must  be in Num Lock mode for this to work properly. In
       keypad mode, the arguments are given first followed by a single character which identifies
       the command and terminates input.

       Most  ICOM  radios  tune  in 10-Hz steps, while some HF radios tune in 1-Hz steps and some
       VHF/UHF radios tune in 100-Hz steps. The program determines the minimum tuning step during
       initialization  and  adjusts  the  various  displays  and  control ranges accordingly. The
       easiest way to tune the radio is using keypad mode and the arrow keys.  The  UP  and  DOWN
       arrow  keys  adjust  the  frequency  up  or  down  one step. The LEFT and RIGHT arrow keys
       decrease and increase the tuning rate (Hz per step) respectively. The rate values begin at
       the minimum tuning step and extend in 1-2.5-5-10 steps to 5 MHz per step.

       Each  press  of  the  UP  and  DOWN  keys  displays the current frequency, mode and either
       transmit duplex offset or split offset. The display is also  produced  by  other  commands
       that  change  these quantities. Each press of the LEFT and RIGHT keys displays the current
       tuning rate.  Each press of the ENTER key displays the current VFO frequency and mode.  If
       preceded  by  a  single  +  or  -,  the  memory  channel  is  incremented  or decremented,
       respectively, and the contents of that channel replace the VFO.  VFO  frequencies  can  be
       entered  directly  using the keypad +, -, ., digit and ENTER keys. With a little practice,
       it is easy to scan a band (say with 1-kHz steps in USB) looking for signals and, when  one
       is  found,  change  to  100-Hz  steps to move closer and then to 10-Hz steps for the final
       adjustment.

       With the arrow keys, the VFO frequency values are constrained to follow integral multiples
       of  the rate values. This prevents leaving the radio on some odd frequency, increasing the
       tuning rate and finding the actual tuning steps landing on odd values. When necessary, The
       step  keyboard  command  or  s  keypad  command  can  be used to change the tuning step to
       arbitrary values. This is useful in some channelized services  with  non-integral  channel
       spacings,  as in the maritime radio services. The rate keyboard command can be used to set
       the rate directly.

TRANSMIT/RECEIVE SPLIT OPERATION

       The 775 and 781 HF transceivers have an auxiliary receiver and VFO that can be very useful
       in  some  operating  modes,  especially for working DX and contests. When split mode is in
       effect, the main VFO is used for receiving and the auxiliary VFO  for  transmitting.  When
       dual-watch  is  enabled,  the  audio  from  both receivers can be combined in a selectable
       ratio. The control program supports both features using keyboard and keypad  commands  and
       one  of  several operating procedures. Commands are provided to load the transmit VFO from
       the receive VFO with selected offset, load the receive VFO  from  the  transmit  VFO  with
       selected  offset,  and  to  swap transmit and receive VFO contents. Upon happening on a DX
       station, for example, its frequency can be saved temporarily in the transmit VFO by the 0>
       keystrokes,  then  the  receive VFO retuned "up ten" to a quiet spot. The VFO contents are
       then swapped by the = keystroke. If the DX station requests  calls  on  frequency,  the  <
       keystroke  restores the receive VFO from the transmit VFO. The split can be toggled on and
       off with the > keystroke. Many variations in these procedures are possible.

FM DUPLEX OPERATION

       Ordinarily, FM repeater operations require that  the  station  receiving  on  a  frequency
       transmit  at  a fixed offset relative to that frequency.  This operation is automatic with
       most VHF/UHF transceivers and keyboard  commands  are  provided  to  read  and  write  the
       transmit  duplex  offset. Keyboard commands are available to specify the duplex offset and
       sign, although some VHF/UHF transceivers apparently have no provision to control the  sign
       of  the  offset.  However,  sometimes  it  is  necessary  to  listen on the repeater input
       frequency, instead of the normal repeater output frequency. To support this  feature,  the
       keypad / keystroke alternates between the repeater input and output frequencies.

SCANNING OPERATION

       For  those  radios  the  support  scanning, a number of commands are provided to start the
       operation in various modes and capture the frequencies found. The general procdure  is  to
       start  the scan and wait for scanning to stop, usually when the squelch is broken. At this
       time, the frequency that stopped the scan is displayed and can be  written  to  a  channel
       with the write command.

       The  band  command  can  be used to set the low and high band edges for software scanning.
       This can be used to  search  a  specific  band  for  channelized  services,  such  as  the
       broadcasting, aviation and marine radio bands. Once the band edges and frequency step have
       been selected, the keyboard UP and DOWN arrow keys can  be  used  to  step  the  frequency
       through  the  band. When stepped above the high band edge, the frequency is set to the low
       band edge. When stepped below the low band edge, the frequency is set  to  the  high  band
       edge.

OSCILLATOR CALIBRATION

       Some  ICOM  radios,  including  the  775 and 781, synthesize all oscillator signals from a
       single master oscillator. Once the master oscillator frequency is  accurately  calibrated,
       the  various LO and BFO signals will be exactly on frequency. Other ICOM radios synthesize
       the LO signal, but use an independent oscillator for the BFO signal. In these radios,  the
       BFO  frequency  is  shifted  using  a  varactor  and  a network of diodes and resistors to
       generate the necessary BFO frequencies. This method is not  very  accurate  when  remotely
       tuning the radio to a narrowband RTTY or packet transmission, for example.

       The program has provisions to compensate for the systematic errors in both the synthesized
       LO signal and varactor-switched BFO signals. This is done by adjusting the  VFO  frequency
       to  compensate for the systematic LO error and individual BFO errors. The LO correction is
       provided by the comp command, while the BFO corrections are provided by the USB, LSB,  CW,
       RTTY, AM and FM mode commands.

       The  calibration  procedure  for  single-oscillator radios like the 775 and 781 is simple.
       Tune the radio to a WWV frequency, preferably the highest one heard  and  listen  for  the
       500-Hz  or  600-Hz modulation tones is present. In keypad mode, switch between USB and LSB
       modes and adjust the frequency using the UP and DOWN arrow keys until the tones sound  the
       same.  The  difference  between  the  indicated frequency and actual frequency can be read
       directly from the display or  from  the  radio.  Divide  this  difference  by  the  actual
       frequency to calculate the VFO compensation in PPM.

       For two-oscillator radios, the calibration procedure requires two frequencies, such as WWV
       on 10 MHz and 20 MHz, for example. First, listen for the tones on the 10 MHz frequency and
       use  the  above  procedure,  but with AM mode substituted for one of the SSB modes.  Then,
       listen for the tones on the 20 MHz and do the same thing. The LO error is computed as  the
       difference  between the 20 MHz and 10 MHz differences divided by the difference in the two
       WWV frequencies, in this case 10 MHz, is the LO frequency error and the value of  the  VFO
       compensation in PPM.

       The calibration procedure continues for each BFO separately. Starting with a WWV signal at
       any frequency, use the above procedure to measure the difference between the indicated and
       actual  frequencies  for  each  of  the  four  BFO  modes USB, LSB, CW and RTTY. Enter the
       corrections the argument to the mode command of the same name. If desired, the  CW  and/or
       RTTY  BFO  frequencies  can  be artificially tweaked to move the center frequency to other
       than the standard offset. These offsets will be automatically programmed each time the VFO
       frequency is changed.

CHANNEL PALETTES

       When  using  this  program  to  operate more than one radio that covers the same frequency
       bands and modes, it may be useful to use a standard set of files, which  could  be  loaded
       into any of the radios directly from the file. The program includes the capability to save
       and restore a block of memory channels to and from a  file  using  the  save  and  restore
       commands.  This  allows channel blocks to be created by other programs and copied from one
       radio to another, for example. The information saved in the file includes  the  frequency,
       mode  and  offset.  The  program  can also execute a list of commands stored in a file and
       interpreted in batch mode.

       However, it often  happens  that  individual  radios  need  slightly  different  frequency
       settings to receive the same frequency transmission, especially when narrow filters are in
       use. A common example is when selecting from a standard set of frequencies provided by the
       minimuf  program  (described elsewhere) and a Unix cron to automatically tune the radio(s)
       throughout the day. The standard frequencies can be maintained in a batch file  common  to
       all radios and loaded by the restore batch command.

       However, the cron script can provide both the frequency -g and individual offset -o values
       specific to each radio on the command line. The  program  adds  this  offset,  along  with
       others  provided by the offset and mode commands, if used, as the frequency is transmitted
       to the radio. Usually, the offset is characteristic of the radio, as  the  result  of  BFO
       frequency error, for example, and can be calibrated manually in advance.

       Batch  mode  is designed for cases where a number of radios are to be cloned or programmed
       with memory channel data produced by another program. In principle, a  Unix  shell  script
       could  search  an  archive  for  the  current  VOA  transmission schedules and transmitter
       locations, another program determine the propagation model and best  frequencies  for  the
       receiver location and current time of day, and then program the radio(s) with the results.

INTERFACE DEBUGGING

       The  program  communicates with one or more radios using the CI-V broadcast bus and serial
       asynchronous protocol. The CT-17 level converter can be used to interface the CI-V voltage
       levels  (TTL)  to  EIA  (RS-232) levels, or a homebrew unit can be made from the MAX232 IC
       plus a handful of capacitors. The CT-17 supports up  to  four  radios,  but  there  is  no
       inherent  protocol  limitation  to  this  number.  The  CI-V  uses active-low drivers with
       resistor pullups, so multiple radios can be connected to the same wire.

       Messages are exchanged in the form of frames beginning with two preamble bytes (0xfe)  and
       ending  with  one  end  of  message byte (0xfd).  In order to handle the older radios, the
       control program operates at 1200 bps; however, it can be compiled  to  operate  at  higher
       speeds.   Each  radio  model is assigned a unique identifier byte, which can be changed if
       necessary. The control program sends a frame with that identifier  and  expects  a  reply,
       either containing data or a single ACK (0xfb) or NAK (0xfa). Most functions implemented by
       the control program require an exchange of several frames.

       It has been the experience that some radios can occasionally fail to respond to a  command
       or  respond  with  a mangled frame. Therefore, the control program includes a good deal of
       error recovery code and uses timeouts and retransmissions as necessary. Since the CI-V bus
       uses a broadcast architecture, every octet transmitted by the control program is read back
       for  verification.  If  the  readback  fails  or  no  reply  is   received   after   three
       retransmissions, the operation fails and an error message is displayed.

       The  trace  command can be used to watch the protocol interactions between the program and
       radios. The argument bus enables packet trace.  The trace operates from  received  octets,
       either  a  readback  of a transmitted frame preceded by "T:" or a copy of a received frame
       preceded by "R:". Each transmission is repeated up to three times in case of error,  after
       which  the  operation  fails  and is reported as an error. The argument packet enables bus
       error messages, which are normally suppressed until the maximum retry limit is reached.

HISTORY

       Written by David L. Mills, W3HCF; this update 25 September  1996.  This  manual  page  was
       created  from  the original HTML documentation by Hamish Moffatt VK3SB <hamish@debian.org>
       for Debian (but may be used by others).

BUGS

       This is a work in progress. Many idiosyncrasies  of  various  ICOM  radios  remain  to  be
       discovered.

                                        25 September 1996                                 icom(1)