Update documentation for Hamlib 4.x release

[mikaelnousiainen]

Could you update documentation -- mainly header files and man pages -- for at least the following major things that have changed in Hamlib 4.x:

• set_ant / get_ant function prototypes and man page documentation -- In order to understand how the new parameters (option / antenna), it would be great to have a bit more specific documentation (more text). Additionally rigctld man page doesn't match rigctl man page here. I could even try to update it myself, but even I don't understand how these new parameters should work and what the results should be. A practical example would be very much appreciated.

• set_channel / get_channel function prototypes and man page documentation -- Currently, it says "not implemented" here. What is the meaning of the new read_only flag?

• Document any other possible major API changes that I've missed here.

I can also help with the documentation once I understand what the API changes are for and what the intended functionality should be.

[N0NB]

Hi Mikael.

I have some edits pending on the present man pages. Let me finish them and push them out and then you can jump in.

As for the API changes I think Mike, W9MDB, is the best resource for that information.

As for the roff source, I am trying to follow the man pages project guidelines as much as possible. See man(7) and man-pages(7) as primary guides. Supplemental guides are groff_man(7) and groff_man_style(7).

[N0NB]

I have pushed my changes out. Jump in, Mikael!

[mikaelnousiainen]

Thanks a lot.

@mdblack98 If you could give me some pointers on what intended functionality on the API changes really is, I can proceed to update the docs soon.

[mdblack98]

That change was prompted by the IC-7851.  Haven't noticed any other rigs doing it yet.It's just called a generic "option" as 99% of rigs don't use it.Future Icom's (and other manufacturers) may have this additional option for doing things with the antenna connectors.The rigctl.1 man page gives a cursory overview which I just updated a bit.  May need more explanation.When Icom makes another rig with this capability and shows consistency will make some constants for the option.Something likeenum ant_options {    RIG_ANT_OPTION_OFF = 0x00,    RIG_ANT_OPTION_RXONLY = 0x01 }; Mike W9MDB On Friday, September 11, 2020, 01:17:30 AM CDT, Mikael Nousiainen <notifications@github.com> wrote: Thanks a lot. @mdblack98 If you could give me some pointers on what intended functionality on the API changes really is, I can proceed to update the docs soon. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[mikaelnousiainen]

@mdblack98 Ok, thanks! I still have some follow-up questions, however 👍

1. So just that I understand this correctly, would the RX ant option work like this:

• \set_ant 3 0 -> Will select antenna 3 as both TX and RX antenna
• \set_ant 2 1 -> Will select antenna 2 as RX antenna, but keep 3 as TX
• \set_ant 1 0 -> Will select antenna 1 as both TX and RX antenna, overriding previous RX antenna
• \set_ant 4 1 -> Will select antenna 4 as RX antenna and now keep 1 as TX antenna?

2. Also, could you also give me a short description on the read_only flag on \get_channel ? Do some rigs change state when getting channel info?

[mdblack98]

This may well change in the future...that's why it says it's rig dependent.For the IC7851 here are the meanings.We don't have any standard API for this yet as there's only 1 rig that does it.I can imagine set_ant_split(rig, ant_tx, ant_rx) as a standard API.  The "option" would still be available as another method. - \set_ant 3 0 -> Will set antenna 3 as both TX and RX antenna - \set_ant 2 1 -> Will set antenna 2 as RX antenna, but keep 3 as TX - \set_ant 1 0 -> Will set antenna 1 as both TX and RX antenna, overriding previous RX antenna - \set_ant 4 1 -> Will set antenna 4 as RX antenna and now keep 1 as TX antenna? The read_only flag is to prevent the command from writing the channel info to the active settings.  If read_only=0 then the rig will be set to the channel being read. Mike W9MDB On Sunday, September 13, 2020, 12:26:51 AM CDT, Mikael Nousiainen <notifications@github.com> wrote: @mdblack98 Ok, thanks! I still have some follow-up questions, however 👍 - So just that I understand this correctly, would the RX ant option work like this: - \set_ant 3 0 -> Will select antenna 3 as both TX and RX antenna - \set_ant 2 1 -> Will select antenna 2 as RX antenna, but keep 3 as TX - \set_ant 1 0 -> Will select antenna 1 as both TX and RX antenna, overriding previous RX antenna - \set_ant 4 1 -> Will select antenna 4 as RX antenna and now keep 1 as TX antenna? - Also, could you also give me a short description on the read_only flag on \get_channel ? Do some rigs change state when getting channel info? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[mikaelnousiainen]

Ok, now that 4.0 has not been released yet, I'm wondering if -- instead of adding a parameter to \set_ant and breaking existing applications -- we should add a new command altogether: \set_rx_ant / \get_rx_ant or similar? That would allow the current set_ant functionality to stay as it is and we could experiment with a new command.

Thoughts?

[mdblack98]

Since it all fits under the set_ant paradigm adding more functions and more commands to rigctl isn't desirable.That's why 4.0 bumped the major release# as there are a few API changes. Mike W9MDB On Monday, September 14, 2020, 01:44:48 AM CDT, Mikael Nousiainen <notifications@github.com> wrote: Ok, now that 4.0 has not been released yet, I'm wondering if -- instead of adding a parameter to \set_ant and breaking existing applications -- we should add a new command altogether: \set_rx_ant / \get_rx_ant or similar? That would allow the current set_ant functionality to stay as it is and we could experiment with a new command. Thoughts? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.