diff --git a/doc/hamlib.cfg.in b/doc/hamlib.cfg.in index 5e9b54d2d..746d02bab 100644 --- a/doc/hamlib.cfg.in +++ b/doc/hamlib.cfg.in @@ -22,7 +22,8 @@ INPUT = @top_srcdir@/doc/index.doxygen \ @top_srcdir@/src/ EXCLUDE = @top_srcdir@/src/amp_conf.h \ - @top_srcdir@/include/hamlib/ampclass.h + @top_srcdir@/include/hamlib/ampclass.h \ + @top_srcdir@/include/hamlib/rotclass.h INCLUDE_PATH = @top_srcdir@/include diff --git a/include/hamlib/amplifier.h b/include/hamlib/amplifier.h index 2222ea16c..8972e55dc 100644 --- a/include/hamlib/amplifier.h +++ b/include/hamlib/amplifier.h @@ -31,13 +31,13 @@ */ /** - * \file amplifier.h - * \brief Hamlib amplifier data structures. + * \file amplifier.h + * \brief Hamlib amplifier data structures. * - * This file contains the data structures and declarations for the Hamlib - * amplifier Application Programming Interface (API). + * This file contains the data structures and declarations for the Hamlib + * amplifier Application Programming Interface (API). * - * See the `amplifier.c` file for details on the amplifier API functions. + * See the amplifier.c file for details on the amplifier API functions. */ @@ -51,47 +51,47 @@ struct amp_state; /** - * \typedef typedef struct amp AMP - * \brief Main amplifier handle type definition. + * \typedef typedef struct amp AMP + * \brief Main amplifier handle type definition. * - * The AMP handle is returned by amp_init() and is passed as a parameter to - * every amplifier specific API call. + * The #AMP handle is returned by amp_init() and is passed as a parameter to + * every amplifier specific API call. * - * amp_cleanup() must be called when this handle is no longer needed. + * amp_cleanup() must be called when this handle is no longer needed. */ typedef struct amp AMP; /** - * \typedef typedef float swr_t - * \brief Type definition for - * SWR (Standing Wave Ratio). + * \typedef typedef float swr_t + * \brief Type definition for + * SWR (Standing Wave Ratio). * - * The \c swr_t type is used as a parameter for the amp_get_swr() function. + * The \a swr_t type is used as a parameter for the amp_get_swr() function. * - * The unit of \c swr_t is 1.0 to the maximum value reported by the amplifier's - * internal antenna system tuner, i.e. - * transmatch, - * representing the ratio of 1.0:1 to Maximum:1. + * The unit of \a swr_t is 1.0 to the maximum value reported by the amplifier's + * internal antenna system tuner, i.e. + * transmatch, + * representing the ratio of 1.0:1 to Maximum:1. */ typedef float swr_t; /** - * \typedef typedef float tune_value_t - * \brief Type definition for the - * transmatch - * tuning values of - * capacitance - * and - * inductance. + * \typedef typedef float tune_value_t + * \brief Type definition for the + * transmatch + * tuning values of + * capacitance + * and + * inductance. * - * The \c tune_value_t type is used as a parameter for amp_get_level(). + * The \a tune_value_t type is used as a parameter for amp_get_level(). * - * The unit of \c tune_value_t is - * picoFarads (pF) - * or - * nanoHenrys (nH). + * The unit of \a tune_value_t is + * picoFarads (pF) + * or + * nanoHenrys (nH). */ typedef int tune_value_t; @@ -168,23 +168,23 @@ enum amp_level_e * * The main idea of this struct is that it will be defined by the backend * amplifier driver and will remain read-only for the application. Fields - * that need to be modifiable by the application are copied into the struct - * \c amp_state, which is the private memory area of the AMP instance. + * that need to be modifiable by the application are copied into the + * amp_state structure, which is the private memory area of the #AMP instance. * * This way you can have several amplifiers running within the same - * application, sharing the struct \c amp_caps of the backend, while keeping + * application, sharing the amp_caps structure of the backend, while keeping * their own customized data. * * \b Note: Don't move fields around and only add new fields at the end of the - * caps structure. Shared libraries depend on a constant structure to maintain - * compatibility. + * amp_caps structure. Shared libraries and DLLs depend on a constant + * structure to maintain compatibility. */ struct amp_caps { - amp_model_t amp_model; /*!< Amplifier model as defined in `amplist.h`. */ + amp_model_t amp_model; /*!< Amplifier model as defined in amplist.h. */ const char *model_name; /*!< Model name, e.g. MM-5k. */ const char *mfg_name; /*!< Manufacturer, e.g. Moonbeam. */ - const char *version; /*!< Driver version. */ + const char *version; /*!< Driver version, typically in YYYYMMDD.x format. */ const char *copyright; /*!< Copyright info (should be LGPL). */ enum rig_status_e status; /*!< Driver status. */ @@ -207,42 +207,42 @@ struct amp_caps const rig_ptr_t priv; /*!< Private data. */ const char *amp_model_macro_name; /*!< Model macro name. */ - setting_t has_get_level; /*!< Has get_level capability. */ - setting_t has_set_level; /*!< Has set_level capability. */ + setting_t has_get_level; /*!< List of get levels. */ + setting_t has_set_level; /*!< List of set levels. */ - gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity */ - gran_t parm_gran[RIG_SETTING_MAX]; /*!< level granularity */ + gran_t level_gran[RIG_SETTING_MAX]; /*!< Level granularity. */ + gran_t parm_gran[RIG_SETTING_MAX]; /*!< Parameter granularity. */ /* * Amp Admin API * */ - int (*amp_init)(AMP *amp); /*!< Initializes data structures and returns an #AMP handle--call before amp_open(). */ - int (*amp_cleanup)(AMP *amp); /*!< Frees the data structures associated with the #AMP handle--call after amp_close(). */ - int (*amp_open)(AMP *amp); /*!< Opens the communication channel to the amplifier. */ - int (*amp_close)(AMP *amp); /*!< Closes the communication channel to the amplifier. */ + int (*amp_init)(AMP *amp); /*!< Pointer to backend implementation of ::amp_init(). */ + int (*amp_cleanup)(AMP *amp); /*!< Pointer to backend implementation of ::amp_cleanup(). */ + int (*amp_open)(AMP *amp); /*!< Pointer to backend implementation of ::amp_open(). */ + int (*amp_close)(AMP *amp); /*!< Pointer to backend implementation of ::amp_close(). */ - int (*set_freq)(AMP *amp, freq_t val); /*!< Set the frequency of the amplifier. */ - int (*get_freq)(AMP *amp, freq_t *val); /*!< Query the frequency of the amplifier. */ + int (*set_freq)(AMP *amp, freq_t val); /*!< Pointer to backend implementation of ::amp_set_freq(). */ + int (*get_freq)(AMP *amp, freq_t *val); /*!< Pointer to backend implementation of ::amp_get_freq(). */ - int (*set_conf)(AMP *amp, token_t token, const char *val); /*!< Set the configuration parameter \a val corresponding to the \a token. */ - int (*get_conf)(AMP *amp, token_t token, char *val); /*!< Query the configuration parameter \a val corresponding to the \a token. */ + int (*set_conf)(AMP *amp, token_t token, const char *val); /*!< Pointer to backend implementation of ::amp_set_conf(). */ + int (*get_conf)(AMP *amp, token_t token, char *val); /*!< Pointer to backend implementation of ::amp_get_conf(). */ /* * General API commands, from most primitive to least.. :() * List Set/Get functions pairs */ - int (*reset)(AMP *amp, amp_reset_t reset); /*!< Reset the amplifier (careful!). */ - int (*get_level)(AMP *amp, setting_t level, value_t *val); /*!< Query the \a val corresponding to the \a level. */ - int (*get_ext_level)(AMP *amp, token_t level, value_t *val); /*!< Query the \a val corresponding to the extra \a level. */ - int (*set_powerstat)(AMP *amp, powerstat_t status); /*!< Turn the amplifier On or Off or toggle the Standby or Operate status. */ - int (*get_powerstat)(AMP *amp, powerstat_t *status); /*!< Query the power or standby status of the amplifier. */ + int (*reset)(AMP *amp, amp_reset_t reset); /*!< Pointer to backend implementation of ::amp_reset(). */ + int (*get_level)(AMP *amp, setting_t level, value_t *val); /*!< Pointer to backend implementation of ::amp_get_level(). */ + int (*get_ext_level)(AMP *amp, token_t level, value_t *val); /*!< Pointer to backend implementation of ::amp_get_ext_level(). */ + int (*set_powerstat)(AMP *amp, powerstat_t status); /*!< Pointer to backend implementation of ::amp_set_powerstat(). */ + int (*get_powerstat)(AMP *amp, powerstat_t *status); /*!< Pointer to backend implementation of ::amp_get_powerstat(). */ /* get firmware info, etc. */ - const char *(*get_info)(AMP *amp); /*!< Query available internal information of the amplifier (firmware version, etc.). */ + const char *(*get_info)(AMP *amp); /*!< Pointer to backend implementation of ::amp_get_info(). */ //! @cond Doxygen_Suppress setting_t levels; @@ -251,19 +251,19 @@ struct amp_caps const struct confparams *extlevels; /*!< Extra levels structure. */ const struct confparams *extparms; /*!< Extra parameters structure. */ - const char *macro_name; /*!< Macro name. */ + const char *macro_name; /*!< Amplifier model macro name. */ }; /** * \struct amp_state - * \brief Amplifier state + * \brief Amplifier state structure * * This structure contains live data, as well as a copy of capability fields - * that may be updated (ie. customized) + * that may be updated, i.e. customized while the #AMP handle is instantiated. * - * It is fine to move fields around, as this kind of struct should - * not be initialized like caps are. + * It is fine to move fields around, as this kind of struct should not be + * initialized like amp_caps are. */ struct amp_state { @@ -280,26 +280,23 @@ struct amp_state rig_ptr_t priv; /*!< Pointer to private amplifier state data. */ rig_ptr_t obj; /*!< Internal use by hamlib++ for event handling. */ -//! @cond Doxygen_Suppress - setting_t has_get_level; -//! @endcond + setting_t has_get_level; /*!< List of get levels. */ - gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity */ - gran_t parm_gran[RIG_SETTING_MAX]; /*!< level granularity */ + gran_t level_gran[RIG_SETTING_MAX]; /*!< Level granularity. */ + gran_t parm_gran[RIG_SETTING_MAX]; /*!< Parameter granularity. */ }; /** * \struct amp - * \brief Amplifier structure + * \brief Master amplifier structure * - * Master amplifier data structure acting as a handle for the - * controlled amplifier. + * Master amplifier data structure acting as the #AMP handle for the + * controlled amplifier. A pointer to this structure is returned by the + * amp_init() API function and is passed as a parameter to every amplifier + * specific API call. * - * A pointer to this structure is returned by the amp_init() API function and - * is passed as a parameter to every amplifier specific API call. - * - * \sa amp_caps(), amp_state() + * \sa amp_init(), amp_caps, amp_state */ struct amp { @@ -426,11 +423,11 @@ extern HAMLIB_EXPORT(const char *) amp_strlevel(setting_t); /** - * \def amp_debug - * \brief Convenience macro for generating debugging messages. + * \def amp_debug + * \brief Convenience macro for generating debugging messages. * - * This is an alias of the rig_debug() function call and is used in the same - * manner. + * This is an alias of the rig_debug() function call and is used in the same + * manner. */ #define amp_debug rig_debug diff --git a/include/hamlib/rotator.h b/include/hamlib/rotator.h index 52f22f135..e23c3410a 100644 --- a/include/hamlib/rotator.h +++ b/include/hamlib/rotator.h @@ -31,11 +31,13 @@ */ /** - * \file rotator.h - * \brief Hamlib rotator data structures. + * \file rotator.h + * \brief Hamlib rotator data structures. * - * This file contains the data structures and declarations for the Hamlib - * rotator API. see the rotator.c file for more details on the rotator API. + * This file contains the data structures and declarations for the Hamlib + * rotator Application Programming Interface (API). + * + * See the rotator.c file for more details on the rotator API functions. */ @@ -49,149 +51,166 @@ struct rot_state; /** - * \typedef typedef struct s_rot ROT - * \brief Rotator structure definition (see rot for details). + * \typedef typedef struct s_rot ROT + * \brief Main rotator handle type definition. + * + * The #ROT handle is returned by rot_init() and is passed as a parameter to + * every rotator specific API call. + * + * rot_cleanup() must be called when this handle is no longer needed. */ typedef struct s_rot ROT; /** - * \typedef typedef float elevation_t - * \brief Type definition for elevation. + * \typedef typedef float elevation_t + * \brief Type definition for elevation. * - * The elevation_t type is used as parameter for the rot_set_position() and - * rot_get_position() functions. + * The \a elevation_t type is used as parameter for the rot_set_position() and + * rot_get_position() functions. * - * Unless specified otherwise, the unit of elevation_t is decimal degrees. + * Unless specified otherwise, the unit of \a elevation_t is decimal degrees. */ typedef float elevation_t; /** - * \typedef typedef float azimuth_t - * \brief Type definition for azimuth. + * \typedef typedef float azimuth_t + * \brief Type definition for azimuth. * - * The azimuth_t type is used as parameter for the rot_set_position() and - * rot_get_position() functions. + * The \a azimuth_t type is used as parameter for the rot_set_position() and + * rot_get_position() functions. * - * Unless specified otherwise, the unit of azimuth_t is decimal degrees. + * Unless specified otherwise, the unit of \a azimuth_t is decimal degrees. */ typedef float azimuth_t; /** - * \brief Token in the netrotctl protocol for returning error code + * \brief The token in the netrotctl protocol for returning an error condition code. */ #define NETROTCTL_RET "RPRT " /** - * \def ROT_RESET_ALL - * \brief A macro that returns the flag for the \b reset operation. - * \sa rot_reset(), rot_reset_t() + * \def ROT_RESET_ALL + * \brief A macro that returns the flag for the \b reset operation. + * + * \sa rot_reset(), rot_reset_t */ #define ROT_RESET_ALL 1 /** - * \typedef typedef int rot_reset_t - * \brief Type definition for rotator reset. + * \typedef typedef int rot_reset_t + * \brief Type definition for rotator reset. * - * The rot_reset_t type is used as parameter for the rot_reset() API - * function. + * The \a rot_reset_t type is used as parameter for the rot_reset() API + * function. */ typedef int rot_reset_t; -//! @cond Doxygen_Suppress /** - * \brief Rotator type flags + * \brief Rotator type flags for bitmasks. */ typedef enum { ROT_FLAG_AZIMUTH = (1 << 1), /*!< Azimuth */ ROT_FLAG_ELEVATION = (1 << 2) /*!< Elevation */ } rot_type_t; +//! @cond Doxygen_Suppress +/* So far only used in ests/dumpcaps_rot.c. */ #define ROT_TYPE_MASK (ROT_FLAG_AZIMUTH|ROT_FLAG_ELEVATION) +//! @endcond +/** + * \def ROT_TYPE_OTHER + * \brief Other type of rotator. + * \def ROT_TYPE_AZIMUTH + * \brief Azimuth only rotator. + * \def ROT_TYPE_ELEVATION + * \brief Elevation only rotator. + * \def ROT_TYPE_AZEL + * \brief Combination azimuth/elevation rotator. + */ #define ROT_TYPE_OTHER 0 #define ROT_TYPE_AZIMUTH ROT_FLAG_AZIMUTH #define ROT_TYPE_ELEVATION ROT_FLAG_ELEVATION #define ROT_TYPE_AZEL (ROT_FLAG_AZIMUTH|ROT_FLAG_ELEVATION) -//! @endcond /** - * \def ROT_MOVE_UP - * \brief A macro that returns the flag for the \b UP direction. + * \def ROT_MOVE_UP + * \brief A macro that returns the flag for the \b UP direction. * - * This macro defines the value of the \b UP direction which can be - * used with the rot_move() function. + * This macro defines the value of the \b UP direction which can be + * used with the rot_move() function. * - * \sa rot_move(), ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, - * ROT_MOVE_RIGHT, ROT_MOVE_CW + * \sa rot_move(), ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, + * ROT_MOVE_RIGHT, ROT_MOVE_CW */ #define ROT_MOVE_UP (1<<1) /** - * \def ROT_MOVE_DOWN - * \brief A macro that returns the flag for the \b DOWN direction. + * \def ROT_MOVE_DOWN + * \brief A macro that returns the flag for the \b DOWN direction. * - * This macro defines the value of the \b DOWN direction which can be - * used with the rot_move() function. + * This macro defines the value of the \b DOWN direction which can be + * used with the rot_move() function. * - * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_LEFT, ROT_MOVE_CCW, ROT_MOVE_RIGHT, - * ROT_MOVE_CW + * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_LEFT, ROT_MOVE_CCW, ROT_MOVE_RIGHT, + * ROT_MOVE_CW */ #define ROT_MOVE_DOWN (1<<2) /** - * \def ROT_MOVE_LEFT - * \brief A macro that returns the flag for the \b LEFT direction. + * \def ROT_MOVE_LEFT + * \brief A macro that returns the flag for the \b LEFT direction. * - * This macro defines the value of the \b LEFT direction which can be - * used with the rot_move function. + * This macro defines the value of the \b LEFT direction which can be + * used with the rot_move function. * - * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_CCW, ROT_MOVE_RIGHT, - * ROT_MOVE_CW + * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_CCW, ROT_MOVE_RIGHT, + * ROT_MOVE_CW */ #define ROT_MOVE_LEFT (1<<3) /** - * \def ROT_MOVE_CCW - * \brief A macro that returns the flag for the \b counterclockwise direction. + * \def ROT_MOVE_CCW + * \brief A macro that returns the flag for the \b counterclockwise direction. * - * This macro defines the value of the \b counterclockwise direction which - * can be used with the rot_move() function. This value is equivalent to - * ROT_MOVE_LEFT . + * This macro defines the value of the \b counterclockwise direction which + * can be used with the rot_move() function. This value is equivalent to + * ROT_MOVE_LEFT. * - * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_RIGHT, - * ROT_MOVE_CW + * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_RIGHT, + * ROT_MOVE_CW */ #define ROT_MOVE_CCW ROT_MOVE_LEFT /** - * \def ROT_MOVE_RIGHT - * \brief A macro that returns the flag for the \b RIGHT direction. + * \def ROT_MOVE_RIGHT + * \brief A macro that returns the flag for the \b RIGHT direction. * - * This macro defines the value of the \b RIGHT direction which can be used - * with the rot_move() function. + * This macro defines the value of the \b RIGHT direction which can be used + * with the rot_move() function. * - * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, - * ROT_MOVE_CW + * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, + * ROT_MOVE_CW */ #define ROT_MOVE_RIGHT (1<<4) /** - * \def ROT_MOVE_CW - * \brief A macro that returns the flag for the \b clockwise direction. + * \def ROT_MOVE_CW + * \brief A macro that returns the flag for the \b clockwise direction. * - * This macro defines the value of the \b clockwise direction which can be - * used with the rot_move() function. This value is equivalent to - * ROT_MOVE_RIGHT . + * This macro defines the value of the \b clockwise direction which can be + * used with the rot_move() function. This value is equivalent to + * ROT_MOVE_RIGHT. * - * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, - * ROT_MOVE_RIGHT + * \sa rot_move(), ROT_MOVE_UP, ROT_MOVE_DOWN, ROT_MOVE_LEFT, ROT_MOVE_CCW, + * ROT_MOVE_RIGHT */ #define ROT_MOVE_CW ROT_MOVE_RIGHT @@ -200,46 +219,49 @@ typedef enum { * \brief Rotator status flags */ typedef enum { - ROT_STATUS_NONE = 0, - ROT_STATUS_BUSY = (1 << 0), /*!< Rotator is busy, not accepting commands */ - ROT_STATUS_MOVING = (1 << 1), /*!< Rotator is currently moving (direction type not specified) */ - ROT_STATUS_MOVING_AZ = (1 << 2), /*!< Azimuth rotator is currently moving (direction not specified) */ - ROT_STATUS_MOVING_LEFT = (1 << 3), /*!< Azimuth rotator is currently moving left */ - ROT_STATUS_MOVING_RIGHT = (1 << 4), /*!< Azimuth rotator is currently moving right */ - ROT_STATUS_MOVING_EL = (1 << 5), /*!< Elevation rotator is currently moving (direction not specified) */ - ROT_STATUS_MOVING_UP = (1 << 6), /*!< Elevation rotator is currently moving up */ - ROT_STATUS_MOVING_DOWN = (1 << 7), /*!< Elevation rotator is currently moving down */ - ROT_STATUS_LIMIT_UP = (1 << 8), /*!< The elevation rotator has reached its limit to move up */ - ROT_STATUS_LIMIT_DOWN = (1 << 9), /*!< The elevation rotator has reached its limit to move down */ - ROT_STATUS_LIMIT_LEFT = (1 << 10), /*!< The azimuth rotator has reached its limit to move left (CCW) */ - ROT_STATUS_LIMIT_RIGHT = (1 << 11), /*!< The azimuth rotator has reached its limit to move right (CW) */ - ROT_STATUS_OVERLAP_UP = (1 << 12), /*!< The elevation rotator has rotated up past 360 degrees */ - ROT_STATUS_OVERLAP_DOWN = (1 << 13), /*!< The elevation rotator has rotated down past 0 degrees */ - ROT_STATUS_OVERLAP_LEFT = (1 << 14), /*!< The azimuth rotator has rotated left (CCW) past 0 degrees */ - ROT_STATUS_OVERLAP_RIGHT = (1 << 16), /*!< The azimuth rotator has rotated right (CW) past 360 degrees */ + ROT_STATUS_NONE = 0, /*!< '' -- No status. */ + ROT_STATUS_BUSY = (1 << 0), /*!< Rotator is busy, not accepting commands. */ + ROT_STATUS_MOVING = (1 << 1), /*!< Rotator is currently moving (direction type not specified). */ + ROT_STATUS_MOVING_AZ = (1 << 2), /*!< Azimuth rotator is currently moving (direction not specified). */ + ROT_STATUS_MOVING_LEFT = (1 << 3), /*!< Azimuth rotator is currently moving left. */ + ROT_STATUS_MOVING_RIGHT = (1 << 4), /*!< Azimuth rotator is currently moving right. */ + ROT_STATUS_MOVING_EL = (1 << 5), /*!< Elevation rotator is currently moving (direction not specified). */ + ROT_STATUS_MOVING_UP = (1 << 6), /*!< Elevation rotator is currently moving up. */ + ROT_STATUS_MOVING_DOWN = (1 << 7), /*!< Elevation rotator is currently moving down. */ + ROT_STATUS_LIMIT_UP = (1 << 8), /*!< The elevation rotator has reached its limit to move up. */ + ROT_STATUS_LIMIT_DOWN = (1 << 9), /*!< The elevation rotator has reached its limit to move down.*/ + ROT_STATUS_LIMIT_LEFT = (1 << 10), /*!< The azimuth rotator has reached its limit to move left (CCW). */ + ROT_STATUS_LIMIT_RIGHT = (1 << 11), /*!< The azimuth rotator has reached its limit to move right (CW). */ + ROT_STATUS_OVERLAP_UP = (1 << 12), /*!< The elevation rotator has rotated up past 360 degrees. */ + ROT_STATUS_OVERLAP_DOWN = (1 << 13), /*!< The elevation rotator has rotated down past 0 degrees. */ + ROT_STATUS_OVERLAP_LEFT = (1 << 14), /*!< The azimuth rotator has rotated left (CCW) past 0 degrees. */ + ROT_STATUS_OVERLAP_RIGHT = (1 << 16), /*!< The azimuth rotator has rotated right (CW) past 360 degrees. */ } rot_status_t; +//! @cond Doxygen_Suppress +/* So far only used in tests/sprintflst.c. */ #define ROT_STATUS_N(n) (1u<<(n)) - +//! @endcond /** - * \brief Macro for not changing the rotator speed with move() function + * \brief Macro for not changing the rotator speed with move() function. */ #define ROT_SPEED_NOCHANGE (-1) /** - * \brief Rotator Level Settings + * \brief Rotator Level Settings. * - * Various operating levels supported by a rotator.\n - * \c STRING used in rotctl + * Various operating levels supported by a rotator. + * + * \c STRING used in the \c rotctl and \c rotctld utilities. * * \sa rot_parse_level(), rot_strlevel() */ enum rot_level_e { - ROT_LEVEL_NONE = 0, /*!< '' -- No Level */ - ROT_LEVEL_SPEED = (1 << 0), /*!< \c SPEED -- Rotation speed, arg int (default range 1-100 if not specified) */ - ROT_LEVEL_63 = CONSTANT_64BIT_FLAG(63), /*!< \c Future use, last level */ + ROT_LEVEL_NONE = 0, /*!< '' -- No Level. */ + ROT_LEVEL_SPEED = (1 << 0), /*!< \c SPEED -- Rotation speed, arg int (default range 1-100 if not specified). */ + ROT_LEVEL_63 = CONSTANT_64BIT_FLAG(63), /*!< **Future use**, last level. */ }; @@ -253,11 +275,18 @@ enum rot_level_e { //! @endcond +/** @cond Doxygen_Suppress + * FIXME: The following needs more explanation about how STRING relates + * to this macro. + * @endcond + */ /** * \brief Rotator Parameters * - * Parameters are settings that are not related to core rotator functionality (= antenna rotation).\n - * \c STRING used in rotctl + * Parameters are settings that are not related to core rotator functionality, + * i.e. antenna rotation. + * + * \c STRING used in the \c rotctl and \c rotctld utilities. * * \sa rot_parse_parm(), rot_strparm() */ @@ -275,18 +304,24 @@ enum rot_parm_e { //! @endcond +/** @cond Doxygen_Suppress + * FIXME: The following needs more explanation about how STRING relates + * to these macros. + * @endcond + */ /** - * \brief Rotator Function Settings + * \brief Rotator Function Settings. * - * Various operating functions supported by a rotator.\n - * \c STRING used in rotctl/rotctld + * Various operating functions supported by a rotator. + * + * \c STRING used in the \c rotctl and \c rotctld utilities. * * \sa rot_parse_func(), rot_strfunc() */ #define ROT_FUNC_NONE 0 /*!< '' -- No Function */ #ifndef SWIGLUAHIDE /* Hide the top 32 bits from the old Lua binding as they can't be represented */ -#define ROT_FUNC_BIT63 CONSTANT_64BIT_FLAG (63) /*!< \c available for future ROT_FUNC items */ +#define ROT_FUNC_BIT63 CONSTANT_64BIT_FLAG (63) /*!< **Future use**, ROT_FUNC items. */ /* 63 is this highest bit number that can be used */ #endif @@ -297,35 +332,32 @@ enum rot_parm_e { */ /** - * Rotator Caps * \struct rot_caps - * \brief Rotator data structure. + * \brief Rotator capability data structure. * - * The main idea of this struct is that it will be defined by the backend - * rotator driver, and will remain readonly for the application. Fields that - * need to be modifiable by the application are copied into the struct - * rot_state, which is a kind of private of the ROT instance. + * The main idea of this structure is that it will be defined by the backend + * rotator driver, and will remain read-only for the application. Fields that + * need to be modifiable by the application are copied into the rot_state + * structure, which is the private memory area of the #ROT instance. * - * This way, you can have several rigs running within the same application, - * sharing the struct rot_caps of the backend, while keeping their own - * customized data. + * This way, you can have several rotators running within the same + * application, sharing the rot_caps structure of the backend, while keeping + * their own customized data. * - * mdblack: Careful moving fields around, as the backends depend on it when - * initializing their caps in shared libraries and dlls. + * \b Note: Don't move fields around and only add new fields at the end of the + * rot_caps structure. Shared libraries and DLLs depend on a constant + * structure to maintain compatibility. */ - -//! @cond Doxygen_Suppress -#define ROT_MODEL(arg) .rot_model=arg,.macro_name=#arg struct rot_caps { - rot_model_t rot_model; /*!< Rotator model. */ - const char *model_name; /*!< Model name. */ - const char *mfg_name; /*!< Manufacturer. */ - const char *version; /*!< Driver version. */ - const char *copyright; /*!< Copyright info. */ + rot_model_t rot_model; /*!< Rotator model as defined in rotlist.h. */ + const char *model_name; /*!< Model name, e.g. TT-360. */ + const char *mfg_name; /*!< Manufacturer, e.g. Tower Torquer. */ + const char *version; /*!< Driver version, typically in YYYYMMDD.x format. */ + const char *copyright; /*!< Copyright info (should be LGPL). */ enum rig_status_e status; /*!< Driver status. */ int rot_type; /*!< Rotator type. */ - enum rig_port_e port_type; /*!< Type of communication port. */ + enum rig_port_e port_type; /*!< Type of communication port (serial, ethernet, etc.). */ int serial_rate_min; /*!< Minimal serial speed. */ int serial_rate_max; /*!< Maximal serial speed. */ @@ -337,24 +369,24 @@ struct rot_caps { int write_delay; /*!< Write delay. */ int post_write_delay; /*!< Post-write delay. */ int timeout; /*!< Timeout. */ - int retry; /*!< Number of retry if command fails. */ + int retry; /*!< Number of retries if command fails. */ - setting_t has_get_func; /*!< List of get functions */ - setting_t has_set_func; /*!< List of set functions */ - setting_t has_get_level; /*!< List of get level */ - setting_t has_set_level; /*!< List of set level */ - setting_t has_get_parm; /*!< List of get parm */ - setting_t has_set_parm; /*!< List of set parm */ + setting_t has_get_func; /*!< List of get functions. */ + setting_t has_set_func; /*!< List of set functions. */ + setting_t has_get_level; /*!< List of get levels. */ + setting_t has_set_level; /*!< List of set levels. */ + setting_t has_get_parm; /*!< List of get parameters. */ + setting_t has_set_parm; /*!< List of set parameters. */ - rot_status_t has_status; /*!< Supported status flags */ + rot_status_t has_status; /*!< Supported status flags. */ - gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity (i.e. steps) */ - gran_t parm_gran[RIG_SETTING_MAX]; /*!< parm granularity (i.e. steps) */ + gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity (i.e. steps). */ + gran_t parm_gran[RIG_SETTING_MAX]; /*!< parm granularity (i.e. steps). */ - const struct confparams *extparms; /*!< Extension parm list, \sa ext.c */ - const struct confparams *extlevels; /*!< Extension level list, \sa ext.c */ - const struct confparams *extfuncs; /*!< Extension func list, \sa ext.c */ - int *ext_tokens; /*!< Extension token list */ + const struct confparams *extparms; /*!< Extension parameter list, \sa ext.c. */ + const struct confparams *extlevels; /*!< Extension level list, \sa ext.c. */ + const struct confparams *extfuncs; /*!< Extension func list, \sa ext.c. */ + int *ext_tokens; /*!< Extension token list. */ /* * Movement range, az is relative to North @@ -376,65 +408,66 @@ struct rot_caps { * */ - int (*rot_init)(ROT *rot); - int (*rot_cleanup)(ROT *rot); - int (*rot_open)(ROT *rot); - int (*rot_close)(ROT *rot); + int (*rot_init)(ROT *rot); /*!< Pointer to backend implementation of ::rot_init(). */ + int (*rot_cleanup)(ROT *rot); /*!< Pointer to backend implementation of ::rot_cleanup(). */ + int (*rot_open)(ROT *rot); /*!< Pointer to backend implementation of ::rot_open(). */ + int (*rot_close)(ROT *rot); /*!< Pointer to backend implementation of ::rot_close(). */ - int (*set_conf)(ROT *rot, token_t token, const char *val); - int (*get_conf)(ROT *rot, token_t token, char *val); + int (*set_conf)(ROT *rot, token_t token, const char *val); /*!< Pointer to backend implementation of ::rot_set_conf(). */ + int (*get_conf)(ROT *rot, token_t token, char *val); /*!< Pointer to backend implementation of ::rot_get_conf(). */ /* * General API commands, from most primitive to least.. :() * List Set/Get functions pairs */ - int (*set_position)(ROT *rot, azimuth_t azimuth, elevation_t elevation); - int (*get_position)(ROT *rot, azimuth_t *azimuth, elevation_t *elevation); + int (*set_position)(ROT *rot, azimuth_t azimuth, elevation_t elevation); /*!< Pointer to backend implementation of ::rot_set_position(). */ + int (*get_position)(ROT *rot, azimuth_t *azimuth, elevation_t *elevation); /*!< Pointer to backend implementation of ::rot_get_position(). */ - int (*stop)(ROT *rot); - int (*park)(ROT *rot); - int (*reset)(ROT *rot, rot_reset_t reset); - int (*move)(ROT *rot, int direction, int speed); + int (*stop)(ROT *rot); /*!< Pointer to backend implementation of ::rot_stop(). */ + int (*park)(ROT *rot); /*!< Pointer to backend implementation of ::rot_park(). */ + int (*reset)(ROT *rot, rot_reset_t reset); /*!< Pointer to backend implementation of ::rot_reset(). */ + int (*move)(ROT *rot, int direction, int speed); /*!< Pointer to backend implementation of ::rot_move(). */ /* get firmware info, etc. */ - const char * (*get_info)(ROT *rot); + const char * (*get_info)(ROT *rot); /*!< Pointer to backend implementation of ::rot_get_info(). */ - int (*set_level)(ROT *rot, setting_t level, value_t val); - int (*get_level)(ROT *rot, setting_t level, value_t *val); + int (*set_level)(ROT *rot, setting_t level, value_t val); /*!< Pointer to backend implementation of ::rot_set_level(). */ + int (*get_level)(ROT *rot, setting_t level, value_t *val); /*!< Pointer to backend implementation of ::rot_get_level(). */ - int (*set_func)(ROT *rot, setting_t func, int status); - int (*get_func)(ROT *rot, setting_t func, int *status); + int (*set_func)(ROT *rot, setting_t func, int status); /*!< Pointer to backend implementation of ::rot_set_func(). */ + int (*get_func)(ROT *rot, setting_t func, int *status); /*!< Pointer to backend implementation of ::rot_get_func(). */ - int (*set_parm)(ROT *rot, setting_t parm, value_t val); - int (*get_parm)(ROT *rot, setting_t parm, value_t *val); + int (*set_parm)(ROT *rot, setting_t parm, value_t val); /*!< Pointer to backend implementation of ::rot_set_parm(). */ + int (*get_parm)(ROT *rot, setting_t parm, value_t *val); /*!< Pointer to backend implementation of ::rot_get_parm(). */ - int (*set_ext_level)(ROT *rot, token_t token, value_t val); - int (*get_ext_level)(ROT *rot, token_t token, value_t *val); + int (*set_ext_level)(ROT *rot, token_t token, value_t val); /*!< Pointer to backend implementation of ::rot_set_ext_level(). */ + int (*get_ext_level)(ROT *rot, token_t token, value_t *val); /*!< Pointer to backend implementation of ::rot_get_ext_level(). */ - int (*set_ext_func)(ROT *rot, token_t token, int status); - int (*get_ext_func)(ROT *rot, token_t token, int *status); + int (*set_ext_func)(ROT *rot, token_t token, int status); /*!< Pointer to backend implementation of ::rot_set_ext_func(). */ + int (*get_ext_func)(ROT *rot, token_t token, int *status); /*!< Pointer to backend implementation of ::rot_get_ext_func(). */ - int (*set_ext_parm)(ROT *rot, token_t token, value_t val); - int (*get_ext_parm)(ROT *rot, token_t token, value_t *val); + int (*set_ext_parm)(ROT *rot, token_t token, value_t val); /*!< Pointer to backend implementation of ::rot_set_ext_parm(). */ + int (*get_ext_parm)(ROT *rot, token_t token, value_t *val); /*!< Pointer to backend implementation of ::rot_get_ext_parm(). */ - int (*get_status)(ROT *rot, rot_status_t *status); + int (*get_status)(ROT *rot, rot_status_t *status); /*!< Pointer to backend implementation of ::rot_get_status(). */ - const char *macro_name; /*!< Macro name. */ + const char *macro_name; /*!< Rotator model macro name. */ }; +//! @cond Doxygen_Suppress +#define ROT_MODEL(arg) .rot_model=arg,.macro_name=#arg //! @endcond /** - * Rotator state * \struct rot_state - * \brief Live data and customized fields. + * \brief Rotator state structure * - * This struct contains live data, as well as a copy of capability fields - * that may be updated (ie. customized) + * This structure contains live data, as well as a copy of capability fields + * that may be updated, i.e. customized while the #ROT handle is instantiated. * - * It is fine to move fields around, as this kind of struct should - * not be initialized like caps are. + * It is fine to move fields around, as this kind of structure should not be + * initialized like rot_caps are. */ struct rot_state { /* @@ -444,47 +477,46 @@ struct rot_state { azimuth_t max_az; /*!< Upper limit for azimuth (overridable). */ elevation_t min_el; /*!< Lower limit for elevation (overridable). */ elevation_t max_el; /*!< Upper limit for elevation (overridable). */ - int south_zero; /*!< South is zero degrees */ - azimuth_t az_offset; /*!< Offset to be applied to azimuth */ - elevation_t el_offset; /*!< Offset to be applied to elevation */ + int south_zero; /*!< South is zero degrees. */ + azimuth_t az_offset; /*!< Offset to be applied to azimuth. */ + elevation_t el_offset; /*!< Offset to be applied to elevation. */ - setting_t has_get_func; /*!< List of get functions */ - setting_t has_set_func; /*!< List of set functions */ - setting_t has_get_level; /*!< List of get level */ - setting_t has_set_level; /*!< List of set level */ - setting_t has_get_parm; /*!< List of get parm */ - setting_t has_set_parm; /*!< List of set parm */ + setting_t has_get_func; /*!< List of get functions. */ + setting_t has_set_func; /*!< List of set functions. */ + setting_t has_get_level; /*!< List of get levels. */ + setting_t has_set_level; /*!< List of set levels. */ + setting_t has_get_parm; /*!< List of get parameters. */ + setting_t has_set_parm; /*!< List of set parameters. */ - rot_status_t has_status; /*!< Supported status flags */ + rot_status_t has_status; /*!< Supported status flags. */ - gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity */ - gran_t parm_gran[RIG_SETTING_MAX]; /*!< parm granularity */ + gran_t level_gran[RIG_SETTING_MAX]; /*!< Level granularity. */ + gran_t parm_gran[RIG_SETTING_MAX]; /*!< Parameter granularity. */ /* * non overridable fields, internal use */ hamlib_port_t rotport; /*!< Rotator port (internal use). */ - int comm_state; /*!< Comm port state, opened/closed. */ + int comm_state; /*!< Comm port state, i.e. opened or closed. */ rig_ptr_t priv; /*!< Pointer to private rotator state data. */ rig_ptr_t obj; /*!< Internal use by hamlib++ for event handling. */ - int current_speed; /*!< Current speed 1-100, to be used when no change to speed is requested */ + int current_speed; /*!< Current speed 1-100, to be used when no change to speed is requested. */ /* etc... */ }; /** - * Rotator structure * \struct s_rot - * \brief This is the master data structure, - * acting as a handle for the controlled rotator. + * \brief Master rotator structure. * - * This is the master data structure, acting as a handle for the controlled - * rotator. A pointer to this structure is returned by the rot_init() API - * function and is passed as a parameter to every rotator specific API call. + * This is the master data structure acting as the #ROT handle for the + * controlled rotator. A pointer to this structure is returned by the + * rot_init() API function and is passed as a parameter to every rotator + * specific API call. * - * \sa rot_init(), rot_caps(), rot_state() + * \sa rot_init(), rot_caps, rot_state */ struct s_rot { struct rot_caps *caps; /*!< Rotator caps. */ @@ -757,13 +789,11 @@ extern HAMLIB_EXPORT(const char *) rot_strstatus(rot_status_t); //! @endcond /** - * \def rot_debug - * \brief Convenience definition for debug level. + * \def rot_debug + * \brief Convenience macro for generating debugging messages. * - * This is just as convenience definition of the rotator debug level, - * and is the same as for the rig debug level. - * - * \sa rig_debug() + * This is an alias of the rig_debug() function call and is used in the same + * manner. */ #define rot_debug rig_debug