Squidstat API User Manual
Loading...
Searching...
No Matches
AisInstrumentHandler Class Referencefinal

this class provides control of the device including starting, pausing, resuming and stopping an experiment on a channel as well as reading the data and other controls of the device. More...

#include <AisInstrumentHandler.h>

Inheritance diagram for AisInstrumentHandler:

Signals

void deviceDisconnected ()
 a signal that is emitted if the device associated with this handler has been disconnected. More...
 
void groundFloatStateChanged (bool grounded)
 a signal that is emitted when the floating ground connection state has changed. More...
 
void experimentNewElementStarting (uint8_t channel, const AisExperimentNode &stepInfo)
 a signal that is emitted whenever a new elemental experiment has started. More...
 
void activeDCDataReady (uint8_t channel, const AisDCData &DCData)
 a signal that is emitted whenever new DC data for an active experiment are ready. More...
 
void idleDCDataReady (uint8_t channel, const AisDCData &DCData)
 a signal that is emitted whenever new DC data are ready when the device is in an idle state. More...
 
void recoveryDCDataReady (uint8_t channel, const AisDCData &DCData)
 a signal that is emitted whenever new DC recovery data are ready. More...
 
void activeACDataReady (uint8_t channel, const AisACData &ACData)
 a signal that is emitted whenever new AC data for an active experiment are ready. More...
 
void recoveryACDataReady (uint8_t channel, const AisACData &ACData)
 a signal that is emitted whenever new AC recovery data are ready. More...
 
void experimentStopped (uint8_t channel)
 a signal that is emitted whenever an experiment was stopped manually or has completed. More...
 
void experimentPaused (uint8_t channel)
 a signal that is emitted whenever an experiment was paused. More...
 
void experimentResumed (uint8_t channel)
 a signal that is emitted whenever an experiment was resumed. More...
 
void recoverDataErased (bool successful)
 a signal that is emitted whenever data erase process is completed. More...
 
void deviceError (uint8_t channel, const QString &error)
 a signal that is emitted whenever device send any critical error. More...
 

Public Member Functions

AisErrorCode uploadExperimentToChannel (uint8_t channel, std::shared_ptr< AisExperiment > experiment) const
 upload an already created custom experiment to a specific channel on the device. More...
 
AisErrorCode uploadExperimentToChannel (uint8_t channel, const AisExperiment &experiment) const
 upload an already created custom experiment to a specific channel on the device. More...
 
AisErrorCode startUploadedExperiment (uint8_t channel) const
 start the previously uploaded experiment on the specific channel. More...
 
AisErrorCode startIdleSampling (uint8_t channel) const
 start idle sampling when an experiment is neither uploaded nor running on the specified channel. More...
 
AisErrorCode skipExperimentStep (uint8_t channel) const
 skip the current experiment step and proceed to the next. More...
 
AisErrorCode pauseExperiment (uint8_t channel) const
 pause a running experiment on the channel. More...
 
AisErrorCode resumeExperiment (uint8_t channel) const
 resume a paused experiment on the channel. More...
 
AisErrorCode stopExperiment (uint8_t channel) const
 stop a running or a paused experiment on the channel. More...
 
double getExperimentUTCStartTime (uint8_t channel) const
 get UTC time for the start of the experiment in seconds. More...
 
AisErrorCode setIRComp (uint8_t channel, double uncompensatedResistance, double compensationLevel) const
 set IR compensation. More...
 
AisErrorCode setCompRange (uint8_t channel, const AisCompRange &compRange) const
 set a compensation range with stability factor and bandwidth index. More...
 
int8_t setLinkedChannels (std::vector< uint8_t > channels) const
 connect several channels together in parallel mode. More...
 
int8_t setBipolarLinkedChannels (std::vector< uint8_t > channels) const
 connect two channels together in bipolar mode. More...
 
bool hasBipolarMode (uint8_t channel) const
 tells whether the given channel is bipolar mode More...
 
std::vector< uint8_t > getLinkedChannels (uint8_t channel) const
 get a list of channels linked to the given channel. More...
 
bool isChannelBusy (uint8_t channel) const
 tells whether the given channel is busy or not. More...
 
bool isChannelPaused (uint8_t channel) const
 tells whether the given channel has a paused experiment or not. More...
 
std::vector< uint8_t > getFreeChannels () const
 get a list of the currently free channels. More...
 
int getNumberOfChannels () const
 get the number of all the channels on this device. More...
 
AisErrorCode eraseRecoverData () const
 delete the recover data from device. More...
 
AisErrorCode startManualExperiment (uint8_t channel) const
 start a manual experiment. More...
 
AisErrorCode setManualModeSamplingInterval (uint8_t channel, double value) const
 set an interval for sampling the data. More...
 
AisErrorCode setManualModeOCP (uint8_t channel) const
 set open-circuit potential mode. More...
 
AisErrorCode setManualModeConstantVoltage (uint8_t channel, double value) const
 set constant voltage for the manual experiment. More...
 
AisErrorCode setManualModeConstantVoltage (uint8_t channel, double value, int currentRangeIndex) const
 set constant voltage for the manual experiment and also set a manual current range. More...
 
AisErrorCode setManualModeCurrentRange (uint8_t channel, int currentRangeIndex) const
 set the current range for the manual experiment. Once a range is set, autoranging capability is turned off. That means that during potentiostatic control, the current range may range up if necessary, but it will not drop below the user-set range. During galvanostatic control, the lowest current range that contains the designated setpoint will be chosen, provided it is not lower than the user-set range. More...
 
AisErrorCode setManualModeCurrentAutorange (uint8_t channel) const
 enable current autoranging for the manual experiment. More...
 
AisErrorCode setManualModeVoltageRange (uint8_t channel, int voltageRangeIndex) const
 set the voltage range for the manual experiment. Once a range is set, autoranging capability is turned off. That means that during galvanostatic control, the voltage range may range up if necessary, but it will not drop below the user-set range. During potentiostatic control, the lowest voltage range that contains the designated setpoint will be chosen, provided it is not lower than the user-set range. More...
 
AisErrorCode setManualModeVoltageAutorange (uint8_t channel) const
 enable voltage autoranging for the manual experiment. More...
 
AisErrorCode setManualModeConstantCurrent (uint8_t channel, double value) const
 set constant current for the manual experiment. More...
 
std::vector< std::pair< double, double > > getManualModeCurrentRangeList (uint8_t channel) const
 get a list of the applicable current ranges to the given channel specific to your device. More...
 
std::vector< std::pair< double, double > > getManualModeVoltageRangeList (uint8_t channel) const
 get a list of the applicable voltage ranges to the given channel specific to your device. More...
 

Detailed Description

this class provides control of the device including starting, pausing, resuming and stopping an experiment on a channel as well as reading the data and other controls of the device.

You may get an instrument handler instance of this class by calling AisDeviceTracker::getInstrumentHandler where you can get the device name either by calling AisDeviceTracker::getConnectedDevices or whenever the signal newDeviceConnected() is emitted.

Member Function Documentation

◆ activeACDataReady

void AisInstrumentHandler::activeACDataReady ( uint8_t  channel,
const AisACData ACData 
)
signal

a signal that is emitted whenever new AC data for an active experiment are ready.

Parameters
channelthe channel number from which the AC data arrived.
ACDatathe AC data that just arrived.

◆ activeDCDataReady

void AisInstrumentHandler::activeDCDataReady ( uint8_t  channel,
const AisDCData DCData 
)
signal

a signal that is emitted whenever new DC data for an active experiment are ready.

Parameters
channelthe channel number from which the DC data arrived.
DCDatathe DC data that just arrived.

◆ deviceDisconnected

void AisInstrumentHandler::deviceDisconnected ( )
signal

a signal that is emitted if the device associated with this handler has been disconnected.

◆ deviceError

void AisInstrumentHandler::deviceError ( uint8_t  channel,
const QString &  error 
)
signal

a signal that is emitted whenever device send any critical error.

Parameters
channelthe channel number at which error rise.
errorinformation about error message.
Note
stop experiment command will automatilcally send on channel.

◆ eraseRecoverData()

AisErrorCode AisInstrumentHandler::eraseRecoverData ( ) const

delete the recover data from device.

Returns
AisErrorCode::Success if request is sucessfully send for delete the data. If not successful, possible returned errors are:

◆ experimentNewElementStarting

void AisInstrumentHandler::experimentNewElementStarting ( uint8_t  channel,
const AisExperimentNode stepInfo 
)
signal

a signal that is emitted whenever a new elemental experiment has started.

Parameters
channelthe channel number on which the experiment was started.
stepInfoinformation regarding the current step.
See also
AisExperimentNode

◆ experimentPaused

void AisInstrumentHandler::experimentPaused ( uint8_t  channel)
signal

a signal that is emitted whenever an experiment was paused.

Parameters
channelthe channel on which the experiment was paused.

◆ experimentResumed

void AisInstrumentHandler::experimentResumed ( uint8_t  channel)
signal

a signal that is emitted whenever an experiment was resumed.

Parameters
channelthe channel on which the experiment was resumed.

◆ experimentStopped

void AisInstrumentHandler::experimentStopped ( uint8_t  channel)
signal

a signal that is emitted whenever an experiment was stopped manually or has completed.

Parameters
channelthe channel on which the experiment has stopped.

◆ getExperimentUTCStartTime()

double AisInstrumentHandler::getExperimentUTCStartTime ( uint8_t  channel) const

get UTC time for the start of the experiment in seconds.

This will give the time in seconds between the origin of UTC time and the start of the experiment aka Unix Epoch.

Parameters
channelthe channel for which to get the start time of the experiment.
Returns
the Unix Epoch up to the start of the experiment in seconds.

◆ getFreeChannels()

std::vector< uint8_t > AisInstrumentHandler::getFreeChannels ( ) const

get a list of the currently free channels.

Returns
a list of the currently free channels. If all channels are busy, an empty list is returned.

◆ getLinkedChannels()

std::vector< uint8_t > AisInstrumentHandler::getLinkedChannels ( uint8_t  channel) const

get a list of channels linked to the given channel.

Parameters
channela valid channel number to find which other channels are linked to it.
Returns
a list of channels linked to the channel parameter.

◆ getManualModeCurrentRangeList()

std::vector< std::pair< double, double > > AisInstrumentHandler::getManualModeCurrentRangeList ( uint8_t  channel) const

get a list of the applicable current ranges to the given channel specific to your device.

The list is indexed, with each index containing a range with minimum and maximum current for the range. You can pass the index of the desired current range to setManualModeConstantVoltage or setManualModeConstantCurrent.

Parameters
channela valid channel number for which to check the current range.
Returns
a list of the of the applicable current ranges to the given channel specific to your device.

◆ getManualModeVoltageRangeList()

std::vector< std::pair< double, double > > AisInstrumentHandler::getManualModeVoltageRangeList ( uint8_t  channel) const

get a list of the applicable voltage ranges to the given channel specific to your device.

The list is indexed, with each index containing a range with minimum and maximum voltage for the range. You can pass the index of the desired current range to setManualModeConstantVoltage or setManualModeConstantCurrent.

Parameters
channela valid channel number for which to check the current range.
Returns
a list of the of the applicable current ranges to the given channel specific to your device.

◆ getNumberOfChannels()

int AisInstrumentHandler::getNumberOfChannels ( ) const

get the number of all the channels on this device.

Returns
the number of channels on the connected device. If no device found, -1 will be returned.

◆ groundFloatStateChanged

void AisInstrumentHandler::groundFloatStateChanged ( bool  grounded)
signal

a signal that is emitted when the floating ground connection state has changed.

Parameters
groundedtrue if there is a connection to ground and false if the ground has disconnected.

◆ hasBipolarMode()

bool AisInstrumentHandler::hasBipolarMode ( uint8_t  channel) const

tells whether the given channel is bipolar mode

Parameters
channelthe channel number to check if it is bipolar mode
Returns
true only if given a valid channel number that has bipolar mode.

◆ idleDCDataReady

void AisInstrumentHandler::idleDCDataReady ( uint8_t  channel,
const AisDCData DCData 
)
signal

a signal that is emitted whenever new DC data are ready when the device is in an idle state.

A manual experiment displays real time values. These values are displayed even if the channel does not have an experiment running on it.

Parameters
channelthe channel number from which the DC data arrived.
DCDatathe DC data that just arrived.

◆ isChannelBusy()

bool AisInstrumentHandler::isChannelBusy ( uint8_t  channel) const

tells whether the given channel is busy or not.

Parameters
channelthe channel number to check if it is busy or not.
Returns
true only if given a valid channel number that has either a running or a paused experiment.

◆ isChannelPaused()

bool AisInstrumentHandler::isChannelPaused ( uint8_t  channel) const

tells whether the given channel has a paused experiment or not.

Parameters
channelthe channel number to check if it has a paused experiment.
Returns
true only if given a valid channel number that has an experiment that has been paused.

◆ pauseExperiment()

AisErrorCode AisInstrumentHandler::pauseExperiment ( uint8_t  channel) const

pause a running experiment on the channel.

Parameters
channelthe channel number to pause the experiment on.
Returns
true if an experiment was successfully paused on the channel and false otherwise. If not successful, possible returned errors are:

This will return AisErrorCode::Success only if there is currently a running experiment on a valid channel on a connected device.

◆ recoverDataErased

void AisInstrumentHandler::recoverDataErased ( bool  successful)
signal

a signal that is emitted whenever data erase process is completed.

Parameters
successfulis true on erased correctly, and false on data is not erased.

◆ recoveryACDataReady

void AisInstrumentHandler::recoveryACDataReady ( uint8_t  channel,
const AisACData ACData 
)
signal

a signal that is emitted whenever new AC recovery data are ready.

Parameters
channelthe channel number from which the AC data are recovered from.
ACDatathe AC data that just arrived.

◆ recoveryDCDataReady

void AisInstrumentHandler::recoveryDCDataReady ( uint8_t  channel,
const AisDCData DCData 
)
signal

a signal that is emitted whenever new DC recovery data are ready.

Parameters
channelthe channel number from which the DC data are recovered from.
DCDatathe DC data that just arrived.

◆ resumeExperiment()

AisErrorCode AisInstrumentHandler::resumeExperiment ( uint8_t  channel) const

resume a paused experiment on the channel.

Parameters
channelthe channel number to resume the experiment on.
Returns
AisErrorCode::Success if an experiment was successfully resumed on the channel. If not successful, possible returned errors are:

This will return AisErrorCode::Success only if there is currently a paused experiment on a valid channel on a connected device.

◆ setBipolarLinkedChannels()

int8_t AisInstrumentHandler::setBipolarLinkedChannels ( std::vector< uint8_t >  channels) const

connect two channels together in bipolar mode.

You may combine two channels to expand the voltage range to include negative voltages. Note that this is only applicable to the cycler model. For 4 channel Cycler models, you can combine channels 1 and 2 or channels 3 and 4. You cannot use any other channel combinations.

Parameters
channelsa list of two channels to be oprate in bipolar mode.
Returns
the master channel out of the given list of two channels. The master channel is your interface to upload an experiment to and then control it. If not successful set in bipolar mode, possible returned errors as -1.
Note
this functionality is only applicable to the cycler model.

◆ setCompRange()

AisErrorCode AisInstrumentHandler::setCompRange ( uint8_t  channel,
const AisCompRange compRange 
) const

set a compensation range with stability factor and bandwidth index.

Parameters
channelthe channel for which to set the compensation range.
compRangean object of type compRange that is initialized with a stability factor (0-10) and a bandwidth index (0-10).
Returns
AisErrorCode::Success if setting the IR compensation was successful. If not successful, possible returned errors are:
See also
AisCompRange

◆ setIRComp()

AisErrorCode AisInstrumentHandler::setIRComp ( uint8_t  channel,
double  uncompensatedResistance,
double  compensationLevel 
) const

set IR compensation.

Parameters
channelthe channel for which to set the IR compensation.
uncompensatedResistancethe value of the uncompensated resistance in Ohms.
compensationLevelthe compensation percentage (0%-100%). This is unit-less.
Returns
AisErrorCode::Success if setting the IR compensation was successful. If not successful, possible returned errors are:

◆ setLinkedChannels()

int8_t AisInstrumentHandler::setLinkedChannels ( std::vector< uint8_t >  channels) const

connect several channels together in parallel mode.

You may connect a list of channels so you can get a higher combined output current of all channels. Note that this is only applicable to the cycler model.

Parameters
channelsa list of channels to be linked.
Returns
the master channel out of the given list of channels. The master channel is your interface to upload an experiment to and then control it.
Note
this functionality is only applicable to the cycler model.

◆ setManualModeConstantCurrent()

AisErrorCode AisInstrumentHandler::setManualModeConstantCurrent ( uint8_t  channel,
double  value 
) const

set constant current for the manual experiment.

Parameters
channela valid channel number to set a constant voltage for.
valuethe value to set the constant current in Amps.
Returns
AisErrorCode::Success if setting the constant current was successful. If not successful, possible returned errors are:

◆ setManualModeConstantVoltage() [1/2]

AisErrorCode AisInstrumentHandler::setManualModeConstantVoltage ( uint8_t  channel,
double  value 
) const

set constant voltage for the manual experiment.

Parameters
channela valid channel number to set a constant voltage for.
valuethe value to set the constant voltage in volts.
Returns
AisErrorCode::Success if setting the constant voltage was successful. If not successful, possible returned errors are:

◆ setManualModeConstantVoltage() [2/2]

AisErrorCode AisInstrumentHandler::setManualModeConstantVoltage ( uint8_t  channel,
double  value,
int  currentRangeIndex 
) const

set constant voltage for the manual experiment and also set a manual current range.

Parameters
channela valid channel number to set a constant voltage for.
valuethe value to set the constant voltage in volts.
currentRangeIndexthe index of the desired current range.
Returns
AisErrorCode::Success if setting the constant voltage was successful. You can get a list of the available ranges for your model by calling getManualModeCurrentRangeList. If not successful, possible returned errors are:

◆ setManualModeCurrentAutorange()

AisErrorCode AisInstrumentHandler::setManualModeCurrentAutorange ( uint8_t  channel) const

enable current autoranging for the manual experiment.

Parameters
channela valid channel number to enable current autoranging for.
Returns
AisErrorCode::Success if enabling current autoranging successful. If not successful, possible returned errors are:

◆ setManualModeCurrentRange()

AisErrorCode AisInstrumentHandler::setManualModeCurrentRange ( uint8_t  channel,
int  currentRangeIndex 
) const

set the current range for the manual experiment. Once a range is set, autoranging capability is turned off. That means that during potentiostatic control, the current range may range up if necessary, but it will not drop below the user-set range. During galvanostatic control, the lowest current range that contains the designated setpoint will be chosen, provided it is not lower than the user-set range.

Parameters
channela valid channel number to set the current range for.
currentRangeIndexthe index of the desired current range.
Returns
AisErrorCode::Success if setting the current range was successful. You can get a list of the available ranges for your model by calling getManualModeCurrentRangeList. If not successful, possible returned errors are:

◆ setManualModeOCP()

AisErrorCode AisInstrumentHandler::setManualModeOCP ( uint8_t  channel) const

set open-circuit potential mode.

To apply the set potential or current, leave the open circuit potential mode off. This operation is reversed automatically when calling either setManualModeConstantVoltage() or setManualModeConstantCurrent()

Parameters
channela valid channel number to set open circuit mode on.
Returns
AisErrorCode::Success if turning on the open circuit mode was successful. If not successful, possible returned errors are:

◆ setManualModeSamplingInterval()

AisErrorCode AisInstrumentHandler::setManualModeSamplingInterval ( uint8_t  channel,
double  value 
) const

set an interval for sampling the data.

Parameters
channelthe channel to set the sampling interval for.
valuethe value for the sampling interval in seconds.
Returns
AisErrorCode::Success if the operation was set successfully. If not successful, possible returned errors are:

◆ setManualModeVoltageAutorange()

AisErrorCode AisInstrumentHandler::setManualModeVoltageAutorange ( uint8_t  channel) const

enable voltage autoranging for the manual experiment.

Parameters
channela valid channel number to enable voltage autoranging for.
Returns
AisErrorCode::Success if enabling voltage autoranging successful. If not successful, possible returned errors are:

◆ setManualModeVoltageRange()

AisErrorCode AisInstrumentHandler::setManualModeVoltageRange ( uint8_t  channel,
int  voltageRangeIndex 
) const

set the voltage range for the manual experiment. Once a range is set, autoranging capability is turned off. That means that during galvanostatic control, the voltage range may range up if necessary, but it will not drop below the user-set range. During potentiostatic control, the lowest voltage range that contains the designated setpoint will be chosen, provided it is not lower than the user-set range.

Parameters
channela valid channel number to set the voltage range for.
voltageRangeIndexthe index of the desired voltage range.
Returns
AisErrorCode::Success if setting the voltage rnage was successful. You can get a list of the available ranges for your model by calling getManualModeVoltageRangeList. If not successful, possible returned errors are:

◆ skipExperimentStep()

AisErrorCode AisInstrumentHandler::skipExperimentStep ( uint8_t  channel) const

skip the current experiment step and proceed to the next.

When running an element that has several steps like going from CC to CV, then skipping the step goes to the next step within the element. When having several elements in the custom experiment and the current element has one step or we are at the last step within the element, then skipping the step results in going to the next element. If this is the final step of the final element, the experiment will stop.

Parameters
channela valid channel number with an experiment to skip the step.
Returns
AisErrorCode::Success the experiment step was successfully skipped If not successful, possible returned errors are:

◆ startIdleSampling()

AisErrorCode AisInstrumentHandler::startIdleSampling ( uint8_t  channel) const

start idle sampling when an experiment is neither uploaded nor running on the specified channel.

Parameters
channelthe channel number to start collecting idle data on.
Returns
AisErrorCode::Success if the request to start idle data was sent. If not successful, possible returned errors are:
See also
isChannelBusy

◆ startManualExperiment()

AisErrorCode AisInstrumentHandler::startManualExperiment ( uint8_t  channel) const

start a manual experiment.

With manual experiments, users can turn on any connected channel and toggle between open circuit mode and voltage or current setpoints that can be changed in real-time and run for indefinite periods.

Parameters
channela valid channel number to run the manual experiment on.
Returns
AisErrorCode::Success if the manual experiment was successfully started. If not successful, possible returned errors are:

◆ startUploadedExperiment()

AisErrorCode AisInstrumentHandler::startUploadedExperiment ( uint8_t  channel) const

start the previously uploaded experiment on the specific channel.

Parameters
channelthe channel number to start the experiment on.
Returns
AisErrorCode::Success if the experiment was successfully started on the channel. If not successful, possible returned errors are:
See also
uploadExperimentToChannel
isChannelBusy

◆ stopExperiment()

AisErrorCode AisInstrumentHandler::stopExperiment ( uint8_t  channel) const

stop a running or a paused experiment on the channel.

Parameters
channelthe channel number to stop the experiment on.
Returns
AisErrorCode::Success if an experiment was successfully stopped on the channel. If not successful, possible returned errors are:

This will only return AisErrorCode::Success if there is currently a running or a paused experiment on a valid channel on a connected device.

◆ uploadExperimentToChannel() [1/2]

AisErrorCode AisInstrumentHandler::uploadExperimentToChannel ( uint8_t  channel,
const AisExperiment experiment 
) const

upload an already created custom experiment to a specific channel on the device.

Any running experiment is run on a specific device on a specific channel. This function uploads an experiment to a channel so that you may start, pause, resume and stop the experiment. All of these four control functionalities and others require a channel number to control the experiment. Therefore, if we have several channels, we need to keep track of which experiment is on which channel.

Parameters
channelthe channel number to upload the experiment to.
experimentthe custom experiment to be uploaded to the channel.
Returns
AisErrorCode::Success if the experiment was successfully uploaded to the channel. If not successful, possible returned errors are:

This returns AisErrorCode::Success only when given a valid channel number that is not busy on a connected device.

See also
isChannelBusy

◆ uploadExperimentToChannel() [2/2]

AisErrorCode AisInstrumentHandler::uploadExperimentToChannel ( uint8_t  channel,
std::shared_ptr< AisExperiment experiment 
) const

upload an already created custom experiment to a specific channel on the device.

Any running experiment is run on a specific device on a specific channel. This function uploads an experiment to a channel so that you may start, pause, resume and stop the experiment. All of these four control functionalities and others require a channel number to control the experiment. Therefore, if we have several channels, we need to keep track of which experiment is on which channel.

Parameters
channelthe channel number to upload the experiment to.
experimentthe custom experiment to be uploaded to the channel.
Returns
AisErrorCode::Success if the experiment was successfully uploaded to the channel. If not successful, possible returned errors are:

This returns AisErrorCode::Success only when given a valid channel number that is not busy on a connected device.

See also
isChannelBusy

The documentation for this class was generated from the following file: