mirror
/
Hamlib
kopia lustrzana https://github.com/Hamlib/Hamlib
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Update Docygen comments in rotator.c 

Create new group for rot_internal that Doxygen shows under the Modules
tab.
pull/548/head
Nate Bargmann 2021-02-15 15:36:47 -06:00
rodzic e016025c04
commit 9dce43fc50
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: F72625E2EDBED598
2 zmienionych plików z 167 dodań i 95 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

5
doc/index.doxygen
Wyświetl plik

@ -102,8 +102,9 @@ Windows 32 bit on Debian GNU/Linux.
/*! Define groups for Doxygen /*! Define groups for Doxygen
* \defgroup rig Rig (transceiver) API * \defgroup rig Rig (transceiver) API
* \defgroup rig_internal Rig (transceiver) Internal API
* \defgroup rotator Rotator API * \defgroup rotator Rotator API
* \defgroup utilities Utility Routines API * \defgroup rot_internal Rotator Internal API
* \defgroup rig_internal Rig Internal API
* \defgroup amplifier Amplifier API * \defgroup amplifier Amplifier API
* \defgroup utilities Utility Routines API
*/ */

257
src/rotator.c
Wyświetl plik

@ -28,18 +28,22 @@
/** /**
* \file src/rotator.c * \file src/rotator.c
* \brief Rotator interface * \brief Rotator interface
* \author Frank Singleton
* \date 2000-2003
* \author Stephane Fillod * \author Stephane Fillod
* \date 2000-2012 * \date 2000-2012
* *
* Hamlib interface is a frontend implementing rotator wrapper functions. * This Hamlib interface is a frontend implementing the rotator wrapper
* functions.
*/ */
/** /**
* \page rot Rotator interface * \page rot Rotator interface
* *
* Rotator can be any kind of azimuth or azimuth and elevation controlled * A rotator can be any kind of azimuth, elevation, or azimuth and elevation
* antenna system. * controlled antenna system or other such aiming equipment, e.g. telescopes,
* etc.
*/ */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
@ -147,22 +151,30 @@ static int remove_opened_rot(ROT *rot)
} }
#endif /* !DOC_HIDDEN */ #endif /* !DOC_HIDDEN */
/** @} */ /* rotator definitions */
/** /**
* \brief execs cfunc() on each opened rot * \addtogroup rot_internal
* \param cfunc The function to be executed on each rot * @{
* \param data Data pointer to be passed to cfunc() */
/**
* \brief Executes \a cfunc on each opened #ROT.
* *
* Calls cfunc() function for each opened rot. The contents of the opened * \param cfunc The function to be executed on each #ROT.
* rot table is processed in random order according to a function pointed to * \param data Data pointer to be passed to \a cfunc.
* by \a cfunc, which is called with two arguments, the first pointing to the
* #ROT handle, the second to a data pointer \a data.
* *
* If \a data is not needed, then it can be set to NULL. The processing of * Calls \a cfunc function for each opened #ROT. The contents of the opened
* the opened rot table is stopped when cfunc() returns 0. * #ROT table is processed in random order according to a function pointed to
* \internal * by \a cfunc, which is called with two arguments, the first pointing to the
* #ROT handle, the second to a data pointer \a data.
* *
* \return always RIG_OK. * If \a data is not needed, then it can be set to NULL. The processing of
* the opened #ROT table is stopped when \a cfunc returns 0.
*
* \return RIG_OK in all cases.
*/ */
int foreach_opened_rot(int (*cfunc)(ROT *, rig_ptr_t), rig_ptr_t data) int foreach_opened_rot(int (*cfunc)(ROT *, rig_ptr_t), rig_ptr_t data)
{ {
@ -180,17 +192,24 @@ int foreach_opened_rot(int (*cfunc)(ROT *, rig_ptr_t), rig_ptr_t data)
return RIG_OK; return RIG_OK;
} }
/** @} */ /* rot_internal definitions */
/** /**
* \brief allocate a new #ROT handle * \addtogroup rotator
* \param rot_model The rot model for this new handle * @{
*/
/**
* \brief Allocate a new #ROT handle.
*
* \param rot_model The rotator model for this new handle.
* *
* Allocates a new #ROT handle and initializes the associated data * Allocates a new #ROT handle and initializes the associated data
* for \a rot_model. * for \a rot_model (see rotlist.h or `rigctl -l`).
* *
* \return a pointer to the #ROT handle otherwise NULL if memory allocation * \return a pointer to the #ROT handle otherwise NULL if memory allocation
* failed or \a rot_model is unknown (e.g. backend autoload failed). * failed or \a rot_model is unknown, e.g. backend autoload failed.
* *
* \sa rot_cleanup(), rot_open() * \sa rot_cleanup(), rot_open()
*/ */
@ -313,18 +332,19 @@ ROT *HAMLIB_API rot_init(rot_model_t rot_model)
/** /**
* \brief open the communication to the rot * \brief Open the communication channel to the rotator.
* \param rot The #ROT handle of the rotator to be opened
* *
* Opens communication to a rotator which \a ROT handle has been passed * \param rot The #ROT handle of the rotator to be opened.
* by argument.
* *
* \return RIG_OK if the operation has been successful, otherwise * Opens the communication channel to a rotator for which the #ROT handle has
* a negative value if an error occurred (in which case, cause is * been passed.
* set appropriately).
* *
* \retval RIG_EINVAL \a rot is NULL or inconsistent. * \return RIG_OK if the operation has been successful, otherwise a **negative
* \retval RIG_ENIMPL port type communication is not implemented yet. * value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK Communication channel succesfully opened.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* \retval RIG_ENIMPL Communication port type is not implemented yet.
* *
* \sa rot_init(), rot_close() * \sa rot_init(), rot_close()
*/ */
@ -448,15 +468,17 @@ int HAMLIB_API rot_open(ROT *rot)
/** /**
* \brief close the communication to the rot * \brief Close the communication channel to the rotator.
* \param rot The #ROT handle of the rotator to be closed * \param rot The #ROT handle of the rotator to be closed.
* *
* Closes communication to a rotator which \a ROT handle has been passed * Closes the communication channel to a rotator for which #ROT handle has
* by argument that was previously open with rot_open(). * been passed by argument that was previously opened with rot_open().
* *
* \return RIG_OK if the operation has been successful, otherwise * \return RIG_OK if the operation has been successful, otherwise a **negative
* a negative value if an error occurred (in which case, cause is * value** if an error occurred (in which case, cause is set appropriately).
* set appropriately). *
* \retval RIG_OK Communication channel successfully closed.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* *
* \sa rot_cleanup(), rot_open() * \sa rot_cleanup(), rot_open()
*/ */
@ -527,15 +549,18 @@ int HAMLIB_API rot_close(ROT *rot)
/** /**
* \brief release a rot handle and free associated memory * \brief Release a #ROT handle and free associated memory.
* \param rot The #ROT handle of the radio to be closed
* *
* Releases a rot struct which port has eventually been closed already * \param rot The #ROT handle to be released.
*
* Releases a #ROT handle for which the communication channel has been closed
* with rot_close(). * with rot_close().
* *
* \return RIG_OK if the operation has been successful, otherwise * \return RIG_OK if the operation has been successful, otherwise a **negative
* a negative value if an error occurred (in which case, cause is * value** if an error occurred (in which case, cause is set appropriately).
* set appropriately). *
* \retval RIG_OK #ROT handle successfully released.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* *
* \sa rot_init(), rot_close() * \sa rot_init(), rot_close()
*/ */
@ -571,16 +596,25 @@ int HAMLIB_API rot_cleanup(ROT *rot)
/** /**
* \brief set the azimuth and elevation of the rotator * \brief Set the azimuth and elevation of the rotator.
* \param rot The rot handle *
* \param azimuth The azimuth to set to * \param rot The #ROT handle.
* \param elevation The elevation to set to * \param azimuth The azimuth to set in decimal degress.
* \param elevation The elevation to set in decimal degrees.
* *
* Sets the azimuth and elevation of the rotator. * Sets the azimuth and elevation of the rotator.
* *
* \return RIG_OK if the operation has been successful, otherwise * \b Note: A given rotator may be capable of setting only the azimuth or
* a negative value if an error occurred (in which case, cause is * only the elevation or both. The rotator backend will ignore the unneeded
* set appropriately). * parameter.
*
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK Either or both parameters set successfully.
* \retval RIG_EINVAL \a rot is NULL or inconsistent \b or either \a azimuth
* or \a elevation is out of range for this rotator.
* \retval RIG_ENAVAIL rot_caps#set_position() capability is not available.
* *
* \sa rot_get_position() * \sa rot_get_position()
*/ */
@ -634,16 +668,25 @@ int HAMLIB_API rot_set_position(ROT *rot,
/** /**
* \brief get the azimuth and elevation of the rotator * \brief Query the azimuth and elevation of the rotator.
* \param rot The rot handle
* \param azimuth The location where to store the current azimuth
* \param elevation The location where to store the current elevation
* *
* Retrieves the current azimuth and elevation of the rotator. * \param rot The #ROT handle.
* \param azimuth The variable to store the current azimuth.
* \param elevation The variable to store the current elevation
* *
* \return RIG_OK if the operation has been successful, otherwise * Retrieves the current azimuth and elevation values of the rotator. The
* a negative value if an error occurred (in which case, cause is * stored values are in decimal degrees.
* set appropriately). *
* \b Note: A given rotator may be capable of querying only the azimuth or
* only the elevation or both. The rotator backend should store a value of 0
* in the unsupported variable.
*
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK Either or both parameters queried and stored successfully.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* \retval RIG_ENAVAIL rot_caps#get_position() capability is not available.
* *
* \sa rot_set_position() * \sa rot_set_position()
*/ */
@ -692,14 +735,19 @@ int HAMLIB_API rot_get_position(ROT *rot,
/** /**
* \brief park the antenna * \brief Park the rotator.
* \param rot The rot handle
* *
* Park the antenna. * \param rot The #ROT handle.
* *
* \return RIG_OK if the operation has been successful, otherwise * Park the rotator in a predetermined position as implemented by the rotator
* a negative value if an error occurred (in which case, cause is * hardware.
* set appropriately). *
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The rotator was parked successfully.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* \retval RIG_ENAVAIL rot_caps#park() capability is not available.
* *
*/ */
int HAMLIB_API rot_park(ROT *rot) int HAMLIB_API rot_park(ROT *rot)
@ -725,15 +773,20 @@ int HAMLIB_API rot_park(ROT *rot)
/** /**
* \brief stop the rotator * \brief Stop the rotator.
* \param rot The rot handle
* *
* Stop the rotator. * \param rot The #ROT handle.
* *
* \return RIG_OK if the operation has been successful, otherwise * Stop the rotator. Command should be immediate.
* a negative value if an error occurred (in which case, cause is
* set appropriately).
* *
* \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The rotator was stopped successfully.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* \retval RIG_ENAVAIL rot_caps#stop() capability is not available.
*
* \sa rot_move()
*/ */
int HAMLIB_API rot_stop(ROT *rot) int HAMLIB_API rot_stop(ROT *rot)
{ {
@ -758,16 +811,19 @@ int HAMLIB_API rot_stop(ROT *rot)
/** /**
* \brief reset the rotator * \brief Reset the rotator.
* \param rot The rot handle *
* \param rot The #ROT handle.
* \param reset The reset operation to perform * \param reset The reset operation to perform
* *
* Resets the rotator. * Resets the rotator to a state determined by \a reset.
* *
* \return RIG_OK if the operation has been successful, otherwise * \return RIG_OK if the operation has been successful, otherwise a **negative
* a negative value if an error occurred (in which case, cause is * value** if an error occurred (in which case, cause is set appropriately).
* set appropriately).
* *
* \retval RIG_OK The rotator was reset successfully.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* \retval RIG_ENAVAIL rot_caps#reset() capability is not available.
*/ */
int HAMLIB_API rot_reset(ROT *rot, rot_reset_t reset) int HAMLIB_API rot_reset(ROT *rot, rot_reset_t reset)
{ {
@ -792,13 +848,22 @@ int HAMLIB_API rot_reset(ROT *rot, rot_reset_t reset)
/** /**
* \brief move the rotator in the specified direction * \brief Move the rotator in the specified direction and speed.
* \param rot The rot handle
* \param direction Direction of movement
* \param speed Speed of movement
* *
* Move the rotator in the specified direction. The speed is a value * \param rot The #ROT handle.
* between 1 and 100. * \param direction Direction of movement.
* \param speed Speed of movement.
*
* Move the rotator in the specified direction. The \a direction is one of
* #ROT_MOVE_CCW, #ROT_MOVE_CW, #ROT_MOVE_LEFT, #ROT_MOVE_RIGHT, #ROT_MOVE_UP,
* or #ROT_MOVE_DOWN. The \a speed is a value between 1 and 100 or
* #ROT_SPEED_NOCHANGE.
*
* \retval RIG_OK The rotator move was successful.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* \retval RIG_ENAVAIL rot_caps#move() capability is not available.
*
* \sa rot_stop()
*/ */
int HAMLIB_API rot_move(ROT *rot, int direction, int speed) int HAMLIB_API rot_move(ROT *rot, int direction, int speed)
{ {
@ -823,15 +888,17 @@ int HAMLIB_API rot_move(ROT *rot, int direction, int speed)
/** /**
* \brief get general information from the rotator * \brief Get general information from the rotator.
* \param rot The rot handle
* *
* Retrieves some general information from the rotator. * \param rot The #ROT handle.
* This can include firmware revision, exact model name, or just nothing.
* *
* \return a pointer to static memory containing the ASCIIZ string * Retrieves some general information from the rotator. This can include
* if the operation has been successful, otherwise NULL if an error occurred * firmware revision, exact model name, or just nothing.
* or get_info not part of capabilities. *
* \return A pointer to static memory containing an ASCII nul terminated
* string (C string) if the operation has been successful, otherwise NULL if
* \a rot is NULL or inconsisten or the rot_caps#get_info() capability is not
* available.
*/ */
const char *HAMLIB_API rot_get_info(ROT *rot) const char *HAMLIB_API rot_get_info(ROT *rot)
{ {
@ -852,15 +919,19 @@ const char *HAMLIB_API rot_get_info(ROT *rot)
/** /**
* \brief get status flags from the rotator * \brief Query status flags of the rotator.
* \param rot The rot handle
* \param status a pointer to a rot_status_t variable that will receive the status flags
* *
* Gets the active status flags from the rotator. * \param rot The #ROT handle.
* \param status The variable where the status flags will be stored.
* *
* \return RIG_OK if the operation has been successful, otherwise * Query the active status flags from the rotator.
* a negative value if an error occurred (in which case, cause is *
* set appropriately). * \return RIG_OK if the operation has been successful, otherwise a **negative
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK The query was successful.
* \retval RIG_EINVAL \a rot is NULL or inconsistent.
* \retval RIG_ENAVAIL rot_caps#get_status() capability is not available.
*/ */
int HAMLIB_API rot_get_status(ROT *rot, rot_status_t *status) int HAMLIB_API rot_get_status(ROT *rot, rot_status_t *status)
{ {