Device control class

class SCPIDevice(commandInterface: SerialCommandInterface, dataInterface: Optional[SerialDataInterface], enablePackageUpdateWarning: bool = True)

General important information for the control of the devices with this class.

The control concept is that via SCPI with the setter methods parameters are set which configure the primitives.

Under SCPI-COMMAND you can see the command sent by the method to the device. The command must be followed by an “\n” as a line break.

The following primitives are available to compose methods with:

Potentiostatic or galvanostatic polarization

Open circuit voltage/potential scan

Ramps potentiostatic or galvanostatic

Staircase potentiostatic or galvanostatic

As an example, the following measurement methods were composed of the primitives:

Charge or discharge something

Output potentiostatic or galvanostatic profile as potentiostatic and galvanostatic polarization or ramps

PITT Potentiostatic Intermittent Titration Technique

GITT Galvanostatic Intermittent Titration Technique

When the primitives are called, they use all parameters and then behave differently depending on the configuration. The methods are setters for devices internal parameters for the individual primitives which can be assembled. The parameters are not reset after the primitive and must be changed manually if they are to change, for the next primitive.

The concept is that nothing is done implicitly, everything must be done explicitly. The only thing that is done implicitly is that the potentiostat is switched on by the methods when they need a potentiostat switched on.

The following methods/parameters are allowed by default:

By default the following methods/parameters are disabled:

The primitives turn the potentiostat on or off depending on how they need it. They turn the potentiostat off or on after the primitive depending on how it was before.

After each primitive there is no measurement for a short time and the data is transferred to the computer. This time depends on how the sampling rate is chosen, usually this time is in the range of 0 ms to 100 ms, tending to be about 10 ms - 20 ms. In the future, primitives will follow in which arbitrary signals with voltage or current values can be output without dead times.

If somewhere POGA is mentioned then the primitive measurePolarization() is meant, with which constant voltage or constant current can be output.

The binary serialName can be read from this object, or by other software such as the Zahner-Lab. The data must always be read from the device when it sends them.

At the moment an autonomous measuring operation without connected computer is not possible.

When using multiple devices, these objects must each run in a separate thread. It is not possible to pass these objects as argument for multiprocessing, because this object cannot be serialized.

Parameters

  • commandInterface (SerialCommandInterface) – SerialCommandInterface object to control the device.

  • dataInterface (SerialDataInterface) – SerialDataInterface object for online data.

  • enablePackageUpdateWarning – False to disable warn output to the package version on the console.

close() → None

Close the Connection.

Close the connection and stop the receiver.

getDataReceiver() → DataReceiver

Get the DataReceiver object.

The DataReceiver type object processes the data from the binary comport.

Returns

the DataReceiver object or None if it doesn’t exist.

setRaiseOnErrorEnabled(enabled: bool = True) → None

Setting the error handling of the control object.

If False, then strings from the device containing error are thrown as exceptions.

Parameters

enabled – True to throw execeptions on errors.

getRaiseOnErrorEnabled() → bool

Read the error handling of the control object.

Returns

True if errors trigger an exception.

IDN() → str

Read informations about the device.

The device uses the SCPI protocol on the interface.

This method provides for example the following software information. Manufacturer, device name, serial number, software version and “binary” if it is the binary channel.

For example: ZAHNER-ELEKTRIK,PP212,33000,1.0.0 binary

SCPI-COMMAND

*IDN?

Returns

The response string from the device.

Return type

string

readDeviceInformations() → str

Read informations about the device.

The device uses the SCPI protocol on the interface.

This method provides for example the following software information. Manufacturer, device name, serial number, software version and “binary” if it is the binary channel.

For example: ZAHNER-ELEKTRIK,PP212,33000,1.0.0 binary

The information is then transferred to the internal data structure.

SCPI-COMMAND

*IDN?

Returns

The response string from the device.

Return type

string

clearState() → str

Clear device state.

Deleting the device state, for example, if the Global Limits have been exceeded. The error numbers are described in the class ZahnerSCPIError.

SCPI-COMMAND

*CLS

Returns

The response string from the device.

Return type

string

readState() → str

Read device state.

Read the device state, for example, if the Global Limits have been exceeded. The error numbers are described in the class ZahnerSCPIError.

SCPI-COMMAND

*CLS?

Returns

The response string from the device.

Return type

string

checkResetStatus() → str

Check device status.

Read and clear the status if an error has occurred.

Returns

The response string from the device.

Return type

string

resetCommand() → str

Reset the device.

THIS FUNCTION CAN BE CALLED FROM AN OTHER THREAD

This command switches off the potentiostat and reboots the device. This causes the connection to be lost and the connection must be re-established. This object must also be recreated so that everything is reinitialized via the constructors and the threads are restarted.

SCPI-COMMAND

*RST

Returns

The response string from the device.

Return type

string

abortCommand() → str

Abort of the active measurement.

THIS FUNCTION CAN BE CALLED FROM AN OTHER THREAD

This function aborts the measurement and switches off the potetiosat. Afterwards the status must be reset with CLS so that the measurement can be continued and new primitives can be called.

The device responds to reply with ok. Other command that are active for example an ramp will return with an status that the measurement was aborted. It is also possible that the device will return with two ok if, depending on when the active measurement was finished.

SCPI-COMMAND

ABOR

Returns

The response string from the device.

Return type

string

calibrateOffsets() → str

Execute the offset calibration.

The offsets must be calibrated manually by calling this method after the instrument has been warmed up for at least half an hour.

The calibration data contains the warm offset values at the time of calibration. If the cold instrument is calibrated, the offsets will be worse when the instrument is warm. If you do not calibrate after the start, the offsets will be getting better until the instrument is warmed up.

It is NOT recommended to calibrate the cold instrument only once after startup. It does not hurt to calibrate the offsets from time to time, as this only takes a few seconds.

If the calibration returns several times with an error, there may be a defect. In this case, contact your Zahner distributor.

SCPI-COMMAND

:SESO:CALO

Returns

The response string from the device.

Return type

string

switchToEPCControl() → str

Switch to EPC mode and switch off the potentiostat for safety.

When this command is called, the device closes the USB connection and can only be controlled via the EPC interface. It must be switched back to the SCPI mode manually via Remote2 from the Thales side.

This function probably throws an exception, because the device disconnects from USB by software. This must be received with Try and Catch.

SCPI-COMMAND

:SYST:SEPC

Returns

The response string from the device.

Return type

string

switchToEPCControlWithoutPotentiostatStateChange() → str

Switch to EPC mode without changing settings on the potentiostat.

This function leaves the potentiostat in its current operating state and then switches to EPC mode. This should only be used when it is really necessary to leave the potentiostat on, because between the change of control no quantities like current and voltage are monitored.

When this command is called, the device closes the USB connection and can only be controlled via the EPC interface. It must be switched back to the SCPI mode manually via Remote2 from the Thales side.

This function probably throws an exception, because the device disconnects from USB by software. This must be received with try and catch.

To ensure that the switch between Thales and Python/SCPI is interference-free, the following procedure should be followed. This is necessary to ensure that both Thales and Python/SCPI have calibrated offsets, otherwise jumps may occur when switching modes:

  1. Connect Zennium with USB and EPC-device/power potentiostat (XPOT2, PP2x2, EL1002) with USB to the computer. As well as Zennium to power potentiostat by EPC cable.

  2. Switch on all devices.

  3. Allow the equipment to warm up for at least 30 minutes.

  4. Select and calibrate the EPC-device in Thales (with Remote2).

  5. Switching the EPC-device to SCPI mode via Remote2 command.

  6. Performing the offset calibration with Python/SCPI.

  7. Then it is possible to switch between Thales and Python/SCPI with the potentiostat switched on.

SCPI-COMMAND

:SYST:HOTS

Returns

The response string from the device.

Return type

string

setLineFrequency(frequency: float) → str

Set the line frequency of the device.

With this command the line frequency can be changed, depending on the country where the device is located. The line frequency is stored in the device and is still stored after a restart of the device.

The device must know the line frequency of the country in which it is located in order to suppress interference.

SCPI-COMMAND

:SYST:LINF <value>

Parameters

frequency – The frequency as float value.

Returns

The response string from the device.

Return type

string

getLineFrequency() → float

Read the line frequency of the device.

The line frequency is stored in the device and is still stored after a restart of the device.

SCPI-COMMAND

:SYST:LINF?

Returns

The set line frequency as float.

Return type

float

setDateTime(year: int, month: int, day: int, hour: int, minute: int, second: int) → str

Set the time of the device.

This command is used to set the device time.

SCPI-COMMAND

:SYST:TIME <yyyy>-<mm>-<dd>T<hh>:<mm>:<ss>

Returns

The response string from the device.

Return type

string

getDateTime() → str

read the time of the device

Returns

the time from the device as ISO 8601 string

getDateTimeStruct() → date

read the time of the device

:returns the date and time as datetime struct

getSoftwareInfo() → str

Read software information.

The basic revision of the software can be queried with IDN. This command queries complex software information that is not required under normal circumstances. It is only used internally to identify untagged versions of the software.

For example: Version: 1.0.0-rc3; Branch: master; Hash: 247a16a75a3d5685def55972588990aeebbf280f; Target: Debug; Compile time: 2021-04-08T10:49:25.074486+01:00

SCPI-COMMAND

:SYST:SOFT:INFO?

Returns

The time from the device as ISO 8601 string.

Return type

string

getPotential() → float

Read the potential from the device.

This command is the same as getVoltage to allow the naming of voltage and potential.

SCPI-COMMAND

:MEAS:VOLT?

Returns

The most recent measured potential.

Return type

float

getVoltage() → float

Read the voltage from the device.

Read the voltage between Reference and Working Sense.

SCPI-COMMAND

:MEAS:VOLT?

Returns

The most recent measured voltage.

Return type

float

getPotentialMedian(measurements: int = 7) → float

Read potential and calculate median.

Does the same as getVoltageMedian.

Parameters

measurements – The number of measurements for median calculation.

Returns

The median potential.

Return type

float

getVoltageMedian(measurements: int = 7) → float

Read potential and calculate median.

Reade measurements times the potential from the device and calculate the median.

Parameters

measurements – The number of measurements for median calculation.

Returns

The median potential.

Return type

float

getCurrent() → float

Read the current from the device.

This command reads only the current current value. This function does NOT automatically set the correct current range, it ONLY READS.

SCPI-COMMAND

:MEAS:CURR?

Returns

The most recent measured current.

Return type

float

getCurrentMedian(measurements: int = 7) → float

Read current and calculate median.

Reade measurements times the current from the device and calculate the median.

Parameters

measurements – The number of measurements for median calculation.

Returns

The median current.

Return type

float

setPotentiostatEnabled(enable: bool = False) → str

Switching the potentiostat on or off.

If only the potentiostat is switched on, NO RANGING is performed and NO LIMITS are monitored. Everything must be done manually.

If primitives require a potentiostat to be on, such as polarizing, then they will turn the potentiostat on. After the primitive it will be switched back to the previous state.

If the potentiostat was on before a primitive, for example, then it will be switched on again after the primitive.

If the potentiostat was not on before a primitive, it takes up to 50 ms at the beginning of the primitive, depending on the device, until the potentiostat has settled and measurement can be started. If the potentiostat is already on at the beginning of the measurement, the measurement starts immediately. If faster processes are to be recorded in succession in different primitives, the potentiostat must be switched on beforehand.

SCPI-COMMAND

:SESO:STAT <ON|OFF>

Parameters

enable – The state. True to turn on.

Returns

The response string from the device.

Return type

string

_getRelationCommandParameter(relation: Union[RELATION, str]) → str

Get the relation command parameter.

This function returns the parameter for the relation, which must be sent as SCPI command.

Parameters

relation (RELATION) – The relation OCV or ZERO.

Returns

The parameter string

Return type

string

setVoltageRelation(relation: Union[RELATION, str]) → str

Set the relation of the voltage parameter for simple use.

If the relation is related to OCV, measureOCV() must be used to specify the OCV relation to be used for calculating the relative voltage.

The relation is of the type RELATION. The strings OCP OCV and the number 1 is also supported for relation to Open Circuit. Everything else means relation to 0 V.

SCPI-COMMAND

:SESO:UREL <OCV|0>

Parameters

relation (RELATION) – The relation OCV or ZERO.

Returns

The response string from the device.

Return type

string

setVoltageValue(value: float) → str

Set the voltage parameter for simple use.

This value should be set before switching on.

If the potentiostat is simply switched on potentiostatically without a primitive, this voltage value is output on the potentiostat.

If setVoltageRelation() is selected as OCV, then this value is added to the measured OCV.

SCPI-COMMAND

:SESO:UVAL <value>

Parameters

value – The voltage value.

Returns

The response string from the device.

Return type

string

setCurrentValue(value: float) → str

Set the current parameter for simple use.

This value should be set before switching on.

If the potentiostat is simply switched on galvanostatically without a primitive, this current value is output on the galvanostat.

SCPI-COMMAND

:SESO:IVAL <value>

Parameters

value – The current value.

Returns

The response string from the device.

Return type

string

getMACAddress() → str

Read MAC address from device.

Each device is assigned a MAC address from the Zahner MAC address block. With this command the MAC address can be read.

SCPI-COMMAND

:SYST:MAC?

Returns

The MAC address of the device.

Return type

string

setVoltageRange(voltage: float) → str

Set the voltage range.

This command sets the voltage range by an voltage value.

SCPI-COMMAND

:SESO:VRNG <value>

Parameters

voltage – voltage for which the range is to be selected.

Returns

The response string from the device.

Return type

string

setVoltageRangeIndex(voltage: int) → str

Set the voltage range.

This command sets the voltage range by the range index. Index starts at 0.

SCPI-COMMAND

:SESO:VRNG:IDX <value>

Parameters

voltage – voltage range index.

Returns

The response string from the device.

Return type

string

setAutorangingEnabled(state: bool = True) → str

Set the autoranging state.

This does not work perfectly depending on the measurement object. The best option is always to measure with a fixed current range without autoranging.

Autoranging is only activ in primitves. If only the potentiostat is switched on, NO RANGING is performed and NO LIMITS are monitored. It is recommended to measure without autoranging if you know the current that will flow.

It can be rang in all primitives. However, disturbances can be seen in the measurement from the ringing, since disturbances occur during the shunt change. The time for switching is up to 50 ms depending on the device.

If you start in the wrong measuring range, time passes at the beginning in which disturbances and measuring errors are to be seen, until the correct measuring range is found.

Before starting the measurement, you can manually set a current range to accelerate until the correct shunt is found.

SCPI-COMMAND

:SESO:CRNG:AUTO <1|0>

Parameters

state – The state of autoranging. True means turned on.

Returns

The response string from the device.

Return type

string

setInterpolationEnabled(state: bool = True) → str

Set the interpolation state.

When autoranging is active, disturbances in the measurement may be seen due to the current range change of the potentiostat.

If interpolation is switched off, the disturbances are visible in the data. If interpolation is switched on, the current points are linearly interpolated with the current values before and after the range change.

This does not work perfectly depending on the measurement object. The best option is always to measure with a fixed current range without autoranging.

SCPI-COMMAND

:SESO:INTP <1|0>

Parameters

state – The state of interpolation. True means turned on.

Returns

The response string from the device.

Return type

string

setMinimumShuntIndex(index: int) → str

Set the minimum shunt index.

This command sets the smallest shunt that is used. Index starts at 0.

SCPI-COMMAND

:SESO:CRNG:AUTO:LLIM <value>

Parameters

current – Current range index.

Returns

The response string from the device.

Return type

string

setMaximumShuntIndex(index: int) → str

Set the maximum shunt index.

This command sets the biggest shunt that is used. Index starts at 0.

SCPI-COMMAND

:SESO:CRNG:AUTO:ULIM <value>

Parameters

current – Current range index.

Returns

The response string from the device.

Return type

string

setShuntIndex(index: int) → str

Set the shunt index.

This command sets a shunt, via its index. Index starts at 0.

SCPI-COMMAND

:SESO:CRNG:IDX <value>

Parameters

current – Current range index.

Returns

The response string from the device.

Return type

string

setCurrentRange(current: float) → str

Set the current range.

This command sets a shunt. The shunt is automatically selected to match the current value.

SCPI-COMMAND

:SESO:CRNG <value>

Parameters

current – Current for which the range is to be selected.

Returns

The response string from the device.

Return type

string

setTimeParameter(time: Union[float, str]) → str

Set the time parameter.

This command sets the time for primitives that require a single time parameter, such as ramps.

The time can be specified as a floating point number, then it is interpreted as seconds. The number should not be much smaller than one second.

Alternatively, the time can also be specified as a string. Then you have s, m and min and h as time unit available.

As can be read in the class SCPIDevice, there is a dead time at the ends of the primitive, that this does not fall into the weight, the time should not be less than one second.

Examples:

  • setTimeParameter(3.1415) Input as seconds.

  • setTimeParameter(“3.1415 s”) Input as seconds.

  • setTimeParameter(“3.1415 m”) Input as minutes.

  • setTimeParameter(“3.1415 min”) Input as minutes.

  • setTimeParameter(“3.1415 h”) Input as hours.

SCPI-COMMAND

:PARA:TIME <value>

Parameters

time – The time parameter. READ THE TEXT ABOVE.

Returns

The response string from the device.

Return type

string

setMaximumTimeParameter(value: Union[float, str]) → str

Set the maximum time parameter.

Parameters for primitives that require a maximum time. Enter the parameter as for setTimeParameter().

As can be read in the class SCPIDevice, there is a dead time at the ends of the primitive, that this does not fall into the weight, the time should not be less than one second.

SCPI-COMMAND

:PARA:TMAX <value>

Parameters

time – time parameter; for valid values see setTimeParameter

Returns

response string from the device

Return type

string

setMinimumTimeParameter(value: Union[float, str]) → str

Set the minimum time parameter.

Parameters for primitives that require a minimum time. Enter the parameter as for setTimeParameter().

SCPI-COMMAND

:PARA:TMIN <value>

Parameters

time – time parameter; for valid values see setTimeParameter

Returns

The response string from the device.

Return type

string

setVoltageParameterRelation(relation: Union[RELATION, str]) → str

Set the relation of the voltage parameter for primitves.

If the relation is related to OCV, measureOCV() must be used to specify the OCV relation to be used for calculating the relative voltage.

The relation is of the type RELATION. The strings OCP OCV and the number 1 is also supported for relation to Open Circuit. Everything else means relation to 0 V.

SCPI-COMMAND

:PARA:UREL <OCV|0>

Parameters

relation (RELATION) – The relation OCV or ZERO.

Returns

The response string from the device.

Return type

string

setVoltageParameter(value: float) → str

Set the voltage parameter for primitives.

Primitves that need an voltage parameter like ramps use this parameter. This parameter is only used when the coupling is potentiostatic.

If setVoltageParameterRelation() is selected as OCV, then this value is added to the measured OCV.

SCPI-COMMAND

:PARA:UVAL <value>

Parameters

value – The voltage value.

Returns

The response string from the device.

Return type

string

setCurrentParameter(value: float) → str

Set the current parameter for primitives.

Primitves that need an current parameter like ramps use this parameter. This parameter is only used when the coupling is galvanostatic.

SCPI-COMMAND

:PARA:IVAL <value>

Parameters

value – The current value.

Returns

The response string from the device.

Return type

string

setScanRateParameter(scanrate: float) → str

Set the scan rate for primitives.

Primitves that need an scan rate parameter use this parameter. The value is interpreted as V/s or A/s depending on the selected coupling.

SCPI-COMMAND

:PARA:SCRA <value>

Parameters

value – The scanrate value. V/s or A/s depending on coupling as float.

Returns

The response string from the device.

Return type

string

setCoupling(coupling: Union[COUPLING, str]) → str

Set the coupling of the device.

Set the coupling to galvanostatic or potentiostatic. The parameter coupling has to be from type COUPLING or the string “pot”.

When the coupling is changed the potentiostat will be turned off. It must be switched on again manually, with setPotentiostatEnabled().

SCPI-COMMAND

:SESO:COUP <pot|gal>

Parameters

coupling (COUPLING) – The coupling of the device.

Returns

The response string from the device.

Return type

string

setBandwith(bandwithIdx: int) → str

Set the bandwith of the device.

The bandwidth of the device is automatically set correctly, it is not recommended to change it.

SCPI-COMMAND

:SESO:BAND <value>

Parameters

bandwith – The bandwith as index.

Returns

The response string from the device.

Return type

string

setFilterFrequency(frequency: float) → str

Set the filter frequency of the device.

The filter frequency of the device is automatically set correctly, it is not recommended to change it.

SCPI-COMMAND

:SESO:FILT <value>

Parameters

frequency – The frequency as float value.

Returns

The response string from the device.

Return type

string

setParameterLimitCheckToleranceTime(time: float) → str

Setting the time for which operation outside the limits is allowed.

By default this parameter is 0. It will be aborted at the latest at the next integer multiple of the sampling period duration. For this time, it is allowed to exceed or fall below the functional parameter current and voltage limits.

Enter the parameter as for setTimeParameter().

SCPI-COMMAND

:PARA:UILT <value>

Parameters

time – The time in seconds.

Returns

The response string from the device.

Return type

string

setMinMaxVoltageParameterCheckEnabled(state: bool = True) → str

Switch voltage check on or off.

The voltage is absolute and independent of OCP/OCV.

When switched on, the voltage is checked in galvanostatic primitives, such as ramps or galvanostatic polarization. When the limit is reached, it continues to the next primitive and the state of the device is ok and it has no error.

This can be used, for example, to apply a constant current until a voltage is reached. This is used in the method measureCharge().

SCPI-COMMAND

:PARA:ULIM:STAT <ON|OFF>

Parameters

state – The state of check. True means turned on.

Returns

The response string from the device.

Return type

string

setMinMaxCurrentParameterCheckEnabled(state: bool = True) → str

Switch current check on or off.

The current is absolute with sign.

When switched on, the current is checked in potentiostatic primitives, such as ramps or polarization. When the limit is reached, it continues to the next primitive and the state of the device is ok and it has no error.

This can be used, for example, to wait until the voltage is only as small as required (settling process).

SCPI-COMMAND

:PARA:ILIM:STAT <ON|OFF>

Parameters

state – The state of check. True means turned on.

Returns

The response string from the device.

Return type

string

setMaximumVoltageParameter(value: float) → str

Set the maximum voltage parameter for primitives.

The voltage is absolute and independent of OCP/OCV.

If the monitoring is switched on, the primitive is successfully aborted when the maximum voltage is exceeded or the minimum voltage is undershot. It returns with the response ok.

SCPI-COMMAND

:PARA:ULIM:MAX <value>

Parameters

value – The voltage value.

Returns

The response string from the device.

Return type

string

setMinimumVoltageParameter(value: float) → str

Set the minimum voltage parameter for primitives.

The voltage is absolute and independent of OCP/OCV.

If the monitoring is switched on, the primitive is successfully aborted when the maximum voltage is exceeded or the minimum voltage is undershot. It returns with the response ok.

SCPI-COMMAND

:PARA:ULIM:MIN <value>

Parameters

value – The voltage value.

Returns

The response string from the device.

Return type

string

setMaximumCurrentParameter(value: float) → str

Set the maximum voltage parameter for primitives.

The current is absolute with sign.

If the monitoring is switched on, the primitive is successfully aborted when the maximum current is exceeded or the minimum current is undershot. It returns with the response ok.

SCPI-COMMAND

:PARA:ILIM:MAX <value>

Parameters

value – The current value.

Returns

The response string from the device.

Return type

string

setMinimumCurrentParameter(value: float) → str

Set the minimum voltage parameter for primitives.

The current is absolute with sign.

If the monitoring is switched on, the primitive is successfully aborted when the maximum current is exceeded or the minimum current is undershot. It returns with the response ok.

SCPI-COMMAND

:PARA:ILIM:MAX <value>

Parameters

value – The current value.

Returns

The response string from the device.

Return type

string

setGlobalLimitCheckToleranceTime(time: float) → str

Setting the time for which operation outside the limits is allowed.

By default this parameter is 0. It will be aborted at the latest at the next integer multiple of the sampling period duration. For this time, it is allowed to exceed or fall below the global current and voltage limits.

Enter the parameter as for setTimeParameter().

SCPI-COMMAND

:SESO:UILT <value>

Parameters

state – The time in seconds.

Returns

The response string from the device.

Return type

string

setGlobalVoltageCheckEnabled(state: bool = True) → str

Switch global voltage check on or off.

The voltage is absolute and independent of OCP/OCV.

When this is enabled, the voltage in potentiostatic and galvanostatic is checked for the global limits. If the limits are exceeded, the potentiostat is switched off and the primitive returns an error condition.

New primitives cannot be measured until the error state of the device has been reset. The state can be reset with clearState().

SCPI-COMMAND

:SESO:ULIM:STAT <ON|OFF>

Parameters

state – The state of check. True means turned on.

Returns

The response string from the device.

Return type

string

setGlobalCurrentCheckEnabled(state: bool = True) → str

Switch global current check on or off.

The current is absolute with sign.

When this is enabled, the current in potentiostatic and galvanostatic is checked for the global limits. If the limits are exceeded, the potentiostat is switched off and the primitive returns an error condition.

New primitives cannot be measured until the error state of the device has been reset. The state can be reset with clearState().

SCPI-COMMAND

:SESO:ILIM:STAT <ON|OFF>

Parameters

state – The state of check. True means turned on.

Returns

The response string from the device.

Return type

string

setMaximumVoltageGlobal(value: float) → str

Set the maximum voltage for the device.

The voltage is absolute and independent of OCP/OCV.

If the monitoring is switched on, the primitive is aborted when the maximum voltage is exceeded or the minimum voltage is undershot.

SCPI-COMMAND

:SESO:ULIM:MAX <value>

Parameters

value – The voltage value.

Returns

The response string from the device.

Return type

string

setMinimumVoltageGlobal(value: float) → str

Set the minimum voltage for the device.

The voltage is absolute and independent of OCP/OCV.

If the monitoring is switched on, the primitive is aborted when the maximum voltage is exceeded or the minimum voltage is undershot.

SCPI-COMMAND

:SESO:ULIM:MIN <value>

Parameters

value – The voltage value.

Returns

The response string from the device.

Return type

string

setMaximumCurrentGlobal(value: float) → str

Set the maximum current for the device.

The current is absolute with sign.

If the monitoring is switched on, the primitive is aborted when the maximum current is exceeded or the minimum voltage is undershot.

SCPI-COMMAND

:SESO:ILIM:MAX <value>

Parameters

value – The current value.

Returns

The response string from the device.

Return type

string

setMinimumCurrentGlobal(value: float) → str

Set the minimum current for the device.

The current is absolute with sign.

If the monitoring is switched on, the primitive is aborted when the maximum current is exceeded or the minimum voltage is undershot.

SCPI-COMMAND

:SESO:ILIM:MIN <value>

Parameters

value – The current value.

Returns

The response string from the device.

Return type

string

setSamplingFrequency(frequency: float) → str

Set the the sampling frequency.

This frequency is used for all primitives except IE stairs.

SCPI-COMMAND

:SESO:SFRQ <value>

Parameters

frequency – The sampling frequency in Hz.

Returns

The response string from the device.

Return type

string

setToleranceBreakEnabled(value: bool = True) → str

Allowing tolerance break for primitive.

The primitive potentiostatic and galvanostatic polarization or OCVScan can be aborted if the absolute change tolerance has been fallen below. In the case of IE steps, this applies to the individual steps of the primitive.

The tolerances apply to the complementary quantity, i.e. potentiostatic to current changes and galvanostatic to voltage changes. OCV it is related to the voltage.

The absolute tolerances are always in V/s or A/s. The relative tolerance is a factor of 1/s. The current change is divided by the size at the start and is therefore set in the relative ratio of the start size at primitve start.

The tolerances are calculated according to the following formulas, where X is current or voltage as the case requires.

Absolute Tolerance = (Xn-Xn-1)/(tn-tn-1) Relative Tolerance = (Absolute Tolerance)/(X0)

SCPI-COMMAND

:PARA:TOL:STAT <0|1>

Parameters

value – The sate of tolerance break. True means enabled.

Returns

The response string from the device.

Return type

string

setAbsoluteTolerance(value: float) → str

Set the absolute tolerance.

Documentation is with the method setToleranceBreakEnabled().

SCPI-COMMAND

:PARA:TOL:ABS <value>

Parameters

value – The value of absolute tolerance in V/s or A/s.

Returns

The response string from the device.

Return type

string

setRelativeTolerance(value: float) → str

Set the relative tolerance.

Documentation is with the method setToleranceBreakEnabled().

SCPI-COMMAND

:PARA:TOL:REL <value>

Parameters

value – The value of relative tolerance in 1/s.

Returns

The response string from the device.

Return type

string

setChargeBreakEnabled(value: bool = True) → str

Allowing charge break for primitive.

With primitive potentiostatic and galvanostatic polarization, you can set an upper charge limit and a lower charge limit. These are absolute signed values.

For each primitive these values count separately and for each primitive the charge starts at 0.

If you want to know the charge, the current must be integrated manually.

SCPI-COMMAND

:PARA:CHAR:STAT <0|1>

Parameters

value – The sate of charge break. True means enabled.

Returns

The response string from the device.

Return type

string

setMaximumCharge(value: float) → str

Set the maximum charge parameter for primitives.

If the monitoring is switched on, the primitive is successfully aborted when the maximum charge is exceeded or the minimum charge is undershot. It returns with the response ok.

SCPI-COMMAND

:PARA:CHAR:MAX <value>

Parameters

value – The charge value.

Returns

The response string from the device.

Return type

string

setMinimumCharge(value: float) → str

Set the minimum charge parameter for primitives.

If the monitoring is switched on, the primitive is successfully aborted when the maximum charge is exceeded or the minimum charge is undershot. It returns with the response ok.

SCPI-COMMAND

:PARA:CHAR:MIN <value>

Parameters

value – The charge value.

Returns

The response string from the device.

Return type

string

getTemperature() → float

Read temperatur from the connected thermoelement.

For this command, a thermocouple must be connected to the back of the device. Otherwise an exception is thrown because the response string contains the text that no temperature sensor is connected.

This is used to query the temperature. A recording of the temperature during measurements is not yet supported.

SCPI-COMMAND

:MEAS:TEMP?

Returns

The measured temperature in degree celsius.

Return type

float

setStepSize(value: float) → str

Set the step size for primitives.

This parameter is used only by the IEStairs. It can be the step size in V for potentiostatic stairs or in A for galvanostatic stairs.

SCPI-COMMAND

:PARA:STEP <value>

Parameters

value – The step size in V or A.

Returns

The response string from the device.

Return type

string

measureRampValueInTime(targetValue: Optional[float] = None, duration: Optional[float] = None) → str

Measuring a ramp with a target value in a duration.

Potentiostatic or galvanostatic ramps are possible. With these ramps, the device selects the step size as small as possible.

Before starting the ramp, a setpoint must always be specified, at which the ramp then starts. It is not necessary to switch on the potentiostat, it is sufficient to set a voltage value with the method setVoltageValue() or a current value with the method setCurrentValue(), depending on whether the ramp is galvanostatic or potentiostatic. Alternatively, the ramp starts from the final value of the last executed pimitive. However, if the last primitive had a different coupling, a new value must be specified. Within the duration the targetValue is then driven.

If targetValue is not specified, the value from the last method call of setVoltageParameter() or setCurrentParameter() is used, depending on how the coupling was set when the call was made. The same applies to duration there the value of the method setTimeParameter() is used.

The ramp can be aborted with the minimum or maximum values.

In addition to the dead time at the end of the ramp, as with all primitives, there are a few milliseconds at the beginning of the ramp that are needed to initialize the ramp, this is not necessary with POGA for example.

Used setup methods/parameters:

SCPI-COMMAND

:MEAS:RMPT?

Parameters

  • targetValue – The target targetValue or None to use the old parameter.

  • duration – The duration of the ramp or None to use the old time parameter.

Returns

The response string from the device.

Return type

string

measureRampValueInScanRate(targetValue: Optional[float] = None, scanrate: Optional[float] = None) → str

Measuring a ramp to a target value with a scanrate.

Potentiostatic or galvanostatic ramps are possible. With these ramps, the device selects the step size as small as possible.

Before starting the ramp, a setpoint must always be specified, at which the ramp then starts. It is not necessary to switch on the potentiostat, it is sufficient to set a voltage value with the method setVoltageValue() or a current value with the method setCurrentValue(), depending on whether the ramp is galvanostatic or potentiostatic. Alternatively, the ramp starts from the final value of the last executed pimitive. However, if the last primitive had a different coupling, a new value must be specified.

If targetValue is not specified, the targetValue from the last method call of setVoltageParameter() or setCurrentParameter() is used, depending on how the coupling was set when the call was made. The same applies to scanrate there the last value of the method setScanRateParameter() is used.

The absolute value of the scan rate is used. The unit is in V/s or A/s depending on whether the command is called galvanostatically or potentiostatically.

The ramp can be aborted with the minimum or maximum values.

In addition to the dead time at the end of the ramp, as with all primitives, there are a few milliseconds at the beginning of the ramp that are needed to initialize the ramp, this is not necessary with POGA for example.

Used setup methods/parameters:

SCPI-COMMAND

:MEAS:RMPS?

Parameters

  • targetValue – The target targetValue or None to use the old parameter.

  • scanrate – The scanrate to the target value.

Returns

The response string from the device.

Return type

string

measureRampScanRateForTime(scanrate: Optional[float] = None, time: Optional[float] = None) → str

Measuring with a scanrate for a time.

Potentiostatic or galvanostatic ramps are possible. With these ramps, the device selects the step size as small as possible.

Before starting the ramp, a setpoint must always be specified, at which the ramp then starts. It is not necessary to switch on the potentiostat, it is sufficient to set a voltage value with the method setVoltageValue() or a current value with the method setCurrentValue(), depending on whether the ramp is galvanostatic or potentiostatic. Alternatively, the ramp starts from the final value of the last executed pimitive. However, if the last primitive had a different coupling, a new value must be specified.

If the scanrate is not specifiedet the last value of the method setScanRateParameter() is used. The same applies to duration there the value of the method setTimeParameter() is used.

Here the sign of the ramp is important and indicates the direction of the ramp. The unit is in V/s or A/s depending on whether the command is called galvanostatic or potentiostatic.

The ramp can be aborted with the minimum or maximum values.

In addition to the dead time at the end of the ramp, as with all primitives, there are a few milliseconds at the beginning of the ramp that are needed to initialize the ramp, this is not necessary with POGA for example.

Used setup methods/parameters:

SCPI-COMMAND

:MEAS:RMPV?

Parameters

  • targetValue – The target targetValue or None to use the old target targetValue.

  • scanrate – The scanrate to the target value.

Returns

The response string from the device.

Return type

string

measurePolarization() → str

POGA - Measurement of a potentiostatic or galvanostatic polarization.

This primitive outputs constant current or constant voltage for a maximum time, depending on what has been set.

However, the primitive can be aborted prematurely if the complementary quantity, e.g. the current in potentiostatic operation, exceeds a specified maximum current or falls below a minimum current.

Likewise, the primitive can be aborted prematurely when the change of the complementary quantity per time has fallen below a set value. For the abortion on a change, one can still set a minimum duration of the primitive, which expires before the tolerance is checked.

With primitive potentiostatic and galvanostatic polarization, you can set an upper charge limit and a lower charge limit. These are absolute signed values. For each primitive these values count separately and for each primitive the charge starts at 0.

Used setup methods/parameters:

SCPI-COMMAND

:MEAS:POGA?

Returns

The response string from the device.

Return type

string

measureOCVScan() → str

Measurement of open circuit voltage over time

However, the primitive can be aborted prematurely if the voltage in potentiostatic operation, exceeds a maximum or falls below a minimum.

Likewise, the primitive can be aborted prematurely when the change of the voltage per time has fallen below a set value. For the abortion on a change, one can still set a minimum duration of the primitive, which expires before the tolerance is checked.

Used setup methods/parameters:

SCPI-COMMAND

:MEAS:OCVS?

Returns

The response string from the device.

Return type

string

measureOCV() → str

Measurement of open circuit voltage.

The potentiostat is automatically switched off by this method.

This method measures the open circuit voltage, and sets this open circuit voltage as a reference for subsequent measurements when a voltage is to be referenced to OCV.

SCPI-COMMAND

:MEAS:OCV?

Returns

The open circuit voltage.

Return type

float

measureIEStairs() → str

Measurement of a voltage or current staircase.

This primitive outputs a voltage or current staircase from the current current or voltage value to a target value.

By default, only one measured value is recorded at the end of the step. The duration and size of the step can be set. As with polarization, change tolerances and a minimum time after which the next step is continued can also be set.

However, the primitive can be aborted prematurely if the complementary quantity, e.g. the current in potentiostatic operation, exceeds a specified maximum current or falls below a minimum current.

Used setup methods/parameters:

SCPI-COMMAND

:MEAS:IESC?

Returns

The response string from the device.

Return type

string

checkConnectionPolarity() → bool

Check that the object is connected with the correct polarity.

This function is only to simplify the development of measurement methods from primitives, for example, that a battery has a positive open circuit voltage. This eliminates the need to handle cases when the OCV is negative, making everything clearer and simpler.

Returns

True if the polarity is correct, else raise ValueError().

Return type

float

measureCharge(current: float, stopVoltage: float, maximumTime: Union[float, str], minimumVoltage: float = 0) → str

Charge an object.

It is charged with a positive current until a maximum voltage is reached. A maximum time can also be defined. In theory, you should not need the minimum voltage, as the voltage should increase during charging.

Global limits can be defined outside this method before the function call. Where the limits should be chosen slightly larger, that the functional terminations with the lower priority are used instead of the global terminations.

Parameters

  • current – The charging current. The absolute value is used.

  • stopVoltage – The voltage up to which charging is to take place.

  • maximumTime – The maximum charging time.

  • minimumVoltage – You should not need the minimum voltage, as the voltage should increase during charging.

Returns

The response string from the device, from measurePolarization().

Return type

string

measureDischarge(current: float, stopVoltage: float, maximumTime: Union[float, str], maximumVoltage: Union[float, str] = 1000) → str

Discharge an object.

It is discharged with a negative current until a minimum voltage is reached. A maximum time can also be defined. In theory, you should not need the maximum voltage, as the voltage should decrease during discharging.

Global limits can be defined outside this method before the function call. Where the limits should be chosen slightly larger, that the functional terminations with the lower priority are used instead of the global terminations.

Parameters

  • current – The discharging current. The absolute value * -1.0 is used.

  • stopVoltage – The voltage down to which discharging is to take place.

  • maximumTime – The maximum charging time.

  • maximumVoltage – You should not need the maximum voltage, as the voltage should decrease during discharging.

Returns

The response string from the device, from measurePolarization().

Return type

string

measureProfile(profileDict: list[dict[str, float]], coupling: COUPLING, scalingFactor: float = 1, outputPrimitive: str = 'pol') → None

Output a sequence of POGA or ramps.

With this command a defined number of potentiostatic or galvanostatic polarizations or ramps can be output one after the other. Galvanostatic and potentiostatic cannot be mixed at the moment.

The profile must be passed with the following data structure:

[{“time”: 0, “value”: 0.1},{“time”: 1, “value”: 0.4},{“time”: 2, “value”: 0.3}]

The structure is an array with a dictionary for each step. The dictionary has two keys:

time: The time point of the value. value: The value, current or voltage, depending on the parameter coupling.

There is also an example to import data from an drive cycle. driveCycle = getNormalisedCurrentTableForHUDDSCOL()

Note that this method is composed of calls to the individual primitives including their limitations and peculiarities. Short dead times where no measurements are taken for data processing.

Parameters

  • profileDict – Profile support points, see documentation above.

  • coupling (COUPLING) – Coupling of measurement.

  • scalingFactor – Multiplier for the values from the dictionary, default 1, especially for current normalization. But can also be used to multiply the voltage by a factor.

  • outputPrimitive – Default “pol” that means POGA, but “ramp” is also possible.

Return type

None

measurePITT(targetVoltage: float, endVoltage: float, stepVoltage: float, onTime: Union[float, str], openCircuitTime: Union[float, str], startWithOCVScan: bool = True, measureOnTargetVoltage: bool = False) → None

PITT - Potentiostatic Intermittent Titration Technique

This is a simple basic implementation of PITT. Global current and voltage interrupts can be set outside the method. The functionality can be easily extended by additional parameters of the methods, such as abort on change tolerances.

Parameters

  • targetVoltage – The upper reverse voltage.

  • endVoltage – The voltage to finish the measurement.

  • stepVoltage – The voltage step size.

  • onTime – The time for the constant voltage phase.

  • openCircuitTime – The time for open circuit phase.

  • startWithOCVScan – Start with scan of the start potential, if false start with first step.

  • measureOnTargetVoltage – if True, then a measurement is made on the target voltage, depending on the step size, the last step can then be smaller. If False, then the last voltage measurement points can be between targetVoltage and (targetVoltage - stepVoltage) size. With false the points are on the same potential in the up and down cycle.

Return type

None

measureGITT(targetVoltage: float, endVoltage: float, current: float, onTime: Union[float, str], openCircuitTime: Union[float, str], startWithOCVScan: bool = False) → None

GITT - Galvanostatic Intermittent Titration Technique

This is a simple basic implementation of PITT. The functionality can be easily extended by additional parameters of the methods, such as abort on change tolerances.

The software voltage limit of the device is used as the voltage limit. If this is exceeded, the device returns an error condition. This error condition must be reset for further measurement. To avoid false triggering of the limits, the limits that are not required are switched over.

Parameters

  • targetVoltage – The upper reverse voltage.

  • endVoltage – The voltage to finish the measurement.

  • current – The value of current.

  • onTime – The time for the constant voltage phase.

  • openCircuitTime – The time for open circuit phase.

  • startWithOCVScan – Start with scan of the start potential, if false start with first step.

Return type

None

_processTimeInput(time: Union[float, str]) → float

Private function to process time inputs.

This function processes the input to a floating point number with a time specification in seconds. All methods which set time parameters process the parameter with this method.

Times can then be passed as in the following examples:

  • _processTimeInput(3.1415) Input as seconds.

  • _processTimeInput(“3.1415 s”) Input as seconds.

  • _processTimeInput(“3.1415 m”) Input as minutes.

  • _processTimeInput(“3.1415 min”) Input as minutes.

  • _processTimeInput(“3.1415 h”) Input as hours.

Parameters

time – Time in format as described in the previous section.

Returns

Time in seconds as float value.

_writeCommandToInterfaceAndReadValue(string: str) → float

Private function to send a command to the device and read a float.

This function sends the data to the device with the class SerialCommandInterface and waits for a response. This response is then converted to a float.

Parameters

string – String with command, without the line feed.

Returns

Float value.

Return type

float

_writeCommandToInterfaceAndReadLine(string: str) → str

Private function to send a command to the device and read a string.

This function sends the data to the device with the class SerialCommandInterface and waits for a response.

This function also manages the possibility to send abort or reset in a second thread in parallel to the first request to abort the primitive or to reset the device.

Raises

ZahnerSCPIError – Error number.

Parameters

string – String with command, without the line feed.

Returns

Response string from the device.

Return type

string

enum COUPLING(value)

Working modes for the potentiostat.

Valid values are as follows:

GALVANOSTATIC = <COUPLING.GALVANOSTATIC: 0>
POTENTIOSTATIC = <COUPLING.POTENTIOSTATIC: 1>
enum RELATION(value)

Possible potential references for voltage parameters. OCP and OCV are the same and mean reference to open circuit voltage and potential respectively.

Valid values are as follows:

ZERO = <RELATION.ZERO: 0>
OCV = <RELATION.OCV: 1>