NAME

HAM::Device::IcomCIV - Class for basic remote control of Icom CI-V Radios

MODULE VERSION

Version 0.02 02. Dec. 2007

SYNOPSIS

  use HAM::Device::IcomCIV;

  # initiate first radio
  my $rig1 = HAM::Device::IcomCIV->new( undef, '/dev/ttyS1', 1, 19200, 'IC-R8500', 0x4A, 0xE0, 1 );

  my ($lower, $upper) = $rig1->get_bandedges;

  my $freq = $rig1->frequency;
  $rig1->frequency(6075000);

  my $mode = $rig1->mode;
  my ($mode, filter) = $rig1->mode;
  $rig1->mode('AM');
  $rig1->mode('AM', 'NARROW');

  ...
  # initiate second radio on same bus (same serial port)
  $my $serio = $rig1->get_serioobject;

  $my $rig2 = HAM::Device::IcomCIV->new( $serio, undef, undef, undef, 'IC-R75', undef, 0xE0, 1 );

SUPPORTED CI-V FUNCTIONS

 * Read/Set Frequency
 * Read/Set Mode
 * Read Band Edges
 * Switch to VFO (last selected or A or B or Main or Sub)
 * Switch to Memory
 * Select Memory channel
 * Clear Memory channel
 * Transfer Memory to VFO
 * Write VFO contents to selected memory

If you are looking for support of more elaborate CI-V functions see descendants of HAM::Device::IcomCIV, like HAM::Device::IcomICR8500, HAM::Device::IcomICR75 etc. These classes implement functions specific to the radio. If these classes do not implement what you want, derive your own class from HAM::Device::IcomCIV.

DESCRIPTION

This module is an OO approach to use Icom radios attached to a serial port.

HAM::Device::IcomCIV is not an abstract class, but one you can use directly. It allows for the most basic form of remote control of practically any Icom radio equipped with a CI-V port, namely set & get of the displayed frequency, set & get the mode and filter, read the band edges, switch to VFO or Memory (if radio has a VFO), select a memory channel, write VFO data to memory and clear a memory.

It supports multiple radios on the same serial port, differentiated by their CI-V adress. Note: If you have two or more identical models on the same bus, they must use different CI-V adresses.

This class can be used in a procedural manner or with an event callback mechanism (or both at the same time). When used without callbacks you just use the provided methods for setting or getting radio settings (Frequency, Mode etc.). If you use the callback mechanism you will receive a callback to your sub (set with set_callback) which tells you what happened, i.e. which data was received (see event and status constants).

EXPORT

Nothing by default.

STATUS CONSTANTS (exported on demand)

    stGOOD      all ok, command succeeded
    stFAIL      command to radio failed
    stNOIM      command not implemented in this class (not recognized)
    stWAIT      wait, status update in progress
    stINIT      occurs only after new() and if no command has been issued yet

EVENT CONSTANTS (exported on demand)

    evSTAT      Status GOOD/NOGOOD received
    evFREQ      A new frequency has been received
    evMODE      A new mode/filter has been received
    evUNKN      Unknown command response received
    evNOEV      Fake, no event has happened so far
    evEDGE      Band Edges have been received

USES

    HAM::Device::IcomCIVSerialIO
    Carp;

METHODS

new( SerialIOobject, SerialDevice, Baudrate, UseLock, RadioModel, RadioAdr, OwnAdr, DebugLevel )

Creates a new IcomCIV object. Returns the object reference.

SerialIOobject

Is a ref to an instance of HAM::Device::IcomCIVSerialIO. If undef a new SerialIO object will be created with the following two parameters. If defined no new SerialIO object will be created but this one will be used instead. This allows to share one SerialIO object between several instances of IcomCIV (see method get_serioobject() ).

Either SerialIOobject or SerialDevice must be set, otherwise new will die.

SerialDevice

Must be present at least once (if you have multiple radios on one serial bus). Can be undef for subsequent calls for the creation of a 2nd, 3rd etc. radio which use the same serial port as the first. Default is /dev/ttyS1. If undef the previous parameter mus tbe set.

Baudrate

If SerialDevice is given, this value should be given as well. If SerialDevice is undef this value is ignored. If SerialDevice is present and this valus is undef, defaults to 19200.

UseLock

Boolean if serial port should use locking or not

RadioModel

Must be exactly one of the model names defined in this module, case does not matter. If model is not known the creation of the object will fail. See below for a list of recognized models.

RadioAdr

The CI-V bus adress of that radio. Can be undef, in that case the default adress of the specified model is used.

OwnAdr

The CI-V bus adress of the controller (this computer), usually 0xE0 is used. Can be undef, if so 0xEO is used.

DebugLevel

Numeric value, 0 disables debugging, increasing values yield more debug output to STDERR. Default 0.

set_callback ( ref_to_sub )

With this method the callback subroutine is set for later calls. After each received message from the CI-V protocol this sub is called with the following parameters:

event

Is one of

    evSTAT      Status GOOD/NOGOOD received
    evFREQ      A new frequency has been received
    evMODE      A new mode/filter has been received
    evUNKN      Unknown command response received
    evNOEV      Fake, no event has happened so far
    evEDGE      Band Edges have been received
state

Is one of

    stGOOD      all ok, command succeeded
    stFAIL      command to radio failed
    stNOIM      command not implemented in this class (not recognized)
    stWAIT      wait, status update in progress
    stINIT      occurs only after new() and if no command has been issued yet
data1, data2

Contents of data1 and data2 depends on the specific event:

    Event   data1           data2
    ------------------------------
    evFREQ  frequency       undef
    evMODE  mode            filter
    evEDGE  loedge          hiedge
    evSTAT  undef           undef
    evUNKN  commandbyte     undef

The callback function should handle the received data (e.g. display it) and return without much delay. Currently there is no protection that the callback is not called again and again before returning. I.e. your callback function should be re-entrant.

get_serioobject()

Returns the HAM::Device::IcomCIVSerialIO object which was initiated in an earlier instance of HAM::Device::IcomCIV. For use in a subsequent instance of this module for another radio on the same bus.

process_buffer( buffer )

This is the central routine which is called whenever a CI-V telegram has been received. It receives a byte buffer, filled with the entire CI-V telegram, including leading 0xFE 0xFE, but excluding the trailing 0xFD.

This basic class IcomCIV::Radio implements decoding of command responses which are supported by most Icom radios. That is:

    get freq          0x00 or 0x03 received
    get mode/filter   0x01 or 0x04 received
    get Band edges    0x02 received
    GOOD              0xFB received
    NOGOOD            0xFA received

All other responses are not recognized by this class and should be handled by a descendant for an individual model. See HAM::Device::IcomICR8500 or HAM::Device::IcomICR75 for examples of descendant classes.

At the end of process_buffer the upper layer (application) is called by it's callback (if set).

frequency( [integer] )

Sets (when issued with parameter) or gets (without parameter) the frequency of a radio. Frequency is integer in Hz.

Setting the frequency uses the command 0x05 which yields a GOOD/NOGOOD response from the radio, so expect a status event after setting the frequency (if you use the event callback).

Alternatively there exists the method set_frequency which uses command 0x00, which does not yield a response from the radio. So you will not receive a status event or any feedback if your command was successful or not, but it's slightly faster.

Getting a frequency interrogates the radio and waits (blocks) until the radio returns the frequency (integer, in Hz). A later version will implement a timeout.

If events are used (if callback is set) you will also receive a evFREQ event. Before sending the query command to the radio the status is set to stWAIT, it will change to stGOOD if a frequency was received.

mode( Modestring [, Filterstring] )

Sets (when issued with parameter) or gets (without parameter) the current mode and filter of the radio (USB. LSB, AM etc.). Optional parameter is filter, so mode and filter can be set with one call.

Setting the mode uses the command 0x06 which yields a GOOD/NOGOOD response from the radio, so expect a status event after setting the mode (if you use the event callback).

Alternatively there exists the method set_mode which uses command 0x01, which does not yield a response from the radio. So you will not receive a status event or any feedback if your command was successful or not.

Getting a mode interrogates the radio and waits (blocks) until a response is received. A later version will implement a timeout. In scalar context only mode is returned, in list context mode and filter is returned. Returned strings are human readable like USB, LSB, AM etc., and NORMAL, NARROW or WIDE for filter. See IcomCIV::Support for all possible modes and filters.

If events are used (if callback is set) you will also receive a evMODE event. Before sending the query command to the radio the status is set to stWAIT, it will change to stGOOD if a mode/filter was received.

status( )

Returns the current status, one of: stGOOD all ok, command succeeded stFAIL command to radio failed stNOIM command not implemented in this class (not recognized) stWAIT wait, status update in progress stINIT occurs only after new() and if no command has been issued yet

get_bandedges( )

Returns the lower and upper frequency limit the radio does support. Frequencies are integer in Hz.

select_vfo( [A|B|MAIN|SUB] )

Selects the VFO mode. If no parameter is given the previously selected VFO (A or B, Main or Sub) is selected. With parameter 'A', 'B', 'Main' or 'Sub' the respective VFO is selected. Works only with radio which have a VFO (not all do).

If successful status is set to stGOOD and a evSTAT event happens.

equal_vfo( )

Equalizes VFO A and VFO B. If successful status is set to stGOOD and a evSTAT event happens. Works only with radios which have a VFO (not all do).

exchange_vfo( )

Swaps VFO A and VFO B. If successful status is set to stGOOD and a evSTAT event happens. Works only with radios which have a VFO (not all do).

equal_mainsub( )

Swaps VFOs MAIN and SUB. If successful status is set to stGOOD and a evSTAT event happens. Works only with radios which have a Main/Sub VFO (not all do).

select_mem( [number] )

Selects memory mode, previously used memory channel if no parameter is given. Or selects memory channel number if parameter is provided.

If successful status is set to stGOOD and a evSTAT event happens.

write_mem( )

Writes the currently displayed frequency and mode to the currently selected VFO. If the selected memory is not empty the previous contents is overwritten.

If successful status is set to stGOOD and a evSTAT event happens.

xfer_mem( )

Transfers the contents (Frequency, Mode) of currently selected memory channel to the VFO. Please note that this command behaves differently, depending whether the radio is currently in Memory or VFO mode. Check the authors website for more details.

If successful status is set to stGOOD and a evSTAT event happens.

clear_mem( )

Erases the currently selected memory channel. With most radios this works only if the radio is currently in memory mode and fails (status stFAIL) when in VFO Mode.

If successful status is set to stGOOD and a evSTAT event happens.

CLASS FUNCTIONS

These functions are used internally.

int2bcd( frequency, want_nr_of_bytes )

Converts an integer number to a BCD string as used with the CI-V protocol. Length of BCD string is want_nr_of_bytes.

Frequency as integer, BCD string is LSB first. If frequency results in a longer BCD string than requested by want_nr_of_bytes it is cut off.

bcd2int( List_of_BCD_bytes )

Converts a list of BCD bytes to an integer number. List of BCD bytes must be LSB first, as used with the Icom CI-V protocol. Returns the resulting frequency as integer.

icom2mode( mode, model )

Converts mode byte as used by the Icom CI-V protocol to a readable string. Returns the mode string.

Valid modes are (depending on radio):

    LSB, USB,
    AM, S-AM,
    CW, CW-R,
    RTTY, RTTY-R,
    FM, WFM,
    PSK, PSK-R

mode2icom( mode_string )

Reverse of above, converts mode string to Icom byte. Returns one mode byte as chr. If mode is not recognized the invalid modebyte '0x99' is returned. If you do not check the return value and send this to the radio, it will respond with a stFAIL status.

Valid modes: see icom2mode

icom2filter( mode, filter )

Converts two bytes from the Icom CI-V protocol to Filter width

Returned filters are:

    NORMAL
    NARROW
    WIDE

filter2icom( mode_string, filter_string )

Converts mode and filter string to Icom filter byte. Requires mode byte as well, because possible filters depend on mode. Returns filter byte as chr. Please note that an invalid filter is not mapped to an invalid code but to 'Normal'.

Valid mode strings: depending on radio, also see icom2mode Valid filter strings:

    NORMAL
    NARROW
    WIDE

get_civ_adress( model )

Returns the default CI-V bus adress for a model if found (as integer), otherwise undef.

Valid models are:

    IC-1271       IC-707   IC-7400      IC-7800    IC-R9000
    IC-1275       IC-718   IC-746PRO    IC-820     IC-R9500
    IC-271        IC-725   IC-751A      IC-821     IC-X3
    IC-275        IC-726   IC-756       IC-910
    IC-375        IC-725   IC-756PRO    IC-970
    IC-471        IC-726   IC-756PRO2   IC-R10
    IC-475        IC-728   IC-756PRO3   IC-R20
    IC-575        IC-729   IC-761       IC-R71
    IC-7000       IC-735   IC-765       IC-R72
    IC-703        IC-736   IC-7700      IC-R75
    IC-706        IC-737   IC-775       IC-R7000
    IC-706 MK2    IC-738   IC-78        IC-R7100
    IC-706 MK2G   IC-746   IC-781       IC-R8500

SEE ALSO

    HAM::Device::IcomCIVSerialIO
    HAM::Device::IcomICR8500
    HAM::Device::IcomICR75
    and probably other IcomCIV modules

    Icom CI-V Protocol Specification by Icom
    Documentation of the CI-V protocol in any recent Icom radio manual
    Documentation of the CI-V protocol at the authors website
    http://www.df4or.de

If you are looking for a library which supports more radios than just Icoms, look for 'grig' or 'hamlib'.

AUTHOR

Ekkehard (Ekki) Plicht, DF4OR, <ekki@plicht.de>

COPYRIGHT AND LICENSE

Copyright (c) 2007 Ekkehard (Ekki) Plicht. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.