HAM::Device::IcomCIV - Class for basic remote control of Icom CI-V Radios
Version 0.02 02. Dec. 2007
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 );
* 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.
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).
Nothing by default.
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
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
HAM::Device::IcomCIVSerialIO Carp;
Creates a new IcomCIV object. Returns the object reference.
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.
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.
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.
Boolean if serial port should use locking or not
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.
The CI-V bus adress of that radio. Can be undef, in that case the default adress of the specified model is used.
The CI-V bus adress of the controller (this computer), usually 0xE0 is used. Can be undef, if so 0xEO is used.
Numeric value, 0 disables debugging, increasing values yield more debug output to STDERR. Default 0.
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:
Is one of
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.
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.
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).
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.
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.
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
Returns the lower and upper frequency limit the radio does support. Frequencies are integer in Hz.
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.
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).
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).
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).
Selects memory mode, previously used memory channel if no parameter is given. Or selects memory channel number if parameter is provided.
Writes the currently displayed frequency and mode to the currently selected VFO. If the selected memory is not empty the previous contents is overwritten.
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.
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.
These functions are used internally.
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.
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.
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
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
Converts two bytes from the Icom CI-V protocol to Filter width
Returned filters are:
NORMAL NARROW WIDE
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:
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
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'.
Ekkehard (Ekki) Plicht, DF4OR, <ekki@plicht.de>
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.
To install HAM::Device::IcomCIV, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HAM::Device::IcomCIV
CPAN shell
perl -MCPAN -e shell install HAM::Device::IcomCIV
For more information on module installation, please visit the detailed CPAN module installation guide.