fldigi 0.0.8 → 0.0.9

data/lib/fldigi.rb

@@ -16,17 +16,36 @@
 # More documentation is forthcoming, but for the moment, refer to the
 # clients published along with this library to see how to use it.
 
+# Version History:
+#
+# 0.0.9 - 05/26/2014 - jfrancis - Added a lot of code comments.
+#
+# 0.0.8 - 05/26/2014 - jfrancis - Fixed 10m propnet frequency. Got
+# carried away with 0.0.7 fix, and had one too many zeros in there.
+#
+# 0.0.7 - 05/26/2014 - jfrancis - All propnet frequencies were low by
+# an order of magnitude (ie, left off a zero).
+#
+# 0.0.6 - 05/25/2014 - jfrancis - First public release on
+# rubygems.org.
+
 class Fldigi
   attr_accessor :rigctl, :freq, :carrier, :call, :modem, :afc, :rsid, :sideband, :squelch, :slevel, :spot, :delay, :grid, :phg, :band
 
   # Do the initial setup.  All arguments are optional, default is
-  # rigctl, localhost, standard port.
+  # rigctl, localhost, standard port.  If you have no rig control,
+  # call with "Fldigi.new(false)".  If you want to remote control an
+  # FLDigi instance that's not on the local machine and/or has a
+  # non-standard port number, you'll have to supply all three options,
+  # like "Fldigi.new(true,10.1.2.3,7362)".
   def initialize(rigctl=true, host="127.0.0.1", port=7362)
+    # Housekeeping.
     @host=host
     @port=port
     @message=""
     @rigctl=rigctl
 
+    # Set up the defaults.
     @freq=14070000.0
     @freq_old=nil
     @carrier=1000
@@ -48,6 +67,7 @@ class Fldigi
     @spot=nil
     @spot_old=nil
 
+    # Propnet stuff.
     @band=nil
     @fsym=nil
     @delay=nil
@@ -55,22 +75,21 @@ class Fldigi
     @phg=nil
     @phgtext=""
 
+    # Connect to the FLDigi instance.
     @srvr=XMLRPC::Client.new(host,"/RPC2",port)
   end
 
   # Send a command to FLDigi.
   def sendcmd(cmd, param=-1)
     if param==-1
-      #puts "#{cmd}"
       return @srvr.call(cmd)
     else
-      #puts "#{cmd} : #{param}"
       return @srvr.call(cmd,param)
     end
   end
 
   # Push all of the changed settings to FLDigi.  Anything that has not
-  # changes is not pushed (to save time).
+  # changed is not pushed (to save time).
   def config
 
     # Set the audio carrier.
@@ -118,7 +137,8 @@ class Fldigi
       end
     end
     
-    # Set the sideband ("USB"/"LSB").
+    # Set the sideband ("USB"/"LSB").  ToDo: make sure this is
+    # correct.
     if @sideband!=@sideband_old
       @sideband_old=@sideband
       if @sideband!=self.sendcmd("main.get_sideband")
@@ -164,11 +184,16 @@ class Fldigi
     end
 
     # Set the radio frequency (in hz).  If the user has specified no
-    # rig control, it simply returns.  Otherwise, it returns true if
-    # successful, false if it fails.  The sleep here gives the radio
-    # time to change frequencies before checking.  0.5 seconds work
-    # with all of my radios, but it's possible this will need to be
-    # tweaked.
+    # rig control, it simply returns true and ignores the provided
+    # value (this is so people who don't have rig control can still
+    # use the other features of the library, they just can't set the
+    # radio frequency).  Otherwise, it returns true if successful in
+    # setting the frequency, false if it fails.  The sleep here gives
+    # the radio time to change frequencies before checking.  0.5
+    # seconds work with all of my radios, but it's possible this will
+    # need to be tweaked.  Send me an e-mail if this value is not
+    # adequate for your radio, and I'll figure out a plan.  So far, it
+    # works on my IC-706MkII, my IC-756Pro, and my FT-817.
     @freq=@freq.to_f
     if @freq!=@freq_old and @rigctl
       @freq_old=@freq
@@ -198,7 +223,10 @@ class Fldigi
     end
   end
   
-  # Set FLDigi to transmit (immediate).
+  # Set FLDigi to transmit (immediate).  When switched to transmit,
+  # FLDigi will send whatever text exists in FLDigi's transmit buffer
+  # (which is *not* the same thing as the object's internal message
+  # queue called @message).
   def transmit
     if self.sendcmd("main.get_trx_status")=="tx"
       return true
@@ -213,7 +241,16 @@ class Fldigi
   end
   
   # Send the currently buffered data using the carrier, mode,
-  # frequency, etc. currently configured.
+  # frequency, etc. currently configured.  The current code will wait
+  # up to ten seconds for the first character to be transmitted (this
+  # gives time for really slow modems to get rolling).  Once the first
+  # sent character is detected, it makes sure it sees as least one
+  # character every two seconds (which again, is just enough for the
+  # very slowest modem).  You can set the two second value lower if
+  # you're only going to use fast modems, but if you forget and use a
+  # slow modem with this set lower, you'll chop off your own
+  # transmissions.  This value also affects how long of an idle is
+  # left after the last character.  Everything's a trade-off...
   def send_buffer
     if @message.length > 0
       self.sendcmd("text.add_tx",@message)
@@ -241,39 +278,44 @@ class Fldigi
   end
 
   # Add a string of text to the outgoing buffer.  If you want carriage
-  # returns, you must supply them.
+  # returns, you must supply them as part of the text (ie, "foo\n").
   def add_tx_string(text)
     @message=@message+text
     return @message
   end
 
-  # Get the received data accumulated since the last time you asked.
+  # Return the received data accumulated since the last time you asked.
   def get_rx_data
     return self.sendcmd("rx.get_data")
   end
 
-  # Get the tranmitted data accumulated since the last time you asked.
+  # Return the tranmitted data accumulated since the last time you asked.
   def get_tx_data
     return self.sendcmd("tx.get_data")
   end
 
-  # Clear the incoming data buffer (you probably don't want to do
-  # this).
+  # Clear FLDigi's incoming data buffer (you probably don't want to do
+  # this, except *possibly* the first time you connect).
   def clear_rx_data
     return self.sendcmd("text.clear_rx")
   end
 
-  # Clear any buffered untransmitted data.
+  # Clear any buffered untransmitted data (as with clear_rx_data(),
+  # this is something you'll use sparingly, if at all).
   def clear_tx_data
     return self.sendcmd("text.clear_tx")
   end
 
-  # Clear out the internal buffered message.
+  # Clear out the internal buffered message.  This clears the internal
+  # object's message queue, but does not change what may or may not be
+  # queued in FLDigi for transmission (clear_tx_data() does that).
   def clear_message
     @message=""
   end
 
-  # Return a list of valid modems.
+  # Return a list of valid modems supported by FLDigi.  Note that not
+  # all modems make sense and/or will work.  Like Feld Hell, for
+  # example.  Or the Wefax modes.
   def list_modems
     return self.sendcmd("modem.get_names")
   end
@@ -284,16 +326,23 @@ class Fldigi
     return self.sendcmd("fldigi.list")
   end
   
-  # Setup for propnet.  Must call config() one time after this before
-  # propnet() can be called as many times as desired.  If @band,
-  # @grid, @phg, or @call changes between calls to propnet(), this
-  # method must be called again.
+  # Setup for propnet.  You must call config() one time after this
+  # before propnet() can be called as many times as desired.  If
+  # @band, @grid, @phg, or @call changes between calls to propnet(),
+  # this method (and config()) must be called again.
   def propnet_config
     if @call and @grid and @band and @phg
       
+      # We don't want the carrier wandering around while doing
+      # propnet.
       @afc=false
+
+      # The carrier for North America is 1500hz.  Might (probably is)
+      # different for other places.  ToDo: fix this so it's
+      # user-settable.
       @carrier=1500
 
+      # Transmit frequencies are pre-defined by the propnet folks.
       case @band.to_i
       when 80
         @freq=3598200
@@ -325,27 +374,30 @@ class Fldigi
       else
         return false
       end
-      
+
+      # Figure out how long to sleep based on the supplied PHG value.
       if @phg[7,1].to_i==0
         @delay=nil
       else
         @delay=3600/(@phg[7,1].to_i)
       end
 
+      # Construct the actual string to be sent.
       tmp="#{@call.downcase}>#{@fsym}:[#{@grid}]#{@phg}/^"
       tmp=tmp+((self.crc16(tmp)).to_s(16)).upcase
       @phgtext="FOR INFO: http://www.PropNET.org\n"+tmp
     end
   end
 
-  # Construct and queue a PropNET packet.  Requires @grid, @call,
-  # @band, and @phg to be set.  Call send_buffer() after.
+  # Queue the pre-built PropNET packet (must call propnet_config() and
+  #  config() first).  Requires @grid, @call, @band, and @phg to be
+  #  set.  Call send_buffer() after to start the actual transmission.
   def propnet
     self.add_tx_string(@phgtext)
   end
 
-  # Call CQ.  Requires that @call be previously set, else returns
-  # false.  Call send_buffer() after.
+  # Queues up a CQ call.  Requires that @call be previously set, else
+  # returns false.  Call send_buffer() after to begin transmission.
   def cq
     if @call
       self.add_tx_string("CQ CQ CQ de #{@call} #{@call} #{@call} pse k")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fldigi
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors: