[Hamlib-developer] API completion

[Stephane F. <f4...@fr...>]

Here is a (long) list of pending issues I try to work out, if we want to see
the Hamlib API complete one day.
Let me know if you agree or disagree on the ideas, on the implementation,
etc. Part of it is already coded. However it's not written in stone though.
If you think the API names are not well chosen, you might be right!
Give a better name in that case, english is not my mother tongue!

Duplex and split operation:
---------------------------

Until now, we have *duplex* support with the following enum:

enum rptr_shift_e {
        RIG_RPT_SHIFT_NONE = 0,
        RIG_RPT_SHIFT_MINUS,
        RIG_RPT_SHIFT_PLUS
	}

Adding the following two capabilities, we can set the duplex offset,
thus the duplex support is complete.

  int (*set_rpt_offs)(RIG *rig, freq_t offs); /* set duplex offset freq */
  int (*get_rpt_offs)(RIG *rig, freq_t *offs); /* get duplex offset freq */

Do you see anything else needed?


Well, now let's talk about *split* support.
On most radios (all ?), the split mode is implemented using 2 VFOs.
ie. VFO A holds the receive frequency while VFO B holds the transmit freq.

enum split_e {
		RIG_SPLIT_OFF = 0,
		RIG_SPLIT_ON
		};
int (*set_split_freq)(RIG *rig, freq_t rx_freq, freq_t tx_freq);
int (*get_split_freq)(RIG *rig, freq_t *rx_freq, freq_t *tx_freq);
int (*set_split)(RIG *rig, split_t split);
int (*get_split)(RIG *rig, split_t *split);

set_split_freq would set VFO A and VFO B accordingly, or whatever else
the rig is using. Breaking set_split_freq down in set_split_rxfreq and
set_split_txfreq would have been better, but hey, being smart
has a cost!
Concerning set_split(), we could have reuse set_rpt_shift(), but the
name could be misleading.

What do you think of this proposal? Can I check it in?


Clarification on enum vfo_e
---------------------------

Ok, the enum vfo_e is kind of over crowded, I'm not sure
of what is what:

    RIG_VFO_MAIN = 0,
    RIG_VFO_RX,
    RIG_VFO_TX,
    RIG_VFO_SUB,
    RIG_VFO_SAT_RX,
    RIG_VFO_SAT_TX,
    RIG_VFO_A,
    RIG_VFO_B,
    RIG_VFO_C

RIG_VFO_A,RIG_VFO_B and RIG_VFO_C are fine :)
Is RIG_VFO_MAIN an alias for RIG_VFO_A and RIG_VFO_SUB for RIG_VFO_B?
Allright, now, what I don't understand is how we can have (from an
operating point of vue of course) a VFO for RX and another one for TX.
To my mind, they would be the same VFO, but if you want RX freq different
than TX freq, then you activate split mode.
So my proposal would be:

{   RIG_VFO_MAIN = 0,
    RIG_VFO_SUB,
    RIG_VFO_SAT,
    RIG_VFO_A = RIG_VFO_MAIN,
    RIG_VFO_B = RIG_VFO_SUB,
    RIG_VFO_C = RIG_VFO_SAT
}

Is it OK with you?

rmode_t
-------
Luc is right, we have to rework this type. WE should remove all the wide
and narrow combinations, in order to keep it simple.
Then, we can add some rig_set_filter() that would support, not only
"builtin" narrow and wide filter, but also added filters (ie. can have
more that one narrow filter installed).
 
Misc functions
--------------
  int (*set_ant)(RIG *rig, int ant); /* set antenna number */
  int (*get_ant)(RIG *rig, int *ant); /* get antenna */

  int (*set_att)(RIG *rig, int att); /* set attenuator, in db */
  int (*get_att)(RIG *rig, int *att); /* set attenuator, in db */

and preamp as well? any proposal?
We'll need to support filters too. Can you see a generic approach on this?


Memory:
------

  int rig_set_mem(RIG *rig, int ch);
  int rig_get_mem(RIG *rig, int *ch);
  int rig_mem_clear(RIG *rig);
  int rig_mem_to_vfo(RIG *rig);
  int rig_vfo_to_mem(RIG *rig);  /* memory write */

  We need also VFO A=B, Switch VFO A and B, set to VFO mode, set to MEM mode

  int rig_vfo_copy(RIG *rig);
  int rig_vfo_xchg(RIG *rig);
  int rig_vfo_mode(RIG *rig);
  int rig_mem_mode(RIG *rig);

OR

  int rig_vfo_mem(RIG *rig, vfo_mem_t op);

where op can have the following values:
	* RIG_VM_VFOAB
	* RIG_VM_VFO_XCHG
	* RIG_VM_VFO_MODE
	* RIG_VM_MEM_MODE
	etc.
we could even have:
	* RIG_VM_MCL
	* RIG_VM_MEM2VFO
	* RIG_VM_VFO2MEM

This would cut down the number of functions in the API.
What do you think ? What about the names?



about freq range:
----------------
	Just something to keep in mind. Some rigs, with the same model number,
	are manufactured for ITU region 1 and ITU region 2.
	So what's the matter? Well the frequency ranges vary from one region
	to another one. This will be a great handicap for the capabilities.
	Keep thinking of it, how we could solve this problem...
	and let me know!

Scan functions:
--------------
	rig_scan(my_rig, RIG_SCAN_START);
	rig_scan(my_rig, RIG_SCAN_STOP);

Is that enough? Do we need more control?


About sql:
---------
We need 3 functions:

	set squelch level:  0.0 .. 1.0
	get squelch level-> 0.0 .. 1.0
	read squelch status: open/closed

misc:
----
A function to get firmware string, ITU region, trx ID, etc.
someting that can be displayed in an 'About ...' GUI popup window.


level settings:
---------------

Ah! The big chunk. Idealy, we would have to be able to set/adjust
all the following settings:

   AF level setting				rig_[sg]et_volume
   RF level setting
   SQL level setting			rig_[sg]et_squelch
   IF shift setting
   APF level setting
   NR level setting
   Twin PBT setting (inside)
   Twin PBT setting (outside)
   CW pitch setting
   sets RF power				rig_[sg]et_power
   sets MIC Gain
   sets Key Speed
   sets Notch Freq.
   sets Compressor level
   sets BKin Delay
   sets Balance (Dual Watch)
   Preamp Setting
   AGC setting: off, super-fast, fast, slow
   NB ON/OFF
   APF ON/OFF
   Set (optional) noise reduction off/on
   Set (optional) auto notch off/on
   Repeater tone setting
   TSQL setting
   Monitor setting
   VOX setting
   BKin setting
   Manual Notch
   RTTY Filter Notch
   Signal centered


For all the ON/OFF settings, what do you think of using the rig_set_func()
call that would take care of it? And what about the rest? One set/get
function per paramter or something more generic like this:

	rig_set_setting(RIG *rig, setting_t setting, int value);
	rig_get_setting(RIG *rig, setting_t setting, int *value);

Needless to say, that could be a mess if the setting is not an integer
but a float or a string, etc.
I'm waiting for your thoughts on this.


Let's complete the API (or at least close to it) so we can release it,
after we've documented it....

Thanks for reading :-)
-- 
Stephane							F4CFE