xenial (1) icom.1.gz

Provided by: icom_20120228-2_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)