Hamlib 4.5
Loading...
Searching...
No Matches
Files | Macros | Typedefs | Functions
Amplifier API

Files

file  amplist.h
 Hamlib amplifier model definitions.
 
file  amp_conf.c
 Amplifier Configuration Interface.
 
file  amp_settings.c
 Amplifier function/level/parameter interface.
 
file  amplifier.c
 Amplifier interface.
 
file  extamp.c
 Amplifier extension parameters and levels interface.
 

Macros

#define AMP_MODEL_NONE   0
 A macro that returns the model number for an unknown model. More...
 
#define AMP_MODEL_DUMMY   AMP_MAKE_MODEL(AMP_DUMMY, 1)
 A macro that returns the model number for the DUMMY backend. More...
 
#define AMP_MODEL_NETAMPCTL   AMP_MAKE_MODEL(AMP_DUMMY, 2)
 A macro that returns the model number for the NETAMPCTL backend. More...
 
#define AMP_MODEL_ELECRAFT_KPA1500   AMP_MAKE_MODEL(AMP_ELECRAFT, 1)
 A macro that returns the model number of the KPA1500 backend. More...
 
#define AMP_GEMINI   3
 
#define AMP_BACKEND_GEMINI   "gemini"
 
#define AMP_MODEL_GEMINI_DX1200   AMP_MAKE_MODEL(AMP_GEMINI, 1)
 

Typedefs

typedef int amp_model_t
 Convenience type definition for an amplifier model. More...
 

Functions

const struct confparamsamp_confparam_lookup (AMP *amp, const char *name)
 Query an amplifier configuration parameter token by its name. More...
 
token_t amp_token_lookup (AMP *amp, const char *name)
 Search for the token ID associated with an amplifier configuration parameter token name. More...
 
int amp_set_conf (AMP *amp, token_t token, const char *val)
 Set an amplifier configuration parameter. More...
 
int amp_get_conf2 (AMP *amp, token_t token, char *val, int val_len)
 Query the value of an amplifier configuration parameter. More...
 
int amp_get_conf (AMP *amp, token_t token, char *val)
 
setting_t amp_has_set_level (AMP *amp, setting_t level)
 Check which level settings can be set. More...
 
setting_t amp_has_get_level (AMP *amp, setting_t level)
 Check which level settings can be queried. More...
 
AMP * amp_init (amp_model_t amp_model)
 Allocate a new #AMP handle. More...
 
int amp_open (AMP *amp)
 Open the communication channel to the amplifier. More...
 
int amp_close (AMP *amp)
 Close the communication channel to the amplifier. More...
 
int amp_cleanup (AMP *amp)
 Release an #AMP handle and free associated memory. More...
 
int amp_reset (AMP *amp, amp_reset_t reset)
 Reset the amplifier. More...
 
int amp_get_freq (AMP *amp, freq_t *freq)
 Query the operating frequency of the amplifier. More...
 
int amp_set_freq (AMP *amp, freq_t freq)
 Set the operating frequency of the amplifier. More...
 
const char * amp_get_info (AMP *amp)
 Query general information from the amplifier. More...
 
int amp_set_level (AMP *amp, setting_t level, value_t val)
 Set the value of a requested level. More...
 
int amp_get_level (AMP *amp, setting_t level, value_t *val)
 Query the value of a requested level. More...
 
int amp_set_ext_level (AMP *amp, token_t level, value_t val)
 Set the value of a requested extension levels token. More...
 
int amp_get_ext_level (AMP *amp, token_t level, value_t *val)
 Query the value of a requested extension levels token. More...
 
int amp_set_powerstat (AMP *amp, powerstat_t status)
 Turn the amplifier On or Off or toggle the Standby or Operate status. More...
 
int amp_get_powerstat (AMP *amp, powerstat_t *status)
 Query the power or standby status of the amplifier. More...
 
int amp_ext_level_foreach (AMP *amp, int(*cfunc)(AMP *, const struct confparams *, amp_ptr_t), amp_ptr_t data)
 Executes cfunc on all the elements stored in the amp_caps::extlevels extension levels table. More...
 
int amp_ext_parm_foreach (AMP *amp, int(*cfunc)(AMP *, const struct confparams *, amp_ptr_t), amp_ptr_t data)
 Executes cfunc on all the elements stored in the amp_caps::extparms extension parameters table. More...
 
const struct confparamsamp_ext_lookup (AMP *amp, const char *name)
 Lookup an extension levels or parameters token by its name and return a pointer to the containing confparams structure member. More...
 
const struct confparamsamp_ext_lookup_tok (AMP *amp, token_t token)
 Search for an extension levels or parameters token by its constant value and return a pointer to the confparams structure member. More...
 
token_t amp_ext_token_lookup (AMP *amp, const char *name)
 Simple search returning the extension token ID associated with name. More...
 

Detailed Description

Amplifier interface

An amplifier can be any kind of external power amplifier that is capable of CAT type control.

Macro Definition Documentation

◆ AMP_MODEL_DUMMY

#define AMP_MODEL_DUMMY   AMP_MAKE_MODEL(AMP_DUMMY, 1)

A macro that returns the model number for the DUMMY backend.

The DUMMY backend, as the name suggests, is a backend which performs no hardware operations and always behaves as one would expect. It can be thought of as a hardware simulator and is very useful for testing client applications.

◆ AMP_MODEL_ELECRAFT_KPA1500

#define AMP_MODEL_ELECRAFT_KPA1500   AMP_MAKE_MODEL(AMP_ELECRAFT, 1)

A macro that returns the model number of the KPA1500 backend.

The KPA1500 backend can be used with amplifiers that support the Elecraft KPA-1500 protocol.

◆ AMP_MODEL_NETAMPCTL

#define AMP_MODEL_NETAMPCTL   AMP_MAKE_MODEL(AMP_DUMMY, 2)

A macro that returns the model number for the NETAMPCTL backend.

The NETAMPCTL backend allows use of the ampctld daemon through the normal Hamlib API.

◆ AMP_MODEL_NONE

#define AMP_MODEL_NONE   0

A macro that returns the model number for an unknown model.

The none backend, as the name suggests, does nothing. It is mainly for internal use.

Typedef Documentation

◆ amp_model_t

typedef int amp_model_t

Convenience type definition for an amplifier model.

Function Documentation

◆ amp_cleanup()

int amp_cleanup ( AMP *  amp)

Release an #AMP handle and free associated memory.

Parameters
ampThe #AMP handle to be released.

Releases an #AMP handle for which the communications channel has been closed with amp_close().

Returns
RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OK#AMP handle successfully released.
RIG_EINVALamp is NULL or inconsistent.
See also
amp_init(), amp_close()

◆ amp_close()

int amp_close ( AMP *  amp)

Close the communication channel to the amplifier.

Parameters
ampThe #AMP handle of the amplifier to be closed.

Closes the communication channel to an amplifier for which the #AMP handle has been passed by argument that was previously opened with amp_open().

Returns
RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKCommunication channel successfully closed.
RIG_EINVALamp is NULL or inconsistent.
See also
amp_cleanup(), amp_open()

◆ amp_confparam_lookup()

const struct confparams * amp_confparam_lookup ( AMP *  amp,
const char *  name 
)

Query an amplifier configuration parameter token by its name.

Parameters
ampThe #AMP handle.
nameConfiguration parameter token name string.

Use this function to get a pointer to the token in the confparams structure. Searches the backend config params table first, then falls back to the frontend config params table.

Returns
A pointer to the token in the confparams structure or NULL if amp is NULL or inconsistent or if name is not found (how can the caller know which occurred?).
See also
amp_token_lookup()

TODO: Should use Lex to speed it up, strcmp() hurts!

◆ amp_ext_level_foreach()

int amp_ext_level_foreach ( AMP *  amp,
int(*)(AMP *, const struct confparams *, amp_ptr_t)  cfunc,
amp_ptr_t  data 
)

Executes cfunc on all the elements stored in the amp_caps::extlevels extension levels table.

Parameters
ampThe #AMP handle.
cfuncCallback function of each amp_caps::extlevels.
dataCookie to be passed to the callback function cfunc.

The callback function cfunc is called until it returns a value which is not strictly positive.

Returns
A zero value which means a normal end of iteration, or a negative value which means an abnormal end,
Return values
RIG_OKAll extension levels elements successfully processed.
RIG_EINVALamp or cfunc is NULL or inconsistent.

◆ amp_ext_lookup()

const struct confparams * amp_ext_lookup ( AMP *  amp,
const char *  name 
)

Lookup an extension levels or parameters token by its name and return a pointer to the containing confparams structure member.

Parameters
ampThe #AMP handle.
nameThe extension levels or parameters token name.

Searches the amp_caps::extlevels table and then the amp_caps::extparms table for the token by its name.

Note
As this function is called by amp_ext_token_lookup(), it can be considered a lower level API.
Returns
A pointer to the containing confparams structure member or NULL if nothing found or if amp is NULL or inconsistent.
See also
amp_ext_token_lookup()
Todo:
Should use Lex to speed it up, strcmp() hurts!

◆ amp_ext_lookup_tok()

const struct confparams * amp_ext_lookup_tok ( AMP *  amp,
token_t  token 
)

Search for an extension levels or parameters token by its constant value and return a pointer to the confparams structure member.

Parameters
ampThe #AMP handle.
tokenThe token value (constant).

Searches the amp_caps::extlevels table first and then the amp_caps::extparms for the token by its constant value.

Returns
A pointer to the containing confparams structure member or NULL if nothing found or if amp is NULL or inconsistent.

◆ amp_ext_parm_foreach()

int amp_ext_parm_foreach ( AMP *  amp,
int(*)(AMP *, const struct confparams *, amp_ptr_t)  cfunc,
amp_ptr_t  data 
)

Executes cfunc on all the elements stored in the amp_caps::extparms extension parameters table.

Parameters
ampThe #AMP handle.
cfuncCallback function of each amp_caps::extparms.
dataCookie to be passed to the callback function cfunc.

The callback function cfunc is called until it returns a value which is not strictly positive.

Returns
A zero value which means a normal end of iteration, or a negative value which means an abnormal end.
Return values
RIG_OKAll extension parameters elements successfully processed.
RIG_EINVALamp or cfunc is NULL or inconsistent.

◆ amp_ext_token_lookup()

token_t amp_ext_token_lookup ( AMP *  amp,
const char *  name 
)

Simple search returning the extension token ID associated with name.

Parameters
ampThe #AMP handle.
nameThe token name string to search.
Note
As this function calls amp_ext_lookup(), it can be considered a higher level API.
Returns
The token ID or RIG_CONF_END if there is a lookup failure.
See also
amp_ext_lookup()

◆ amp_get_conf2()

int amp_get_conf2 ( AMP *  amp,
token_t  token,
char *  val,
int  val_len 
)

Query the value of an amplifier configuration parameter.

Parameters
ampThe #AMP handle.
tokenThe token of the parameter to query.
valThe location where to store the value of the configuration token.

Retrieves the value of a configuration parameter associated with token.

Returns
RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKQuerying the parameter was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::get_conf() capability is not available.
See also
amp_set_conf()

◆ amp_get_ext_level()

int amp_get_ext_level ( AMP *  amp,
token_t  level,
value_t val 
)

Query the value of a requested extension levels token.

Parameters
ampThe #AMP handle.
levelThe requested extension levels token.
valThe variable to store the extension level token value.

Query the val corresponding to the extension level token.

Returns
RIG_OK if the operation was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe query was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::get_ext_level() capability is not available.
See also
amp_get_level()

◆ amp_get_freq()

int amp_get_freq ( AMP *  amp,
freq_t freq 
)

Query the operating frequency of the amplifier.

Parameters
ampThe #AMP handle.
freqThe variable to store the operating frequency.

Retrieves the operating frequency from the amplifier.

Returns
RIG_OK if the operation was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe query was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::get_freq() capability is not available.
See also
amp_set_freq()

◆ amp_get_info()

const char * amp_get_info ( AMP *  amp)

Query general information from the amplifier.

Parameters
ampThe #AMP handle.

Retrieves some general information from the amplifier. This can include firmware revision, exact model name, or just nothing.

Returns
A pointer to static memory containing an ASCII nul terminated string (C string) if the operation has been successful, otherwise NULL if amp is NULL or inconsistent or the amp_caps::get_info() capability is not available.

◆ amp_get_level()

int amp_get_level ( AMP *  amp,
setting_t  level,
value_t val 
)

Query the value of a requested level.

Parameters
ampThe #AMP handle.
levelThe requested level.
valThe variable to store the level value.

Query the val corresponding to the level.

Note
val can be any type defined by value_t.
Returns
RIG_OK if the operation was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe query was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::get_level() capability is not available.
See also
amp_get_ext_level()

◆ amp_get_powerstat()

int amp_get_powerstat ( AMP *  amp,
powerstat_t status 
)

Query the power or standby status of the amplifier.

Parameters
ampThe #AMP handle.
statusThe variable to store the amplifier status.

Query the amplifier's power or standby condition. The value stored in status will be one of RIG_POWER_ON, RIG_POWER_OFF and RIG_POWER_OPERATE, RIG_POWER_STANDBY, or RIG_POWER_UNKNOWN.

Returns
RIG_OK if the query was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKQuerying the power/standby state was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::get_powerstat() capability is not available.
See also
amp_set_powerstat()

◆ amp_has_get_level()

setting_t amp_has_get_level ( AMP *  amp,
setting_t  level 
)

Check which level settings can be queried.

Parameters
ampThe #AMP handle.
levelThe level settings bitmap.

Checks if an amplifier is capable of getting a level setting. Since the level is an OR'ed bitwise argument, more than one level can be checked at the same time.

EXAMPLE:

if (amp_has_get_level(my_amp, AMP_LVL_SWR))
my_disp_SWR();
setting_t amp_has_get_level(AMP *amp, setting_t level)
Check which level settings can be queried.
Definition: amp_settings.c:102
Returns
A bit map of supported level settings that can be retrieved, otherwise 0 if none supported or amp is NULL or inconsistent.
See also
amp_has_set_level(), amp_get_level()

◆ amp_has_set_level()

setting_t amp_has_set_level ( AMP *  amp,
setting_t  level 
)

Check which level settings can be set.

Parameters
ampThe #AMP handle.
levelThe level settings bitmap.

Checks if an amplifier is capable of setting a level setting. Since the level is an OR'ed bitwise argument, more than one level can be checked at the same time.

EXAMPLE:

if (amp_has_set_level(my_amp, AMP_LVL_PWR))
my_disp_PWR();
setting_t amp_has_set_level(AMP *amp, setting_t level)
Check which level settings can be set.
Definition: amp_settings.c:69
Returns
A bit map of supported level settings that can be retrieved, otherwise 0 if none supported or amp is NULL or inconsistent.
See also
amp_has_set_level(), amp_set_level()

◆ amp_init()

AMP * amp_init ( amp_model_t  amp_model)

Allocate a new #AMP handle.

Parameters
amp_modelThe amplifier model for this new handle.

Allocates a new #AMP handle and initializes the associated data for amp_model (see amplist.h or ampctl -l).

Returns
Pointer to the #AMP handle otherwise NULL if memory allocation failed or amp_model is unknown, e.g. backend autoload failed.
See also
amp_cleanup(), amp_open()
Todo:
Read the Preferences here!

◆ amp_open()

int amp_open ( AMP *  amp)

Open the communication channel to the amplifier.

Parameters
ampThe #AMP handle of the amplifier to be opened.

Opens the communication channel to an amplifier for which the #AMP handle has been passed.

Returns
RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKCommunication channel successfully opened.
RIG_EINVALamp is NULL or inconsistent.
See also
amp_init(), amp_close()

◆ amp_reset()

int amp_reset ( AMP *  amp,
amp_reset_t  reset 
)

Reset the amplifier.

Parameters
ampThe #AMP handle.
resetThe reset operation to perform.

Perform a reset of the amplifier.

Returns
RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe reset command was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::reset() capability is not available.

◆ amp_set_conf()

int amp_set_conf ( AMP *  amp,
token_t  token,
const char *  val 
)

Set an amplifier configuration parameter.

Parameters
ampThe #AMP handle.
tokenThe token of the parameter to set.
valThe value to set the parameter to.

Sets an amplifier configuration parameter to val.

Returns
RIG_OK if the operation has been successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe parameter was set successfully.
RIG_EINVALamp is NULL or inconsistent or token is invalid.
RIG_ENAVAILamp_caps::set_conf() capability is not available.
See also
amp_get_conf()

◆ amp_set_ext_level()

int amp_set_ext_level ( AMP *  amp,
token_t  level,
value_t  val 
)

Set the value of a requested extension levels token.

Parameters
ampThe #AMP handle.
levelThe requested extension levels token.
valThe variable to set the extension level token value.

Query the val corresponding to the extension level token.

Returns
RIG_OK if the operation was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe query was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::set_ext_level() capability is not available.
See also
amp_set_level()

◆ amp_set_freq()

int amp_set_freq ( AMP *  amp,
freq_t  freq 
)

Set the operating frequency of the amplifier.

Parameters
ampThe #AMP handle.
freqThe operating frequency.

Set the operating frequency of the amplifier. Depending on the amplifier this may simply set the bandpass filters, etc.

Returns
RIG_OK if the operation was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKSetting the frequency was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::set_freq() capability is not available.
See also
amp_get_freq()

◆ amp_set_level()

int amp_set_level ( AMP *  amp,
setting_t  level,
value_t  val 
)

Set the value of a requested level.

Parameters
ampThe #AMP handle.
levelThe requested level.
valThe variable to store the level value.

Set the val corresponding to the level.

Note
val can be any type defined by value_t.
Returns
RIG_OK if the operation was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe query was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::get_level() capability is not available.
See also
amp_set_ext_level()

◆ amp_set_powerstat()

int amp_set_powerstat ( AMP *  amp,
powerstat_t  status 
)

Turn the amplifier On or Off or toggle the Standby or Operate status.

Parameters
ampThe #AMP handle
statusThe powerstat_t setting.

Turns the amplifier On or Off or toggles the Standby or Operate status. See RIG_POWER_ON, RIG_POWER_OFF and RIG_POWER_OPERATE, RIG_POWER_STANDBY for the value of status.

Returns
RIG_OK if the operation was successful, otherwise a negative value if an error occurred (in which case, cause is set appropriately).
Return values
RIG_OKThe requested power/standby state was successful.
RIG_EINVALamp is NULL or inconsistent.
RIG_ENAVAILamp_caps::set_powerstat() capability is not available.
See also
amp_get_powerstat()

◆ amp_token_lookup()

token_t amp_token_lookup ( AMP *  amp,
const char *  name 
)

Search for the token ID associated with an amplifier configuration parameter token name.

Parameters
ampThe #AMP handle.
nameConfiguration parameter token name string.

Searches the backend and frontend configuration parameters tables for the token ID.

Returns
The token ID value or #RIG_CONF_END if the lookup failed.
See also
amp_confparam_lookup()