hamlib-developer

[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

Re: [Hamlib-developer] API completion

[Frank S. <vk...@ix...>]

Hi,

See my comments (***) below.

/Frank..


Stephane Fillod wrote:
> 
> 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?
> 

***

Reverse to listen for example repeater input frequencies.
Is this just a toggle of the current (ie: remember state) RIG_RPT_SHIFT
?
If so, then is this backend "instance data"

> 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
> ---------------------------

> 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?


***

Really we are simply aliasing "n" VFO's to something tangibile
for humans to understand. This is OK with me.

> 
> 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).
> 


***
Yes, a rationalising of modes is good.

ie: mode and bandwidth are different settings on our virtual radio model
(aka API)

also, bandwidth applies to RF frontend, IF, AF and offrig DSP bandwidth.
eg: IF filtering, AF filtering, Off rig filtering + squelch (DSP on
computer)


ie: location(s) and response(s)


location:
---------
enum filter_path_e { 
	RIG_BW_RF = 0,
  	RIG_BW_IF,
  	RIG_BW_AF,
  	RIG_BW_RF_EXTERNAL,
	RIG_BW_IF_EXTERNAL,
	RIG_BW_AF_EXTERNAL,
}

typedef filter_path_e filter_path_t



response
---------
Also, bandwidth may be too restrictive

should not we model it as 
types like bandpass, band reject  high pass, low pass, etc

enum filter_resp { 
  	RIG_FILTER_BPASS,
  	RIG_FILTER_BREJECT,
  	RIG_FILTER_HPF,
  	RIG_FILTER_LPF,
   ..etc
}


or 

enum filter_width { 
  	RIG_FILTER_NARROW,
  	RIG_FILTER_NORMAL,
  	RIG_FILTER_WIDE
   ..etc
}

typedef filter_width_e filter_width_t

These above generally equate to buttons on the rig.

However we may need a general filter decription for that done
at IF and AF etc.. especially when DSP is involved.

I am not (yet) saying 15 pole chebyshev with such and such
charactersitics.  It would be nice to pass a bode plot
to the rig (one day !!). But we do need to set cutoff frequencies
etc. eg: 3db cutoff for BPF, HPF,LPF, etc.. if the rig can handle
it.



An API suggestion would be 

rig_set_filter(RIG *rig, filter_path_t fp, freq_resp_t fres)


Note also thet BPF can be modelled as HPF/LPF combo 
or as BPF with center freq and BW etc..

PSk users prefers centre freq and BW, whereas removing lowend crud
is a LPF for example.

hmmm... geeting late so I move on :-)


> 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?




I see a couple of things here.

1. Rig onboard scanning capability
2. Backend soft scanning, and asynchronous handling
   of "stop scanning" requests etc..
3. Frontend soft scanning requests.


> 
> 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


Offrig squelch , tone detection (DSP on PC) ??

> 
> 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:
> ---------------


> 
> 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);
> 

***

This is prefereable, otherwise my 300 button rig is going to create
a lots of API functions.

> 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.


***
It seems to me that the API models a virtual Radio with particular
capability ranges
for each setting.

I think we should standardise up front the acceptable range settings for
the virtual radio and let the backend take care of necessary scaling.
I expect that most level settings can be implemented via "int" quite
acceptably. 

> 
> 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
> _______________________________________________
> Hamlib-developer mailing list
> Ham...@li...
> http://lists.sourceforge.net/mailman/listinfo/hamlib-developer



Cheers / Frank..


-- 
Frank Singleton				VK3FCS

Email: victor kilo three foxtrot charlie sierra at ix dot netcom dot com

Re: [Hamlib-developer] API completion

[Frank S. <vk...@ix...>]

Frank Singleton wrote:

> 
> PSk users prefers centre freq and BW, whereas removing lowend crud
> is a LPF for example.


Oops, removing lowend crud is using a HPF function :-)


-- 
Frank Singleton				VK3FCS

Email: victor kilo three foxtrot charlie sierra at ix dot netcom dot com