Created Radio Specific Notes (markdown)

Radio-Specific-Notes.md

@@ -0,0 +1,212 @@
+# Radio Specific Notes
+This section details various notes on radio backends regarding backend or hardware limitations and bugs noted when using the backend to control a given piece of hardware. 
+
+[TOC]
+
+## FT-747
+*From Chris Bryant, G3WIE, regarding the ft747 backend.*
+
+The Hamlib backend for the Yaesu FT-747GX was updated for hamlib 1.2.11.
+
+### Variants of the FT-747GX
+
+It is clear that there are at least two variants of the FT-747GX as far as the CAT system is concerned. Some of the information on CAT in the users manual is also wrong. The new backend has been tested with two FT-747GX that were clearly different, I will call them model X and model Y (note these are not Yaesu numbers). 
+
+### Model X
+
+* The status returned in response to an UPDATE command contains 345 bytes.
+* The delay between bytes in a command can be anything between 0 and 200mS.
+* There is no indication on the display that a CAT command is received. 
+
+### Model Y
+
+* The status returned in response to an UPDATE command contains 344 bytes.
+* The delay between bytes in a command can be anything between 0 and 19mS, but no more (the incorrect manual says 50 - 200mS).
+* When a CAT command is received, the word CAT flashes briefly in the top left hand corner of the display. This only indicates receipt not execution. 
+
+### Other notes
+
+If your FT-747GX refuses to work with Hamlib, check/adjust the following:
+
+1. You are using Hamlib 1.2.11 or later.
+2. Try changing the interbyte delay using rigctl command line parameter -C write_delay=xxx.
+3. The FT-747GX CAT interface uses TTL levels (0V and 5V nominal) and you must use an RS-232 converter to connect to a PC. The FT-747GX serial output connection (SO) is driven by an emitter follower with no emitter resistor to 0V. Your converter may not present a suitable load, so try connecting a 5K6 resistor between SO and 0V.
+4. Converters which get their power from other RS232 signals have been known not to work.
+5. The status data returned from the FT-747GX in response to an UPDATE command takes nearly 1 second at 4800 baud (the fastest speed allowed). While sending this data, the rig ignores other commands sent to it.
+6. You cannot tune the rig while it is transmitting. 
+
+## FT-890
+
+*From Nate Bargmann, N0NB, author of the ft890 backend.*
+
+### Quirks, known bugs, and other notes
+
+In this document I'll try to describe the behavior of the Yaesu FT-890 transceiver with Hamlib. Some of these are limitations of the radio while others are programming trade-offs with Hamlib.
+
+This document is organized by Hamlib function calls and documents observed behavior with each call.
+
+`rig_set_rit`
+
+* `RIG_VFO_*` value is respected so the rig VFO may be changed with this call.
+* To "zero" the RIT pass a value > 0 or < 10 with this call. The digit will be dropped as resolution is 10 Hz minimum and the clarifier offset set to 0 Hz. 
+
+### General notes
+
+As with most all Yaesu radios the radio must be polled by the application for status updates, i.e. no transceive mode in CAT. 
+
+## FT-920
+
+*From Nate Bargmann, N0NB, author of the ft920 backend.*
+
+### Quirks, known bugs, and other notes
+
+In this document I'll try to describe the behavior of the Yaesu FT-920 transceiver with Hamlib. Some of these are limitations of the radio while others are programming trade-offs with Hamlib.
+
+This document is organized by Hamlib function calls and documents observed behavior with each call.
+
+`rig_set_mode`
+
+* No matter the status of the main display, MEM or VFO, display will be set to VFO mode if `RIG_VFO_A` or `RIG_VFO_VFO` is passed.
+* If radio is in MEM or MEM TUNE state, main display mode can be changed when `RIG_VFO_MEM` or `RIG_VFO_MAIN` is passed.
+* When `RIG_VFO_CURR` is passed, the display will be set per the VFO stored by the last `rig_get_vfo` call.
+* Modes DATA USB and DATA FM cannot be set at this time (Hamlib limitation). See below.
+* My FT-920 does not support USB/LSB narrow so attempting to set a narrow passband with these modes will return an Invalid Parameter error. 
+
+`rig_get_mode`
+
+* Modes DATA USB and DATA FM cannot be returned as rig.h only has `RIG_MODE_RTTY` (Hamlib limitation).
+* DATA LSB is mapped to `RIG_MODE_RTTY`.
+* I would like to hear from anyone who gets a narrow passband value in USB/LSB mode returned. 
+
+`rig_set_freq`
+
+* When passed `RIG_VFO_A` or `RIG_VFO_VFO` the main display is forced to VFO mode and then the frequency is set.
+* When passed `RIG_VFO_B` or `RIG_VFO_SUB`, the sub display frequency is set.
+* When passed `RIG_VFO_MEM`, or `RIG_VFO_MAIN`, the main display frequency is set regardless of whether the main display is in memory (thus activating MEM Tune) or VFO mode.
+* When `RIG_VFO_CURR` is passed, the display will be set per the VFO stored by the last `rig_get_vfo` call.
+* `RIG_TARGETABLE_ALL` is properly handled (I think). 
+
+`rig_get_freq`
+
+* When passed `RIG_VFO_A` or `RIG_VFO_VFO`, the radio returns the frequency in the main VFO, even if the main display is in MEM or MEM Tune.
+* When passed `RIG_VFO_B` or `RIG_VFO_SUB`, the sub-display frequency is returned.
+* When passed `RIG_VFO_MEM` or `RIG_VFO_MAIN`, the current main display frequency is returned regardless of main display mode.
+* When passed `RIG_VFO_CURR`, the display will be read per the VFO stored by the last `rig_get_vfo call`. 
+
+`rig_set_vfo`
+
+* When called with `RIG_VFO_A` or `RIG_VFO_VFO`, the radio appears to do nothing, however, `rig_state->current_vfo` will be updated.
+* When called with `RIG_VFO_B`, the radio will swap the main and sub displays, the same as if the front panel A<>B button is pressed.
+* No provision exists to make VFO-B (sub display) the active RX through CAT. 
+
+`rig_get_split`
+
+* Both split capabilities are tested, i.e. RX A/TX B and RX B/TX A, but Hamlib only supports an indication that the radio is split.
+* The VFO value passed is not used by the ft920 backend lib. FIXME: Is this a problem? 
+
+`rig_set_split`
+
+* When called with `RIG_SPLIT_OFF` the radio will make TX A active if TX B was active, otherwise no change.
+* When called with `RIG_SPLIT_ON` the radio will make TX B active if TX A was active, otherwise no change.
+* The FT-920 has no capability to change the active RX to RX B (sub display) through CAT. Thus if VFO-B is active RX/TX the setting RIG_SPLIT_ON will make no visible change on the radio.
+* The VFO value passed is not used by the ft920 backend lib. FIXME: Is this a problem? 
+
+`rig_set_split_freq`
+
+* Backend simply wraps `rig_set_freq`--calling app needs to specify target VFO to set frequency. Should backend determine split and set "proper" VFO? 
+
+`rig_get_split_freq`
+
+* Backend simply wraps `rig_get_freq`--calling app needs to specify target VFO to set frequency. Should backend determine split and set "proper" VFO? 
+
+`rig_set_split_mode`
+
+* Backend simply wraps `rig_set_mode`--calling app needs to specify target VFO to set frequency. Should backend determine split and set "proper" VFO? 
+
+`rig_get_split_mode`
+
+* Backend simply wraps `rig_get_mode`--calling app needs to specify target VFO to set frequency. Should backend determine split and set "proper" VFO? 
+
+`rig_set_rit`
+
+* Hamlib specifies that passing 0 as the RIT frequency disables RIT. Thus there is no way to meet the spec and mimic the front panel RIT off function whilst keeping the RIT offset on the display. The Hamlib spec causes behavior analogous to shutting RIT off and then pressing the Clear button.
+* There is no direct way to set RIT offset of VFOB/SUB. However, `rig_set_vfo` can be used to swap VFO B and main, then set RIT, then call `rig_set_vfo` to swap VFO B and main. FIXME: Should backend do this automatically? 
+
+`rig_get_rit`
+
+* Backend returns clarifier offset regardless of whether RIT is on.
+* vfo is honored and stored RIT is returned. 
+
+`rig_set_xit`
+
+* Hamlib specifies that passing 0 as the XIT frequency disables XIT. Thus there is no way to meet the spec and mimic the front panel XIT off function whilst keeping the XIT offset on the display. The Hamlib spec causes behavior analogous to shutting XIT off and then pressing the Clear button.
+* There is no direct way to set XIT offset of VFOB/SUB. However, `rig_set_vfo` can be used to swap VFO B and main, then set XIT, then call `rig_set_vfo` to swap VFO B and main. FIXME: Should backend do this automatically? 
+
+`rig_get_xit`
+
+* Backend returns clarifier offset regardless of whether XIT is on.
+* vfo is honored and stored XIT is returned. 
+
+### General notes
+
+As with most all Yaesu radios the radio must be polled by the application for status updates, i.e. no transceive mode in CAT. 
+
+## Ten-Tec Orion (565) and Orion II (566)
+
+The Hamlib backend for the Orion and Orion II were provided in current form in Hamlib release 1.2.10 and later. Some earlier releases had problems with segfaults.
+
+There was a significant change between version 1.\* and 2.\* of the firmware for the original Orion. The only major effect for Hamlib use was in the S-meter calibration scale. The current backend tries to detect the firmware version and apply the correct scaling. The Orion II only supports version 2.\* and otherwise appears the same as the original Orion. All Orions are supported as Hamlib rig number 1608.
+
+Please submit all bug reports to hamlib-developer@lists.sourceforge.net.
+
+## Elektor SDR
+John, AC6SL, [reported that accessing the Elektor SDR required starting `rigctl` with `sudo`](http://article.gmane.org/gmane.linux.hams.hamlib.devel/2642). Stéphane, F8CFE, reported that,
+
+ > Now, talking about the Elektor SDR 5/07 backend, it has to be known this backend is not a regular `RIG_PORT_SERIAL` backend, but `RIG_PORT_USB`. Even though the FT232R is usb-serial compatible, the Elektor SDR use it in bitbanging mode. Therefore, the device `/dev/ttyUSB0` is not used at all."
+
+With that information in hand, Stéphane went on to suggest the following `udev` rule,
+
+> IMHO, in order to solve the permission issue without having to run programs as root, some udev magic is necessary (I'm no expert). Here's a rough guess for a `/etc/udev/rules.d/95-elektor507.rules` file.
+
+> `#`
+> `# udev rule file for FT232R (Elektor SDR-USB)`
+> `#`
+> `ACTION=="add", SUBSYSTEM=="usb", SYSFS{idVendor}=="0403", SYSFS{idProduct}=="6001", GROUP="plugdev"`
+
+> You'll need to be a member of group plugdev, log back in if just added, restart udev, and replug your device. Quick check:
+
+> `$ lsusb`
+> `Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub`
+> `Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub`
+> `Bus 003 Device 002: ID 0403:6001 Future Technology Devices International, Ltd FT232 USB-Serial (UART) IC`
+> `Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub`
+> `Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub`
+>
+> `$ ls -l /dev/bus/usb/003/002`
+> `crw-rw-r-- 1 root plugdev 189, 257 2010-08-19 22:09 /dev/bus/usb/003/002`
+
+John followed up with,
+
+>    > Here's a rough guess for a
+>    > `/etc/udev/rules.d/95-elektor507.rules` file....
+
+> Yes, creating the .rules file and replugging the device allows rigctl to operate the Elektor SDR without "sudo".
+
+So, it would appear that some udev configuration is required to provide user access to non-standard USB devices, i.e. those beyond the "standard" serial or parallel adapters supported by your distribution.
+
+* 9/16/2010, Nate Bargmann, N0NB 
+
+## Si570 AVR-USB, aka SoftRock
+
+Pretty much like the Elektor SDR, the Si570 AVR-USB requires special priviledges for regular users to access the USB device under Linux. This is generally taken care of by the libhamlib package of your Linux distribution. Should it be missing, here is an example of a `/etc/udev/rules.d/95-si570avrusb.rules` file.
+
+    #
+    # VOTI USBasp AVR Programmer
+    #
+    ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="16c0", ATTR{idProduct}=="05dc", ENV{ACL_MANAGE}="1"
+
+* 10/12/2010, Stéphane Fillod, F8CFE 
+
+## FUNcube dongle
+
+Using the FUNcube dongle with Hamlib under a Windows system requires some libusb-win32 setup as described in the file [`README.funcubedongle`](http://hamlib.git.sourceforge.net/git/gitweb.cgi?p=hamlib/hamlib;a=blob_plain;f=kit/README.funcubedongle;hb=HEAD).