Files
file	amplifier.h
	Hamlib amplifier data structures.

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.

Data Structures
struct	amp_caps
	Amplifier capabilities. More...

struct	amp_state
	Amplifier state structure. More...

struct	amp
	Master amplifier structure. More...

Macros
#define	NETAMPCTL_RET "RPRT "
	The token in the netampctl protocol for returning an error condition code.

#define	amp_debug rig_debug
	Convenience macro for generating debugging messages. More...

#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...

Typedefs
typedef struct amp	AMP
	Main amplifier handle type definition. More...

typedef float	swr_t
	Type definition for SWR (Standing Wave Ratio). More...

typedef int	tune_value_t
	Type definition for the transmatch tuning values of capacitance and inductance. More...

typedef int	amp_model_t
	Convenience type definition for an amplifier model.

Enumerations
enum	amp_type_t { AMP_FLAG_1 = (1 << 1) , AMP_FLAG_2 = (1 << 2) }
	Amplifier type flags. More...

Functions
const struct confparams *	amp_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_conf (AMP amp, token_t token, char val)
	Query the value of an amplifier configuration parameter. 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_get_level (AMP amp, setting_t level, value_t val)
	Query the value of a requested level. 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 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. More...

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. 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_debug

#define amp_debug rig_debug

Convenience macro for generating debugging messages.

This is an alias of the rig_debug() function call and is used in the same manner.

◆ 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

typedef struct amp AMP

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.

◆ swr_t

typedef float swr_t

Type definition for SWR (Standing Wave Ratio).

The swr_t type is used as a parameter for the amp_get_swr() function.

The unit of 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.

◆ tune_value_t

typedef float tune_value_t

Type definition for the transmatch tuning values of capacitance and inductance.

The tune_value_t type is used as a parameter for amp_get_level().

The unit of tune_value_t is picoFarads (pF) or nanoHenrys (nH).

Enumeration Type Documentation

◆ amp_type_t

enum amp_type_t

Amplifier type flags.

Enumerator
AMP_FLAG_1	TBD
AMP_FLAG_2	TBD

Function Documentation

◆ amp_cleanup()

int amp_cleanup ( AMP * amp )

Release an AMP handle and free associated memory.

Parameters

amp	The 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_EINVAL	amp 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

amp	The 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_OK	Communication channel successfully closed.
RIG_EINVAL	amp 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

amp	The AMP handle.
name	Configuration 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

amp	The AMP handle.
cfunc	Callback function of each amp_caps::extlevels.
data	Cookie 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_OK	All extension levels elements successfully processed.
RIG_EINVAL	amp 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

amp	The AMP handle.
name	The 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

amp	The AMP handle.
token	The 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

amp	The AMP handle.
cfunc	Callback function of each amp_caps::extparms.
data	Cookie 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_OK	All extension parameters elements successfully processed.
RIG_EINVAL	amp 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

amp	The AMP handle.
name	The 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_conf()

int amp_get_conf	(	AMP *	amp,
		token_t	token,
		char *	val
	)

Query the value of an amplifier configuration parameter.

Parameters

amp	The AMP handle.
token	The token of the parameter to query.
val	The 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_OK	Querying the parameter was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_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

amp	The AMP handle.
level	The requested extension levels token.
val	The 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_OK	The query was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_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

amp	The AMP handle.
freq	The 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_OK	The query was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_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

amp	The 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

amp	The AMP handle.
level	The requested level.
val	The 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_OK	The query was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_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

amp	The AMP handle.
status	The 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_OK	Querying the power/standby state was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_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

amp	The AMP handle.
level	The 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();

amp_has_get_level

setting_t amp_has_get_level(AMP *amp, setting_t level)

Check which level settings can be queried.

Definition: amp_settings.c:73

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_init()

AMP* amp_init ( amp_model_t amp_model )

Allocate a new AMP handle.

Parameters

amp_model The 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

amp	The 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_OK	Communication channel succesfully opened.
RIG_EINVAL	amp 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

amp	The AMP handle.
reset	The 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_OK	The reset command was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_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

amp	The AMP handle.
token	The token of the parameter to set.
val	The 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_OK	The parameter was set successfully.
RIG_EINVAL	amp is NULL or inconsistent or token is invalid.
RIG_ENAVAIL	amp_caps::set_conf() capability is not available.

See also: amp_get_conf()

◆ amp_set_freq()

int amp_set_freq	(	AMP *	amp,
		freq_t	freq
	)

Set the operating frequency of the amplifier.

Parameters

amp	The AMP handle.
freq	The 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_OK	Setting the frequency was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_caps::set_freq() capability is not available.

See also: amp_get_freq()

◆ 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

amp	The AMP handle
status	The 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_OK	The requested power/standby state was successful.
RIG_EINVAL	amp is NULL or inconsistent.
RIG_ENAVAIL	amp_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

amp	The AMP handle.
name	Configuration 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()

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Amplifier interface

Macro Definition Documentation

◆ amp_debug

◆ AMP_MODEL_DUMMY

◆ AMP_MODEL_ELECRAFT_KPA1500

◆ AMP_MODEL_NETAMPCTL

◆ AMP_MODEL_NONE

Typedef Documentation

◆ AMP

◆ swr_t

◆ tune_value_t

Enumeration Type Documentation

◆ amp_type_t

Function Documentation

◆ amp_cleanup()

◆ amp_close()

◆ amp_confparam_lookup()

◆ amp_ext_level_foreach()

◆ amp_ext_lookup()

◆ amp_ext_lookup_tok()

◆ amp_ext_parm_foreach()

◆ amp_ext_token_lookup()

◆ amp_get_conf()

◆ amp_get_ext_level()

◆ amp_get_freq()

◆ amp_get_info()

◆ amp_get_level()

◆ amp_get_powerstat()

◆ amp_has_get_level()

◆ amp_init()

◆ amp_open()

◆ amp_reset()

◆ amp_set_conf()

◆ amp_set_freq()

◆ amp_set_powerstat()

◆ amp_token_lookup()