#include <attenuate.h>

Inheritance diagram for Attenuate:

Collaboration diagram for Attenuate:

Public Member Functions
	Attenuate (void)

	Attenuate (const string &deviceclass, const string &intensityname="intensity", const string &intensityunit="dB", const string &intensityformat="%6.2f", const string &frequencyname="", const string &frequencyunit="Hz", const string &frequencyformat="%7.0f")

virtual	~Attenuate (void)

int	open (Device &att, int line)

virtual int	open (Device &att) override

virtual int	open (const string &device) override

virtual bool	isOpen (void) const

virtual void	close (void)

void	clear (void)

double	minIntensity (double frequency=0.0) const

double	maxIntensity (double frequency=0.0) const

void	intensities (vector< double > &ints, double frequency=0.0) const

virtual void	init (void)

virtual void	save (const string &path) const

int	write (double &intensity, double frequency, double &level)

int	testWrite (double &intensity, double frequency, double &level)

int	mute (void)

int	testMute (void)

int	attenuate (double &level)

int	testAttenuate (double &level)

string	intensityName (void) const

void	setIntensityName (const string &name)

string	intensityUnit (void) const

void	setIntensityUnit (const string &unit)

string	intensityFormat (void) const

void	setIntensityFormat (const string &format)

string	frequencyName (void) const

void	setFrequencyName (const string &name)

string	frequencyUnit (void) const

void	setFrequencyUnit (const string &unit)

string	frequencyFormat (void) const

void	setFrequencyFormat (const string &format)

int	aoChannel (void) const

void	setAOChannel (int channel)

string	aoDevice (void) const

void	setAODevice (const string &deviceid)

Attenuator *	attenuator (void)

const Attenuator *	attenuator (void) const

bool	noAttenuator (void) const

Public Member Functions inherited from Device
	Device (int type=MiscellaneousType)

	Device (const string &deviceclass, int type=MiscellaneousType)

virtual	~Device (void)

virtual int	reset (void)

virtual const Options &	info (void) const

virtual const Options &	settings (void) const

int	deviceType (void) const

string	deviceTypeStr (void) const

string	deviceClass (void) const

string	deviceFile (void) const

string	deviceName (void) const

string	deviceVendor (void) const

string	deviceIdent (void) const

virtual void	setDeviceIdent (const string &ident)

virtual void	clearError (void)

virtual string	errorStr (void) const

void	setErrorStr (const string &strg)

void	addErrorStr (const string &strg)

void	setErrorStr (int errnum)

void	addErrorStr (int errnum)

virtual bool	success (void) const

virtual bool	failed (void) const

Static Public Attributes
static const double	MuteAttenuationLevel = Attenuator::MuteAttenuationLevel

static const double	MuteIntensity = -1.0e37

static const int	NotOpen = Attenuator::NotOpen

static const int	InvalidDevice = Attenuator::InvalidDevice

static const int	ReadError = Device::ReadError

static const int	WriteError = Device::WriteError

static const int	Underflow = Attenuator::Underflow

static const int	Overflow = Attenuator::Overflow

static const int	IntensityUnderflow = -7

static const int	IntensityOverflow = -8

static const int	IntensityError = -9

Static Public Attributes inherited from Device
static const int	NotOpen = -1

static const int	InvalidDevice = -2

static const int	ReadError = -3

static const int	WriteError = -4

static const int	InvalidParam = -5

Protected Member Functions
virtual int	decibel (double intensity, double frequency, double &db) const =0

virtual void	intensity (double &intens, double frequency, double decibel) const =0

virtual void	initOptions () override

Protected Member Functions inherited from Device
void	setDeviceType (int type)

void	setDeviceClass (const string &deviceclass)

void	setDeviceFile (const string &devicefile)

void	setDeviceName (const string &devicename)

void	setDeviceVendor (const string &devicevendor)

void	addInfo (void)

void	lock (void) const

void	unlock (void) const

QMutex *	mutex (void) const

Additional Inherited Members
Public Types inherited from Device
enum	DeviceTypes { MiscellaneousType = 0, AnalogInputType = 1, AnalogOutputType = 2, DigitalIOType = 3, TriggerType = 4, AttenuatorType = 5, AttenuateType = 6, ManipulatorType = 7, TemperatureType = 8, CameraType = 9 }

Static Public Member Functions inherited from Device
static int	deviceTypes (void)

static string	deviceTypeStr (int type)

static string	getErrorStr (int ern)

Protected Attributes inherited from Device
Options	Info

Options	Settings

Detailed Description

Attenuates a single output channel.

Author: Jan Benda

Todo:: check whether we really need the init() function (versus config()!)

This class is an interface for attenuating a single output line. It allows to convert a requested intensity into an attenuation level for the attenuator device. The carrier frequency of the output signal can be used as a parameter for the conversion. You have to reimplement decibel() and intensity() with the required transformation of the intensity into an attenuation level. What physical quantities the intensity and the carrier frequency are depends on the specific implementation of the Attenuate class. The names, units, and formats of the intensity and the frequency can be retrieved by intensityName(), intensityUnit(), intensityFormat(), frequencyName(), frequencyUnit(), and frequencyFormat().

The open() function recognizes the following options:

line: the line on the attenuator
aodevice: the identifier analog output device
aochannel: the channel of the analog output device
intensityname: name of the intensity variable
intensityunit: unit of the intensity variable
intensityformat: format string for the intensity variable
frequencyname: name of the frequency variable
frequencyunit: unit of the frequency variable
frequencyformat: format string for the frequency variable

The function init() is called before the attenuator is used. You can reimplement this function to load calibration data from a file, for example. save() may be called to save some (calibration) data into a file.

Via a constructor or the open()-function a specific attenuation device for a single output line is assigned to the Attenuate-class. The isOpen()-function checks whether the attenuator is valid and opened. With clear() Attenuate can be disconnected from the attenuator. close() additionally closes the associated attenuator. The aoChannel() function returns the number of the channel of the analog output device aoDevice() where the attenuator is connected to.

The attenuation is set by requesting an intensity using write(). This intensity is mapped into an attenuation level in decibel by the function decibel(). The intensity can be any quantity which is most usefull for your application. What exactly the intensity specifies is determined by the implementation of the decibel() function. The decibel() function gets as a second argument a frequency. This second argument can be used as an parameter for the conversion from intensites to attenuation levels. For example, if your output generates a sound wave via a loadspeaker, the necessary attenuation for getting a specific sound intensity depends on the carrierfrequency of your signal.

Attenuators usually can be set to discrete attenuation levels only. If you request a specific intensity via write(), then it is very likely that the actually set attenuation level results in a slightly different intensity. To make this intensity known to the user, write() sets the intensity variable to the actually set intensity. To be able to compute the intensity from the attenuation level you have to implement the intensity()-function as the inverse function of decibel().

To check whether a requested intensity is possible and what intensity would be set without setting the attenuation level, you can use the testWrite()-function. minIntensity() and maxIntensity() return the minimum and maximum possible intensities given the capabilities of the attenuator device. All possible intensities are returned by intensities().

The mute()-function can be used to mute the output line. testMute() checks whether muting of the output line is possible.

Possible return values of write(), testWrite() and mute() are:

0: success
NotOpen: The device driver for the attenuator is not open.
InvalidDevice: An invalid device index is requested, i.e. the requested output line is not supported by the attenuator device.
WriteError: Failed in setting the attenuation level.
Underflow: The requested attenuation level is too high, i.e. the requested signal amplitude is too small.
Overflow: The requested attenuation level is too low, i.e. the requested signal amplitude is too large.
IntensityUnderflow: The requested intensity is too small to be converted into an attenuation level by the decibel()-function.
IntensityOverflow: The requested intensity is too large to be converted into an attenuation level by the decibel()-function.
IntensityError: Another error occured during conversion of an intensity into an attenuation level by the decibel()-function.

In case you want to use a attenuate interface within RELACS, your Attenuate implementation needs to provide a void default constructor (i.e. with no parameters) that does not open the device. Also, include the header file <relacs/relacsplugin.h> and make the Attenuate device known to RELACS with the addAttenuate( ClassNameOfYourAttenuateImplementation, PluginSetName ) macro.

Constructor & Destructor Documentation

Attenuate ( void )

Constructor.

Attenuate	(	const string &	deviceclass,
		const string &	intensityname = `"intensity"`,
		const string &	intensityunit = `"dB"`,
		const string &	intensityformat = `"%6.2f"`,
		const string &	frequencyname = `""`,
		const string &	frequencyunit = `"Hz"`,
		const string &	frequencyformat = `"%7.0f"`
	)

Construct Attenuate with device class deviceclass. The Attenuate implementation defines the intensity as intensityname with unit intensityunit and format intensityformat and uses for the conversion a frequency with name frequencyname, unit freqencyunit and format frequencyformat. An empty frequencyname indicates that a frequency is not used for the conversion of intensity to an attenuation level.

See Also: setDeviceClass()

~Attenuate ( void )

virtual

Destructor.

References Attenuate::close().

Member Function Documentation

int open	(	Device &	att,
		int	line
	)

Assign output line line of the attenuator att to this. Returns zero on success, or InvalidDevice (or any other negative number indicating the error).

See Also: isOpen(), init(), setAODevice(), setAOChannel()

References Device::deviceIdent(), Device::Info, Attenuate::InvalidDevice, Device::isOpen(), relacs::line(), Attenuate::NotOpen, Device::setDeviceFile(), and Device::Settings.

Referenced by Attenuate::open().

int open ( Device & att )

overridevirtual

Evaluates opts, calls open(Device&,int,const Options&), and sets name, unit, and format of intensity and frequency. You certainly do not need to reimplement this function.

Reimplemented from Device.

References relacs::line(), Attenuate::open(), Attenuate::setAOChannel(), Attenuate::setAODevice(), Attenuate::setFrequencyFormat(), Attenuate::setFrequencyName(), Attenuate::setFrequencyUnit(), Attenuate::setIntensityFormat(), Attenuate::setIntensityName(), and Attenuate::setIntensityUnit().

int open ( const string & device )

overridevirtual

Does nothing (needed for compatibility to other devices). Do not reimplement this function.

Reimplemented from Device.

References Device::Info, Attenuate::InvalidDevice, relacs::line(), Attenuate::setAOChannel(), Attenuate::setAODevice(), Device::setDeviceFile(), Attenuate::setFrequencyFormat(), Attenuate::setFrequencyName(), Attenuate::setFrequencyUnit(), Attenuate::setIntensityFormat(), Attenuate::setIntensityName(), Attenuate::setIntensityUnit(), and Device::Settings.

bool isOpen ( void ) const

virtual

True if the hardware driver is open and the device index is supported.

See Also: open()

Implements Device.

References Device::isOpen(), and Attenuator::lines().

Referenced by Acquire::addAttLine().

void close ( void )

virtual

Close the attenuator wrapper and the associated attenuator device.

See Also: clear(), open(), isOpen()

Implements Device.

References Device::close(), Device::Info, Device::isOpen(), and Device::Settings.

Referenced by Attenuate::~Attenuate().

void clear ( void )

Close the attenuator wrapper without closing the associated attenuator device.

See Also: close(), open(), isOpen()

References Device::Info, and Device::Settings.

double minIntensity ( double frequency = 0.0 ) const

Returns the minimum possible intensity that can be set by the current attenuator device at the given stimulus frequency.

See Also: maxIntensity(), intensities()

References Attenuate::intensity(), Attenuator::maxLevel(), and Attenuator::minLevel().

Referenced by Attenuate::init().

double maxIntensity ( double frequency = 0.0 ) const

Returns the maximum possible intensity that can be set by the current attenuator device at the given stimulus frequency.

See Also: minIntensity(), intensities()

References Attenuate::intensity(), Attenuator::maxLevel(), and Attenuator::minLevel().

Referenced by Attenuate::init().

void intensities	(	vector< double > &	ints,
		double	frequency = `0.0`
	)		const

Returns in ints all possible intensities that can be set by the current attenuator device at the given stimulus frequency sorted by increasing intensities.

See Also: minIntensity(), maxIntensity(), lines()

References Attenuate::intensity(), and Attenuator::levels().

void init ( void )

virtual

This function is called after an attenuator is assigned to this class and before the attenuator is used. The default implementation sets the info(). You can reimplement this function to load calibration data, for example. Don't forget to call Attenuate::init() or set info() yourself.

See Also: open()

References Device::addInfo(), Attenuate::aoChannel(), Attenuate::aoDevice(), Device::deviceIdent(), Device::Info, Attenuate::maxIntensity(), and Attenuate::minIntensity().

Referenced by Acquire::addAttLine().

void save ( const string & path ) const

virtual

Save some data into a file in directory path. The default implementation does nothing. However, you can reimplement this function to save calibration data, for example.

int write	(	double &	intensity,
		double	frequency,
		double &	level
	)

Set intensity to intensity. The parameter frequency may be used for calculating the right attenuation level. In most cases frequency might be the carrier frequency of the signal. See intensityName(), intensityUnit(), intensityFormat(), frequencyName(), frequencyUnit(), and frequencyFormat() for the names and the corresponding units and formats of intensity and frequency. The function decibel() is used to calculate the attenuation level. This function might also define an intensity (in addition to MuteIntensity) for which the attenuator is muted. Since attenuators have a certain resolution, the actually set intensity may differ from the requested intensity intensity. The set intensity is returned in intensity and the set attenuation level in level. If you want to mute the output line, call mute().

Returns

0 on success
NotOpen: The device driver for the attenuator is not open.
InvalidDevice: An invalid device index is requested, i.e. the requested output line is not supported by the attenuator device.
WriteError: Failed in setting the attenuation level.
Underflow: The requested attenuation level is too high, i.e. the requested signal amplitude is too small. In this case, the minimum possible intensity is returned.
Overflow: The requested attenuation level is too low, i.e. the requested signal amplitude is too large. In this case, the maximum possible intensity is returned.
IntensityUnderflow: The requested intensity is too small to be converted into an attenuation level by the decibel()-function. In this case, the minimum possible intensity is returned.
IntensityOverflow: The requested intensity is too large to be converted into an attenuation level by the decibel()-function. In this case, the maximum possible intensity is returned.
IntensityError: Another error occured during conversion of an intensity into an attenuation level by the decibel()-function.

See Also: testWrite(), mute(), attenuate(), intensityName(), intensityUnit(), intensityFormat(), frequencyName(), frequencyUnit(), frequencyFormat()

References Attenuator::attenuate(), Attenuate::decibel(), Attenuate::intensity(), Device::isOpen(), Device::NotOpen, and Device::Settings.

int testWrite	(	double &	intensity,
		double	frequency,
		double &	level
	)

Does the same as write() except setting the attenuator. Using this function it can be checked whether the intensities are valid and to what value the intensity will be actually adjusted.

Returns

0 on success
NotOpen: The device driver for the attenuator is not open.
InvalidDevice: An invalid device index is requested, i.e. the requested output line is not supported by the attenuator device.
Underflow: The requested attenuation level is too high, i.e. the requested signal amplitude is too small. In this case, the minimum possible intensity is returned.
Overflow: The requested attenuation level is too low, i.e. the requested signal amplitude is too large. In this case, the maximum possible intensity is returned.
IntensityUnderflow: The requested intensity is too small to be converted into an attenuation level by the decibel()-function. In this case, the minimum possible intensity is returned.
IntensityOverflow: The requested intensity is too large to be converted into an attenuation level by the decibel()-function. In this case, the maximum possible intensity is returned.
IntensityError: Another error occured during conversion of an intensity into an attenuation level by the decibel()-function.

See Also: write(), testMute(), testAttenuate(), intensityName(), intensityUnit(), intensityFormat(), frequencyName(), frequencyUnit(), frequencyFormat()

References Attenuate::decibel(), Attenuate::intensity(), Device::isOpen(), Device::NotOpen, Attenuate::Overflow, Attenuator::testAttenuate(), and Attenuate::Underflow.

int mute ( void )

Mute the output channel.

Returns

0 on success
NotOpen: The device driver for the attenuator is not open.
InvalidDevice: An invalid device index is requested, i.e. the requested output line is not supported by the attenuator device.
WriteError: Failed in setting the attenuation level.

See Also: testMute(), write(), testWrite()

References Device::isOpen(), Attenuator::mute(), Device::NotOpen, and Device::Settings.

int testMute ( void )

Test muting the output channel.

Returns

0 on success
NotOpen: The device driver for the attenuator is not open.
InvalidDevice: An invalid device index is requested, i.e. the requested output line is not supported by the attenuator device.
WriteError: Failed in setting the attenuation level.

See Also: mute(), write(), testWrite()

References Device::isOpen(), Device::NotOpen, and Attenuator::testMute().

int attenuate ( double & level )

Set the attenuation level directly to level decibel. level can also be set to MuteAttenuationLevel for requesting to mute the attenuator. Returns the actually set level in level. In case the attenuator was muted, MuteAttenuationLevel is returned in level. If the requested attenuation level is too high or too low (Underflow or Overflow), then the maximum or minimum possible attenuation level is set and returned in level.

Returns

0 on success
NotOpen: The device driver for the attenuator is not open.
InvalidDevice: An invalid device index is requested, i.e. the requested output line is not supported by the attenuator device.
WriteError: Failed in setting the attenuation level.
Underflow: The requested attenuation level is too high, i.e. the requested signal amplitude is too small.
Overflow: The requested attenuation level is too low, i.e. the requested signal amplitude is too large.

See Also: testAttenuate(), write(), mute()

References Attenuator::attenuate(), Device::isOpen(), Device::NotOpen, and Device::Settings.

int testAttenuate ( double & level )

Tests setting the attenuation level directly to level decibel. level can also be set to MuteAttenuationLevel for requesting to mute the attenuator. Returns the level that would be set in level. In case the attenuator would be muted, MuteAttenuationLevel is returned in level. If the requested attenuation level is too high or too low (Underflow or Overflow), then the maximum or minimum possible attenuation level is returned in level.

Returns

0 on success
NotOpen: The device driver for the attenuator is not open.
InvalidDevice: An invalid device index is requested, i.e. the requested output line is not supported by the attenuator device.
Underflow: The requested attenuation level is too high, i.e. the requested signal amplitude is too small.
Overflow: The requested attenuation level is too low, i.e. the requested signal amplitude is too large.

See Also: attenuate(), testWrite(), testMute()

References Device::isOpen(), Device::NotOpen, Attenuate::Overflow, Attenuator::testAttenuate(), and Attenuate::Underflow.

string intensityName ( void ) const

The name of the intensity the specific implementation of Attenuate is using.

See Also: setIntensityName(), intensityUnit(), intensityFormat(), frequencyName(), write(), decibel()

void setIntensityName ( const string & name )

Set the name of the intensity the specific implementation of Attenuate is using to name.

See Also: intensityName(), setIntensityUnit(), setIntensityFormat(), setFrequencyName(), write(), decibel()

Referenced by Attenuate::open().

string intensityUnit ( void ) const

The unit of the intensity the specific implementation of Attenuate is using.

See Also: setIntensityUnit(), intensityName(), intensityFormat(), frequencyUnit(), write(), decibel()

void setIntensityUnit ( const string & unit )

Set the unit of the intensity the specific implementation of Attenuate is using to unit.

See Also: intensityUnit(), setIntensityName(), setIntensityFormat(), setFrequencyUnit(), write(), decibel()

Referenced by Attenuate::open().

string intensityFormat ( void ) const

A C-style format string to be used for formatting the intensity the specific implementation of Attenuate is using.

See Also: setIntensityFormat(), intensityName(), intensityUnit(), frequencyFormat(), write(), decibel()

void setIntensityFormat ( const string & format )

Set the format of the intensity the specific implementation of Attenuate is using to format.

See Also: intensityFormat(), setIntensityName(), setIntensityUnit(), setFrequencyFormat(), write(), decibel()

Referenced by Attenuate::open().

string frequencyName ( void ) const

The name of the frequency the specific implementation of Attenuate is using for computing the intensity. An empty frequencyName() indicates that a frequency is not used for the conversion of intensity in an attenuation level.

See Also: setFrequencyName(), frequencyUnit(), intensityName(), write(), decibel()

void setFrequencyName ( const string & name )

Set the name of the frequency the specific implementation of Attenuate is using for computing the intensity to name.

See Also: frequencyName(), setFrequencyUnit(), setIntensityName(), write(), decibel()

Referenced by Attenuate::open().

string frequencyUnit ( void ) const

The unit of the frequency the specific implementation of Attenuate is using for computing the intensity.

See Also: setFrequencyUnit(), frequencyName(), intensityUnit(), write(), decibel()

void setFrequencyUnit ( const string & unit )

Set the unit of the frequency the specific implementation of Attenuate is using for computing the intensity to unit.

See Also: frequencyUnit(), setFrequencyName(), setIntensityUnit(), write(), decibel()

Referenced by Attenuate::open().

string frequencyFormat ( void ) const

A C-style format string to be used for formatting the frequency the specific implementation of Attenuate is using for computing the intensity.

See Also: setFrequencyFormat(), frequencyName(), frequencyUnit(), intensityFormat(), write(), decibel()

void setFrequencyFormat ( const string & format )

Set the format of the frequency the specific implementation of Attenuate is using for computing the intensity to format.

See Also: frequencyFormat(), setFrequencyName(), setFrequencyUnit(), setIntensityFormat(), write(), decibel()

Referenced by Attenuate::open().

int aoChannel ( void ) const

Returns the channel number of the analog output device which is attenuated by this instance of the Attenuate class.

See Also: setAOChannel(), aoDevice(), open()

Referenced by Attenuate::init().

void setAOChannel ( int channel )

Set the channel number for the analog output device which should be attenuated by this instance of the Attenuate class to channel.

See Also: aoChannel(), setAODevice(), open()

Referenced by Acquire::addAttLine(), and Attenuate::open().

string aoDevice ( void ) const

Returns the identifier string of the analog output device which is attenuated by this instance of the Attenuate class.

See Also: setAODevice(), aoChannel(), open()

Referenced by Acquire::addAttLine(), and Attenuate::init().

void setAODevice ( const string & deviceid )

Set the identifier string for the analog output device which should be attenuated by this instance of the Attenuate class to channel.

See Also: aoDevice(), setAOChannel(), open()

Referenced by Acquire::addAttLine(), and Attenuate::open().

Attenuator * attenuator ( void )

Returns the attenuator device that is used by this Attenuate class.

const Attenuator * attenuator ( void ) const

Returns the attenuator device that is used by this Attenuate class.

bool noAttenuator ( void ) const

Returns true if no attenuator is actually used.

virtual int decibel	(	double	intensity,
		double	frequency,
		double &	db
	)		const

protectedpure virtual

Transforms the requested intensity intensity for the carrier frequency frequency of the signal into an attenuation level db for the attenuator. This function is used by write() to set the attenuator to the requested intensity. The implementation of this function must set db to MuteAttenuationLevel in case intensity equals MuteIntensity. For certain other values of intensity db might be also set to MuteAttenuationLevel for muting the attenuator. If the computation of db fails, db should be set to a meaningful value.

Returns

0 on success
IntensityUnderflow: The requested intensity is too small to be converted into an attenuation level. In this case, the attenuation db corresponding to the minimum possible intensity is returned.
IntensityOverflow: The requested intensity is too large to be converted into an attenuation level. In this case, the attenuation db corresponding to the maximum possible intensity is returned.
IntensityError: Another error occured during conversion of an intensity into an attenuation level.

See Also: write(), testWrite(), intensity(), intensityName(), intensityUnit(), intensityFormat(), frequencyName(), frequencyUnit(), frequencyFormat()

Referenced by Attenuate::testWrite(), and Attenuate::write().

virtual void intensity	(	double &	intens,
		double	frequency,
		double	decibel
	)		const

protectedpure virtual

Transform the attenuation level decibel for the carrier frequency frequency of the signal into the intensity intens. This function should be the inverse function of decibel() and is used by write() to return the actually set intensity from the set attenuation level. If the attenuator was muted (decibel equals MuteAttenuationLevel), intens is set to MuteIntensity.