/ 
FT817COMM-0.9.0_04
River stage zero No dependents
/ Ham::Device::FT817COMM

NAME

Ham::Device::FT817COMM - Library to control the Yaesu FT817 Ham Radio

VERSION

Version 0.9.0_04

SYNOPSIS

use HAM::Device::FT817COMM;

Constructor and Port Configurations

my $FT817 = new Ham::Device::FT817COMM (
serialport => '/dev/ttyUSB0',
baud => '38400',
lockfile => '/var/lock/ft817'
			               );

my $port = $FT817->{'serialport'};
my $baud = $FT817->{'baud'};
my $lockfile = $FT817->{'lockfile'};
my $version = $FT817->moduleVersion;

Destructor

$FT817->closePort;

Initialization

The instance of the device and options are created with the constructor and port configurations shown above. The variable which is an instance of the device may be named at that point. In this case $FT817. The serialport must be a valid port and not locked. You must consider that your login must have permission to access the port either being added to the group or giving the user suffucient privilages. The baudrate 'baud' must match the baudrate of the radio CAT RATE which is menu item 14.

Finally lockfile is recommended to ensure that no other software may access the port at the same time. The lockfile is removed as part of the invocation of the destructor method.

METHODS

1. Using Return Data From a Module

This allows for complete control of the rig through the sub routines all done through the cat interface

$output = 'rigname'->'command'('value');

an example is a follows

$output = $FT817->setLock('ENABLE');

Using this method, the output which is collected in the varible $output is designed to be minimal for use in applications that provide an already formatted output.

For example:

$output = $FT817->setLock('ENABLE');
print "$output";

Would simply return F0 if the command failed and 00 if the command was sucessfull. The outputs vary from module to module, depending on the function

2. Using setVerbose()

The module already has pre-formatted outputs for each subroutine. Using the same example in a different form and setting setVerbose(1) we have the following

setVerbose(1);
$FT817->setLock('ENABLE');

The output would be, for example:

Set Lock (ENABLE) Sucessfull.

Other verbose outputs exist to catch errors.

setVerbose(1);
$FT817->setLock('blabla');

The output would be:

Set Lock (blabla) Failed. Option:blabla invalid.

The setVerbose(2) flag is similar to the setVerbose(1) flag but also provides the bit value of the function at the specified memory address.

An example of all 3 is show below for the command getHome()

As return data: Y
As verbose(1) : At Home Frequency
As verbose(2) : getHome: bit is (1) Home is Y

We see that return data will be suitable for a program which needs just a boolean value, verbose(1) is suitable for a front-end app response, and verbose(2) for internal testing of module.

3. Build a sub-routine into a condition

Another use can be to use a subrouting as a value in a condition statment to test

if ((gethome()) eq 'Y') {
	warn "I guess we're home";
		      }

Call all of the modules, one at a time and look at the outputs, from which you can decide how the data can be used. At this time I have completed a command line front end for this module that makes testing all of the functionality easy.

DEBUGGER

FT817COMM has a built in robust debugger that makes available to the user all transactions between the software and the rig. Where verbose gave the outputs to user initiated subroutines, the debugger does very much the same but with internal functions not designed to be called directly in the userspace. That being said, you should never directly call these system functions or you will quickly turn your 817 into a paperweight or door stop. You have been warned.

Feel free to use the debugger to get an idea as to how the module and the radio communicate.

setDebug(1); # Turns on the debugger

The first output of which is:

DEBUGGER IS ON

Two distinct type of transactions happen with the debugger, they are:

CAT commands   :	Commands which use the Yaesu CAT protocol
EPROMM commands:	Commands which read and write to the EEPROM

With the command: getMode() we get the regular output expected, with verbose(1)

Mode is FM

However with the setDebug(1) we will see the following output to the same command:

sendcat:debug - DATA OUT ----> 00 00 00 00 0x03
sendcat:debug - DATA IN <----- 1471200008
Mode is FM

The sendcat:debug shows the request of 00 00 00 00 0x03 sent to the rig, and the rig returning 1471200008. What were looking at is the last two digits 08 which is parsed from the block of data. 08 is mode FM. FT817COMM does all of the parsing and conversion for you.

As you might have guessed, the first 8 digits are the current frequency, which in this case is 147.120 MHZ. The getFrequency() module would pull the exact same data, but parse it differently

The debugger works differently on read/write to the eeprom. The next example shown below used the function getNb(), the noiseblocker status.

eepromdecode:debug - Output from MSB:0 LSB:57 : 11000010
Noise Blocker is OFF

The output shows that the status of noise blocker lives at 0x57 it happens to be bit 5 of this data (0) that indicates that the noiseblocker is OFF.

Modules

agreeWithwarning()
	$agree = $FT817->agreeWithwarning(#);

Turns on and off the internal flag that says. You undrstand the risks of writing to the EEPROM
Activated when any value is in the (). Good practive says () or (1) for OFF and ON.

Returns the argument sent to it on success.
closePort()
	$FT817->closePort();

This function should be executed at the end of the program.  This closes the serial port and removed the lock
file if applicable.  If you do not use this, and exit abnormally, you will need to manually remove the lock 
file if it was enabled in the settings.
dec2bin()
Simple internal function for converting decimal to binary. Has no use to the end user.
eepromDecode()
An internal function to retrieve code from an address of the eeprom and convert the first byte to 
binary, dumping the second byte.
getAgc()
	$agc = $FT817->getAgc();

Returns the current setting of the AGC: AUTO / FAST / SLOW / OFF
getConfig()
	$config = $FT817->getConfig();

Returns the two values that make up the Radio configuration.  This is set by the soldier blobs
of J4001-J4009 in the radio.
getDsp()
	$dsp = $FT817->getDsp();

Returns the current setting of the Digital Signal Processor (if applicable) : ON / OFF
getEeprom()
	$value = $FT817->getEeprom();

Currently returns just the value you send it. In verbose mode however, it will display a formatted
output of the memory address specified.  This was added late and will be update in the next release.
getFasttuning()
	$fasttune = $FT817->getFasttuning();

Returns the current setting of the Fast Tuning mode : ON / OFF
getFlags()
	$flags = $FT817->getFlags();

Returns the current status of the flags : DEBUG / VERBOSE / WRITE ALLOW / WARNED
getFrequency()
	$frequency = $FT817->getFrequency(#);

Returns the current frequency of the rig eg. B<14712000> with B<getFrequency()>
Returns the current frequency of the rig eg. B<147.120.00> MHZ with B<getFrequency(1)>
getHome()
	$home = $FT817->getHome();

Returns the current status of the rig being on the Home Frequency : Y/N
getLock()
	$lock = $FT817->getLock();

Returns the current status of the lock function being enable : Y/N
getMode()
	$mode = $FT817->getMode();

Returns the current Mode of the Radio : AM / FM / USB / CW etc.......
getNb()
	$nb = $FT817->getNb();

Returns the current Status of the Noise Blocker : ON / OFF
getRfgain()
	$rfgainknob = $FT817->getRfgain();

Returns the current Functionality of the RF-GAIN Knob : RFGAIN / SQUELCH
getRxstatus()
	$rxstatus = $FT817->getRxstatus({variables/hash});

Retrieves the status of SQUELCH / S-METER / TONEMATCH / DESCRIMINATOR in one
command and posts the information when verbose(1).  

Returns with variables as argument $squelch $smeter $smeterlin $desc $match
Returns with hash as argument %rxstatus
getSoftcal()
	$softcal = $FT817->getSoftcal({console/file filename.txt});

This command currently works with verbose and write to file.  Currently there is no
usefull return information.  With no argument, it defaults to console and dumps the
entire 76 software calibration memory areas to the screen.  Using file along with a 
file name writes the output to a file.  It's a good idea to keep a copy of this
in case the eeprom gets corrupted and the radio factory defaults.  If you dont have 
this information, you will have to send the radio back to the company for recalibration.
getTuner()
	$tuner = $FT817->getTuner();

Returns the current tuner setting : VFO / MEMORY
getTxpower()
	$txpower = $FT817->getTxpower();

Returns the current Transmit power level : HIGH / LOW3 / LOW2 / LOW1
getTxstatus()
	$txstatus = $FT817->getTxstatus({variables/hash});

Retrieves the status of POWERMETER / PTT / HIGHSWR / SPLIT in one
command and posts the information when verbose(1).  

Returns with variables as argument $pometer $ptt $highswr $split
Returns with hash as argument %txstatus
getVfo()
	$vfo = $FT817->getVfo();

Returns the current VFO : A / B
hex2bin()
Simple internal function for convrting hex to binary. Has no use to the end user.
moduleVersion()
	$version = $FT817->moduleVersion();

Returns the version of FT817COMM.pm to the software calling it.
new()
	my $FT817 = new Ham::Device::FT817COMM (
	serialport => '/dev/ttyUSB0',
	baud => '38400',
	lockfile => '/var/lock/ft817'
				               );

Creates an instance of the device that is the Radio.  Called at the begining of the program.
See the Constructors section for more info.
restoreEeprom()
	$restorearea = $FT817->restoreEeprom();

This restores a specific memory area of the EEPROM back to a known good default value.
This is a WRITEEEPROM based function and requires both setWriteallow() and agreeWithwarning()
to be set to 1.
This command does not allow for an arbitrary address to be written. Currently only 5f is allowed

restoreEeprom(5f); 

Returns 'OK' on success. Any other optput an error.
sendCat()
Internal function, if you try to call it, you may very well end up with a broken radio.
You have been warned.
setClarifier()
	$setclar = $FT817->setClarifier({enable/disable});

Enables or disables the clarifier

Returns '00' on success or 'f0' on failure
setClarifierfreq()
	$setclarfreq = $FT817->setClarifierfreq(####);

Uses 4 digits as an argument to set the Clarifier frequency.  Leading and trailing zeros required where applicable
 1.234 KHZ would be 1234

Returns '00' on success or 'f0' on failure
setCtcssdcs()
	$ctcssdcs = $FT817->setCtcssdcs({DCS/CTCSS/ENCODER/OFF});

Sets the CTCSS DCS mode of the radio

Returns 'OK' on success or something else on failure
setCtcsstone()
	$ctcsstone = $FT817->setCtcsstone(####);

Uses 4 digits as an argument to set the CTCSS tone.  Leading and trailing zeros required where applicable
 192.8 would be 1928 as an argument

Returns '00' on success or 'f0' on failure
setDcscode()
	$dcscode = $FT817->setDcscode(####);

Uses 4 digits as an argument to set the DCS code.  Leading and trailing zeros required where applicable
 0546 would be 546 as an argument

Returns '00' on success or 'f0' on failure
setDebug()
	$debug = $FT817->setDebug(#);

Turns on and off the internal debugger. Provides information on all serial transactions when on.
Activated when any value is in the (). Good practive says () or (1) for OFF and ON.

Returns the argument sent to it on success.
setFrequency()
	$setfreq = $FT817->setFrequency(########);

Uses 8 digits as an argument to set the frequency.  Leading and trailing zeros required where applicable
147.120 MHZ would be 14712000
 14.070 MHZ would be 01407000

Returns '00' on success or 'f0' on failure
setLock()
	$setlock = $FT817->setLock({enable/disable});

Enables or disables the radio lock.

Returns '00' on success or 'f0' on failure
setMode()
	$setmode = $FT817->setMode({LSB/USB/CW/CWR/AM/FM/DIG/PKT/FMN/WFM});

Sets the mode of the radio with one of the valid modes.

Returns '00' on success or 'f0' on failure
setOffsetfreq()
	$offsetfreq = $FT817->setOffsetfreq(########);

Uses 8 digits as an argument to set the offset frequency.  Leading and trailing zeros required where applicable
1.230 MHZ would be 00123000

Returns '00' on success or 'f0' on failure
setOffsetmode()
	$setoffsetmode = $FT817->setOffsetmode({POS/NEG/SIMPLEX});

Sets the mode of the radio with one of the valid modes.

Returns '00' on success or 'f0' on failure
setPower()
	$setPower = $FT817->setPower({ON/OFF});

Sets the power of the radio on or off. Note that this function, as stated in the manual only works
Correctly when connected to DC power and NO Battery installed 

Returns '00' on success or 'null' on failure
setPtt()
	$setptt = $FT817->setPtt({ON/OFF});

Sets the Push to talk of the radio on or off.  

Returns '00' on success or 'f0' on failure
setSplitfreq()
	$setsplit = $FT817->setSplitfreq({enable/disable});

Sets the radio to split the transmit and receive frequencies

Returns '00' on success or 'f0' on failure
setWriteallow()
	$writeallow = $FT817->setWriteallow(#);

Turns on and off the write Flag. Provides a warning about writing to the EEPROM and
requires the agreeWithwarning()  to also be set to 1 after reading the warning
Activated when any value is in the (). Good practive says () or (1) for OFF and ON.

Returns the argument sent to it on success.
toggleRfgain()
	$togglerf = $FT817->toggleRfgain();

Toggles the RF-GAIN knob between RFGAIN or SQLELCH.  This is a WRITEEEPROM based
function and requires both setWriteallow() and agreeWithwarning() to be set to 1.
In the event of a failure, the memory area can be restored with. The following
command that also requires both flags previously mentioned set to 1.

restoreEeprom(5f); 

Returns 'OK' on success. Any other optput an error.
vfoToggle()
	$vfotoggle = $FT817->vfotoggle();

Togles the VFO between A and B

Returns '00' on success or 'f0' on failure
writeEeprom()
Internal function, if you try to call it, you may very well end up with a broken radio.
You have been warned.

AUTHOR

Jordan Rubin KJ4TLB, <jrubin at cpan.org>

BUGS

Please report any bugs or feature requests to bug-ham-device-ft817comm at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Ham-Device-FT817COMM. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command. perldoc Ham::Device::FT817COMM

You can also look for information at:

ACKNOWLEDGEMENTS

Thank you to Clint Turner KA7OEI for his research on the FT817 and discovering the mysteries of the EEprom FT817 and Yaesu are a registered trademark of Vertex standard Inc.

LICENSE AND COPYRIGHT

Copyright 2014 Jordan Rubin.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder. This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.