kopia lustrzana https://github.com/Hamlib/Hamlib
Update Doxygen comments in amplifier.h
Nate Bargmann
rodzic
d4bc60be0b
commit
20ce18f477
|
|
@ -35,7 +35,9 @@
|
||||||
* \brief Hamlib amplifier data structures.
|
* \brief Hamlib amplifier data structures.
|
||||||
*
|
*
|
||||||
* This file contains the data structures and declarations for the Hamlib
|
* This file contains the data structures and declarations for the Hamlib
|
||||||
* amplifier API. see the amplifier.c file for more details on the amplifier API.
|
* amplifier Application Programming Interface (API).
|
||||||
|
*
|
||||||
|
* See the `amplifier.c` file for details on the amplifier API functions.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -50,35 +52,52 @@ struct amp_state;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \typedef typedef struct amp AMP
|
* \typedef typedef struct amp AMP
|
||||||
* \brief Amplifier structure definition (see amp for details).
|
* \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.
|
||||||
|
*
|
||||||
|
* amp_cleanup() must be called when this handle is no longer needed.
|
||||||
*/
|
*/
|
||||||
typedef struct amp AMP;
|
typedef struct amp AMP;
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \typedef typedef float swr_t
|
* \typedef typedef float swr_t
|
||||||
* \brief Type definition for SWR.
|
* \brief Type definition for
|
||||||
|
* <a href="https://en.wikipedia.org/wiki/Standing_wave_ratio" >SWR (Standing Wave Ratio)</a>.
|
||||||
*
|
*
|
||||||
* The swr_t type is used as a parameter for the amp_get_swr() function.
|
* The \c swr_t type is used as a parameter for the amp_get_swr() function.
|
||||||
*
|
*
|
||||||
* Unless specified otherwise, the unit of swr_t is 1.0 to max reported by tuner
|
* The unit of \c swr_t is 1.0 to the maximum value reported by the amplifier's
|
||||||
|
* internal antenna system tuner, i.e.
|
||||||
|
* <a href="http://www.arrl.org/transmatch-antenna-tuner" >transmatch</a>,
|
||||||
|
* representing the ratio of 1.0:1 to Maximum:1.
|
||||||
*/
|
*/
|
||||||
typedef float swr_t;
|
typedef float swr_t;
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \typedef typedef float tune_value_t
|
* \typedef typedef float tune_value_t
|
||||||
* \brief Type definition for tuning values capacitance and resistance.
|
* \brief Type definition for the
|
||||||
|
* <a href="http://www.arrl.org/transmatch-antenna-tuner" >transmatch</a>
|
||||||
|
* tuning values of
|
||||||
|
* <a href="https://en.wikipedia.org/wiki/Capacitance" >capacitance</a>
|
||||||
|
* and
|
||||||
|
* <a href="https://en.wikipedia.org/wiki/Inductance" >inductance</a>.
|
||||||
*
|
*
|
||||||
* The tune_value_t type is used as a parameter for the amp_get_level()
|
* The \c tune_value_t type is used as a parameter for amp_get_level().
|
||||||
*
|
*
|
||||||
* Unless specified otherwise, the units of tune_value_t is pF and nH
|
* The unit of \c tune_value_t is
|
||||||
|
* <a href="https://en.wikipedia.org/wiki/Farad" >picoFarads (pF)</a>
|
||||||
|
* or
|
||||||
|
* <a href="https://en.wikipedia.org/wiki/Henry_(unit)" >nanoHenrys (nH)</a>.
|
||||||
*/
|
*/
|
||||||
typedef int tune_value_t;
|
typedef int tune_value_t;
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \brief Token in the netampctl protocol for returning error code
|
* \brief The token in the netampctl protocol for returning an error condition code.
|
||||||
*/
|
*/
|
||||||
#define NETAMPCTL_RET "RPRT "
|
#define NETAMPCTL_RET "RPRT "
|
||||||
|
|
||||||
|
|
@ -86,9 +105,9 @@ typedef int tune_value_t;
|
||||||
//! @cond Doxygen_Suppress
|
//! @cond Doxygen_Suppress
|
||||||
typedef enum
|
typedef enum
|
||||||
{
|
{
|
||||||
AMP_RESET_MEM, // erase tuner memory
|
AMP_RESET_MEM, // erase tuner memory
|
||||||
AMP_RESET_FAULT, // reset any fault
|
AMP_RESET_FAULT, // reset any fault
|
||||||
AMP_RESET_AMP // for kpa1500
|
AMP_RESET_AMP // for kpa1500
|
||||||
} amp_reset_t;
|
} amp_reset_t;
|
||||||
//! @endcond
|
//! @endcond
|
||||||
|
|
||||||
|
|
@ -103,27 +122,27 @@ typedef enum
|
||||||
|
|
||||||
//! @cond Doxygen_Suppress
|
//! @cond Doxygen_Suppress
|
||||||
// TBD AMP_TYPE
|
// TBD AMP_TYPE
|
||||||
#define AMP_TYPE_MASK (AMP_FLAG_1|AMP_FLAG_2)
|
#define AMP_TYPE_MASK (AMP_FLAG_1|AMP_FLAG_2)
|
||||||
|
|
||||||
#define AMP_TYPE_OTHER 0
|
#define AMP_TYPE_OTHER 0
|
||||||
#define AMP_TYPE_1 AMP_FLAG_1
|
#define AMP_TYPE_1 AMP_FLAG_1
|
||||||
#define AMP_TYPE_2 AMP_FLAG_2
|
#define AMP_TYPE_2 AMP_FLAG_2
|
||||||
#define AMP_TYPE_ALL (AMP_FLAG_1|AMP_FLAG_2)
|
#define AMP_TYPE_ALL (AMP_FLAG_1|AMP_FLAG_2)
|
||||||
//! @endcond
|
//! @endcond
|
||||||
|
|
||||||
|
|
||||||
//! @cond Doxygen_Suppress
|
//! @cond Doxygen_Suppress
|
||||||
enum amp_level_e
|
enum amp_level_e
|
||||||
{
|
{
|
||||||
AMP_LEVEL_NONE = 0, /*!< '' -- No Level */
|
AMP_LEVEL_NONE = 0, /*!< '' -- No Level. */
|
||||||
AMP_LEVEL_SWR = (1 << 0), /*!< \c SWR 1.0 or greater */
|
AMP_LEVEL_SWR = (1 << 0), /*!< \c SWR 1.0 or greater. */
|
||||||
AMP_LEVEL_NH = (1 << 1), /*!< \c Tune setting nanohenries */
|
AMP_LEVEL_NH = (1 << 1), /*!< \c Tune setting in nanohenries. */
|
||||||
AMP_LEVEL_PF = (1 << 2), /*!< \c Tune setting picofarads */
|
AMP_LEVEL_PF = (1 << 2), /*!< \c Tune setting in picofarads. */
|
||||||
AMP_LEVEL_PWR_INPUT = (1 << 3), /*!< \c Power reading from amp */
|
AMP_LEVEL_PWR_INPUT = (1 << 3), /*!< \c Power reading from amplifier. */
|
||||||
AMP_LEVEL_PWR_FWD = (1 << 4), /*!< \c Power reading forward */
|
AMP_LEVEL_PWR_FWD = (1 << 4), /*!< \c Power reading forward. */
|
||||||
AMP_LEVEL_PWR_REFLECTED = (1 << 5), /*!< \c Power reading reverse */
|
AMP_LEVEL_PWR_REFLECTED = (1 << 5), /*!< \c Power reading reverse. */
|
||||||
AMP_LEVEL_PWR_PEAK = (1 << 6), /*!< \c Power reading peak */
|
AMP_LEVEL_PWR_PEAK = (1 << 6), /*!< \c Power reading peak. */
|
||||||
AMP_LEVEL_FAULT = (1 << 7) /*!< \c Fault code */
|
AMP_LEVEL_FAULT = (1 << 7) /*!< \c Fault code. */
|
||||||
};
|
};
|
||||||
//! @endcond
|
//! @endcond
|
||||||
|
|
||||||
|
|
@ -139,36 +158,38 @@ enum amp_level_e
|
||||||
* enquiries about capabilities.
|
* enquiries about capabilities.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
|
||||||
* Amplifier Caps
|
|
||||||
* \struct amp_caps
|
|
||||||
* \brief Amplifier data structure.
|
|
||||||
*
|
|
||||||
* The main idea of this struct is that it will be defined by the backend
|
|
||||||
* amplifier driver, and will remain readonly for the application. Fields that
|
|
||||||
* need to be modifiable by the application are copied into the struct
|
|
||||||
* amp_state, which is a kind of private of the AMP instance.
|
|
||||||
*
|
|
||||||
* This way, you can have several rigs running within the same application,
|
|
||||||
* sharing the struct amp_caps of the backend, while keeping their own
|
|
||||||
* customized data.
|
|
||||||
*
|
|
||||||
* mdblack98: Don't move fields around and add new fields at end of caps
|
|
||||||
* Shared libraries depend on constant structure to maintain compatibility
|
|
||||||
*/
|
|
||||||
//! @cond Doxygen_Suppress
|
//! @cond Doxygen_Suppress
|
||||||
#define AMP_MODEL(arg) .amp_model=arg,.macro_name=#arg
|
#define AMP_MODEL(arg) .amp_model=arg,.macro_name=#arg
|
||||||
|
//! @endcond
|
||||||
|
|
||||||
|
/**
|
||||||
|
* \struct amp_caps
|
||||||
|
* \brief Amplifier capabilities
|
||||||
|
*
|
||||||
|
* 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.
|
||||||
|
*
|
||||||
|
* This way you can have several amplifiers running within the same
|
||||||
|
* application, sharing the struct \c amp_caps 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.
|
||||||
|
*/
|
||||||
struct amp_caps
|
struct amp_caps
|
||||||
{
|
{
|
||||||
amp_model_t amp_model; /*!< Amplifier model. */
|
amp_model_t amp_model; /*!< Amplifier model as defined in `amplist.h`. */
|
||||||
const char *model_name; /*!< Model name. */
|
const char *model_name; /*!< Model name, e.g. MM-5k. */
|
||||||
const char *mfg_name; /*!< Manufacturer. */
|
const char *mfg_name; /*!< Manufacturer, e.g. Moonbeam. */
|
||||||
const char *version; /*!< Driver version. */
|
const char *version; /*!< Driver version. */
|
||||||
const char *copyright; /*!< Copyright info. */
|
const char *copyright; /*!< Copyright info (should be LGPL). */
|
||||||
enum rig_status_e status; /*!< Driver status. */
|
enum rig_status_e status; /*!< Driver status. */
|
||||||
|
|
||||||
int amp_type; /*!< Amplifier type. */
|
int amp_type; /*!< Amplifier 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_min; /*!< Minimal serial speed. */
|
||||||
int serial_rate_max; /*!< Maximal serial speed. */
|
int serial_rate_max; /*!< Maximal serial speed. */
|
||||||
|
|
@ -180,65 +201,65 @@ struct amp_caps
|
||||||
int write_delay; /*!< Write delay. */
|
int write_delay; /*!< Write delay. */
|
||||||
int post_write_delay; /*!< Post-write delay. */
|
int post_write_delay; /*!< Post-write delay. */
|
||||||
int timeout; /*!< Timeout. */
|
int timeout; /*!< Timeout. */
|
||||||
int retry; /*!< Number of retry if command fails. */
|
int retry; /*!< Number of retries if a command fails. */
|
||||||
|
|
||||||
const struct confparams *cfgparams; /*!< Configuration parametres. */
|
const struct confparams *cfgparams; /*!< Configuration parameters. */
|
||||||
const rig_ptr_t priv; /*!< Private data. */
|
const rig_ptr_t priv; /*!< Private data. */
|
||||||
const char *amp_model_macro_name; /*!< Model macro name */
|
const char *amp_model_macro_name; /*!< Model macro name. */
|
||||||
|
|
||||||
setting_t has_get_level;
|
setting_t has_get_level; /*!< Has get_level capability. */
|
||||||
setting_t has_set_level;
|
setting_t has_set_level; /*!< Has set_level capability. */
|
||||||
|
|
||||||
gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
||||||
gran_t parm_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
gran_t parm_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* Amp Admin API
|
* Amp Admin API
|
||||||
*
|
*
|
||||||
*/
|
*/
|
||||||
|
|
||||||
int (*amp_init)(AMP *amp);
|
int (*amp_init)(AMP *amp); /*!< Initializes data structures and returns an #AMP handle--call before amp_open(). */
|
||||||
int (*amp_cleanup)(AMP *amp);
|
int (*amp_cleanup)(AMP *amp); /*!< Frees the data structures associated with the #AMP handle--call after amp_close(). */
|
||||||
int (*amp_open)(AMP *amp);
|
int (*amp_open)(AMP *amp); /*!< Opens the communication channel to the amplifier. */
|
||||||
int (*amp_close)(AMP *amp);
|
int (*amp_close)(AMP *amp); /*!< Closes the communication channel to the amplifier. */
|
||||||
|
|
||||||
int (*set_freq)(AMP *amp, freq_t val);
|
int (*set_freq)(AMP *amp, freq_t val); /*!< Set the frequency of the amplifier. */
|
||||||
int (*get_freq)(AMP *amp, freq_t *val);
|
int (*get_freq)(AMP *amp, freq_t *val); /*!< Query the frequency of the amplifier. */
|
||||||
|
|
||||||
int (*set_conf)(AMP *amp, token_t token, const char *val);
|
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);
|
int (*get_conf)(AMP *amp, token_t token, char *val); /*!< Query the configuration parameter \a val corresponding to the \a token. */
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* General API commands, from most primitive to least.. :()
|
* General API commands, from most primitive to least.. :()
|
||||||
* List Set/Get functions pairs
|
* List Set/Get functions pairs
|
||||||
*/
|
*/
|
||||||
|
|
||||||
int (*reset)(AMP *amp, amp_reset_t reset);
|
int (*reset)(AMP *amp, amp_reset_t reset); /*!< Reset the amplifier (careful!). */
|
||||||
int (*get_level)(AMP *amp, setting_t level, value_t *val);
|
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);
|
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);
|
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);
|
int (*get_powerstat)(AMP *amp, powerstat_t *status); /*!< Query the power or standby status of the amplifier. */
|
||||||
|
|
||||||
|
|
||||||
/* get firmware info, etc. */
|
/* get firmware info, etc. */
|
||||||
const char *(*get_info)(AMP *amp);
|
const char *(*get_info)(AMP *amp); /*!< Query available internal information of the amplifier (firmware version, etc.). */
|
||||||
|
|
||||||
|
//! @cond Doxygen_Suppress
|
||||||
setting_t levels;
|
setting_t levels;
|
||||||
unsigned ext_levels;
|
unsigned ext_levels;
|
||||||
const struct confparams *extlevels;
|
//! @endcond
|
||||||
const struct confparams *extparms;
|
const struct confparams *extlevels; /*!< Extra levels structure. */
|
||||||
|
const struct confparams *extparms; /*!< Extra parameters structure. */
|
||||||
|
|
||||||
const char *macro_name; /*!< Macro name. */
|
const char *macro_name; /*!< Macro name. */
|
||||||
};
|
};
|
||||||
//! @endcond
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Amplifier state
|
|
||||||
* \struct amp_state
|
* \struct amp_state
|
||||||
* \brief Live data and customized fields.
|
* \brief Amplifier state
|
||||||
*
|
*
|
||||||
* This struct contains live data, as well as a copy of capability fields
|
* This structure contains live data, as well as a copy of capability fields
|
||||||
* that may be updated (ie. customized)
|
* that may be updated (ie. customized)
|
||||||
*
|
*
|
||||||
* It is fine to move fields around, as this kind of struct should
|
* It is fine to move fields around, as this kind of struct should
|
||||||
|
|
@ -264,21 +285,21 @@ struct amp_state
|
||||||
//! @endcond
|
//! @endcond
|
||||||
|
|
||||||
gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
||||||
gran_t parm_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
gran_t parm_gran[RIG_SETTING_MAX]; /*!< level granularity */
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Amplifier structure
|
|
||||||
* \struct amp
|
* \struct amp
|
||||||
* \brief This is the master data structure,
|
* \brief Amplifier structure
|
||||||
* acting as a handle for the controlled amplifier.
|
|
||||||
*
|
*
|
||||||
* This is the master data structure, acting as a handle for the controlled
|
* Master amplifier data structure acting as a handle for the
|
||||||
* amplifier. A pointer to this structure is returned by the amp_init() API
|
* controlled amplifier.
|
||||||
* function and is passed as a parameter to every amplifier specific API call.
|
|
||||||
*
|
*
|
||||||
* \sa amp_init(), amp_caps(), amp_state()
|
* 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()
|
||||||
*/
|
*/
|
||||||
struct amp
|
struct amp
|
||||||
{
|
{
|
||||||
|
|
@ -406,12 +427,10 @@ extern HAMLIB_EXPORT(const char *) amp_strlevel(setting_t);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* \def amp_debug
|
* \def amp_debug
|
||||||
* \brief Convenience definition for debug level.
|
* \brief Convenience macro for generating debugging messages.
|
||||||
*
|
*
|
||||||
* This is just as convenience definition of the amplifier debug level,
|
* This is an alias of the rig_debug() function call and is used in the same
|
||||||
* and is the same as for the rig debug level.
|
* manner.
|
||||||
*
|
|
||||||
* \sa rig_debug()
|
|
||||||
*/
|
*/
|
||||||
#define amp_debug rig_debug
|
#define amp_debug rig_debug
|
||||||
|
|
||||||
|
|
|
||||||
Ładowanie…
Reference in New Issue