# Generic SCPI Instruments¶

## SCPIInstrument - Base class for instruments using the SCPI protocol¶

class instruments.generic_scpi.SCPIInstrument(filelike)

Base class for all SCPI-compliant instruments. Inherits from from Instrument.

This class does not implement any instrument-specific communication commands. What it does add is several of the generic SCPI star commands. This includes commands such as *IDN?, *OPC?, and *RST.

Example usage:

>>> import instruments as ik
>>> inst = ik.generic_scpi.SCPIInstrument.open_tcpip('192.168.0.2', 8888)
>>> print(inst.name)

class ErrorCodes

Enumeration describing error codes as defined by SCPI 1999.0. Error codes that are equal to 0 mod 100 are defined to be generic.

block_data_error = <ErrorCodes.block_data_error: -160>
block_data_not_allowed = <ErrorCodes.block_data_not_allowed: -168>
character_data_error = <ErrorCodes.character_data_error: -140>
character_data_not_allowed = <ErrorCodes.character_data_not_allowed: -148>
character_data_too_long = <ErrorCodes.character_data_too_long: -144>
command_error = <ErrorCodes.command_error: -100>
command_header_error = <ErrorCodes.command_header_error: -110>
data_type_error = <ErrorCodes.data_type_error: -104>
exponent_too_large = <ErrorCodes.exponent_too_large: -123>
expression_error = <ErrorCodes.expression_error: -170>
expression_not_allowed = <ErrorCodes.expression_not_allowed: -178>
get_not_allowed = <ErrorCodes.get_not_allowed: -105>
header_separator_error = <ErrorCodes.header_separator_error: -111>
header_suffix_out_of_range = <ErrorCodes.header_suffix_out_of_range: -114>
invalid_block_data = <ErrorCodes.invalid_block_data: -161>
invalid_character = <ErrorCodes.invalid_character: -101>
invalid_character_data = <ErrorCodes.invalid_character_data: -141>
invalid_character_in_number = <ErrorCodes.invalid_character_in_number: -121>
invalid_expression = <ErrorCodes.invalid_expression: -171>
invalid_inside_macro_definition = <ErrorCodes.invalid_inside_macro_definition: -183>
invalid_outside_macro_definition = <ErrorCodes.invalid_outside_macro_definition: -181>
invalid_separator = <ErrorCodes.invalid_separator: -103>
invalid_string_data = <ErrorCodes.invalid_string_data: -151>
invalid_suffix = <ErrorCodes.invalid_suffix: -131>
macro_error = <ErrorCodes.macro_error: -180>
macro_parameter_error = <ErrorCodes.macro_parameter_error: -184>
missing_parameter = <ErrorCodes.missing_parameter: -109>
no_error = <ErrorCodes.no_error: 0>
numeric_data_error = <ErrorCodes.numeric_data_error: -120>
numeric_data_not_allowed = <ErrorCodes.numeric_data_not_allowed: -128>
operation_complete = <ErrorCodes.operation_complete: -800>
parameter_not_allowed = <ErrorCodes.parameter_not_allowed: -108>
power_on = <ErrorCodes.power_on: -500>
program_mnemonic_too_long = <ErrorCodes.program_mnemonic_too_long: -112>
request_control_event = <ErrorCodes.request_control_event: -700>
string_data_error = <ErrorCodes.string_data_error: -150>
string_data_not_allowed = <ErrorCodes.string_data_not_allowed: -158>
suffix_error = <ErrorCodes.suffix_error: -130>
suffix_not_allowed = <ErrorCodes.suffix_not_allowed: -138>
suffix_too_long = <ErrorCodes.suffix_too_long: -134>
syntax_error = <ErrorCodes.syntax_error: -102>
too_many_digits = <ErrorCodes.too_many_digits: -124>
undefined_header = <ErrorCodes.undefined_header: -113>
unexpected_number_of_parameters = <ErrorCodes.unexpected_number_of_parameters: -115>
user_request_event = <ErrorCodes.user_request_event: -600>
SCPIInstrument.check_error_queue()

Checks and clears the error queue for this device, returning a list of SCPIInstrument.ErrorCodes or int elements for each error reported by the connected instrument.

SCPIInstrument.clear()

Clear instrument. Consult manual for specifics related to that instrument.

SCPIInstrument.reset()

Reset instrument. On many instruments this is a factory reset and will revert all settings to default.

SCPIInstrument.trigger()

Send a software trigger event to the instrument. On most instruments this will cause some sort of hardware event to start. For example, a multimeter might take a measurement.

This software trigger usually performs the same action as a hardware trigger to your instrument.

SCPIInstrument.wait_to_continue()

Instruct the instrument to wait until it has completed all received commands before continuing.

SCPIInstrument.display_brightness

Brightness of the display on the connected instrument, represented as a float ranging from 0 (dark) to 1 (full brightness).

Type: float
SCPIInstrument.display_contrast

Contrast of the display on the connected instrument, represented as a float ranging from 0 (no contrast) to 1 (full contrast).

Type: float
SCPIInstrument.line_frequency

Gets/sets the power line frequency setting for the instrument.

Returns: The power line frequency Hertz Quantity
SCPIInstrument.name

The name of the connected instrument, as reported by the standard SCPI command *IDN?.

Return type: str
SCPIInstrument.op_complete

Check if all operations sent to the instrument have been completed.

Return type: bool
SCPIInstrument.power_on_status

Gets/sets the power on status for the instrument.

Type: bool
SCPIInstrument.scpi_version

Returns the version of the SCPI protocol supported by this instrument, as specified by the SYST:VERS? command described in section 21.21 of the SCPI 1999 standard.

SCPIInstrument.self_test_ok

Gets the results of the instrument’s self test. This lets you check if the self test was sucessful or not.

Return type: bool

## SCPIMultimeter - Generic multimeter using SCPI commands¶

class instruments.generic_scpi.SCPIMultimeter(filelike)

This class is used for communicating with generic SCPI-compliant multimeters.

Example usage:

>>> import instruments as ik
>>> inst = ik.generic_scpi.SCPIMultimeter.open_tcpip("192.168.1.1")
>>> print(inst.measure(inst.Mode.resistance))

class InputRange

Valid device range parameters outside of directly specifying the range.

automatic = <InputRange.automatic: 'AUTO'>
default = <InputRange.default: 'DEF'>
maximum = <InputRange.maximum: 'MAX'>
minimum = <InputRange.minimum: 'MIN'>
class SCPIMultimeter.Mode

Enum of valid measurement modes for (most) SCPI compliant multimeters

capacitance = <Mode.capacitance: 'CAP'>
continuity = <Mode.continuity: 'CONT'>
current_ac = <Mode.current_ac: 'CURR:AC'>
current_dc = <Mode.current_dc: 'CURR:DC'>
diode = <Mode.diode: 'DIOD'>
fourpt_resistance = <Mode.fourpt_resistance: 'FRES'>
frequency = <Mode.frequency: 'FREQ'>
period = <Mode.period: 'PER'>
resistance = <Mode.resistance: 'RES'>
temperature = <Mode.temperature: 'TEMP'>
voltage_ac = <Mode.voltage_ac: 'VOLT:AC'>
voltage_dc = <Mode.voltage_dc: 'VOLT:DC'>
class SCPIMultimeter.Resolution

Valid measurement resolution parameters outside of directly the resolution.

default = <Resolution.default: 'DEF'>
maximum = <Resolution.maximum: 'MAX'>
minimum = <Resolution.minimum: 'MIN'>
class SCPIMultimeter.SampleCount

Valid sample count parameters outside of directly the value.

default = <SampleCount.default: 'DEF'>
maximum = <SampleCount.maximum: 'MAX'>
minimum = <SampleCount.minimum: 'MIN'>
class SCPIMultimeter.SampleSource

Valid sample source parameters.

1. “immediate”: The trigger delay time is inserted between successive

samples. After the first measurement is completed, the instrument waits the time specified by the trigger delay and then performs the next sample.

2. “timer”: Successive samples start one sample interval after the

START of the previous sample.

immediate = <SampleSource.immediate: 'IMM'>
timer = <SampleSource.timer: 'TIM'>
class SCPIMultimeter.TriggerCount

Valid trigger count parameters outside of directly the value.

default = <TriggerCount.default: 'DEF'>
infinity = <TriggerCount.infinity: 'INF'>
maximum = <TriggerCount.maximum: 'MAX'>
minimum = <TriggerCount.minimum: 'MIN'>
class SCPIMultimeter.TriggerMode

Valid trigger sources for most SCPI Multimeters.

“Immediate”: This is a continuous trigger. This means the trigger signal is always present.

“External”: External TTL pulse on the back of the instrument. It is active low.

“Bus”: Causes the instrument to trigger when a *TRG command is sent by software. This means calling the trigger() function.

bus = <TriggerMode.bus: 'BUS'>
external = <TriggerMode.external: 'EXT'>
immediate = <TriggerMode.immediate: 'IMM'>
SCPIMultimeter.measure(mode=None)

Instruct the multimeter to perform a one time measurement. The instrument will use default parameters for the requested measurement. The measurement will immediately take place, and the results are directly sent to the instrument’s output buffer.

Method returns a Python quantity consisting of a numpy array with the instrument value and appropriate units. If no appropriate units exist, (for example, continuity), then return type is float.

Parameters: mode (Mode) – Desired measurement mode. If set to None, will default to the current mode.
SCPIMultimeter.input_range

Gets/sets the device input range for the device range for the currently set multimeter mode.

Example usages:

>>> dmm.input_range = dmm.InputRange.automatic
>>> dmm.input_range = 1 * pq.millivolt

Units: As appropriate for the current mode setting. Quantity, or InputRange
SCPIMultimeter.mode

Gets/sets the current measurement mode for the multimeter.

Example usage:

>>> dmm.mode = dmm.Mode.voltage_dc

Type: Mode
SCPIMultimeter.relative
SCPIMultimeter.resolution

Gets/sets the measurement resolution for the multimeter. When specified as a float it is assumed that the user is providing an appropriate value.

Example usage:

>>> dmm.resolution = 3e-06
>>> dmm.resolution = dmm.Resolution.maximum

SCPIMultimeter.sample_count

Gets/sets the number of readings (samples) that the multimeter will take per trigger event.

The time between each measurement is defined with the sample_timer property.

Note that if the trigger_count propery has been changed, the number of readings taken total will be a multiplication of sample count and trigger count (see property SCPIMulimeter.trigger_count).

If specified as a SampleCount value, the following options apply:

1. “minimum”: 1 sample per trigger
2. “maximum”: Maximum value as per instrument manual
3. “default”: Instrument default as per instrument manual

Note that when using triggered measurements, it is recommended that you disable autorange by either explicitly disabling it or specifying your desired range.

Type: int or SampleCount
SCPIMultimeter.sample_source

Gets/sets the multimeter sample source. This determines whether the trigger delay or the sample timer is used to dtermine sample timing when the sample count is greater than 1.

In both cases, the first sample is taken one trigger delay time period after the trigger event. After that, it depends on which mode is used.

SCPIMultimeter.sample_timer

Gets/sets the sample interval when the sample counter is greater than one and when the sample source is set to timer (see SCPIMultimeter.sample_source).

This command does not effect the delay between the trigger occuring and the start of the first sample. This trigger delay is set with the trigger_delay property.

Units: As specified, or assumed to be of units seconds otherwise. Quantity
SCPIMultimeter.trigger_count

Gets/sets the number of triggers that the multimeter will accept before returning to an “idle” trigger state.

Note that if the sample_count propery has been changed, the number of readings taken total will be a multiplication of sample count and trigger count (see property SCPIMulimeter.sample_count).

If specified as a TriggerCount value, the following options apply:

1. “minimum”: 1 trigger

2. “maximum”: Maximum value as per instrument manual

3. “default”: Instrument default as per instrument manual

4. “infinity”: Continuous. Typically when the buffer is filled in this

case, the older data points are overwritten.

Note that when using triggered measurements, it is recommended that you disable autorange by either explicitly disabling it or specifying your desired range.

Type: int or TriggerCount
SCPIMultimeter.trigger_delay

Gets/sets the time delay which the multimeter will use following receiving a trigger event before starting the measurement.

Units: As specified, or assumed to be of units seconds otherwise. Quantity
SCPIMultimeter.trigger_mode

Gets/sets the SCPI Multimeter trigger mode.

Example usage:

>>> dmm.trigger_mode = dmm.TriggerMode.external


## SCPIFunctionGenerator - Generic multimeter using SCPI commands¶

class instruments.generic_scpi.SCPIFunctionGenerator(filelike)

This class is used for communicating with generic SCPI-compliant function generators.

Example usage:

>>> import instruments as ik
>>> import quantities as pq
>>> inst = ik.generic_scpi.SCPIFunctionGenerator.open_tcpip("192.168.1.1")
>>> inst.frequency = 1 * pq.kHz

frequency

Gets/sets the output frequency.

Units: As specified, or assumed to be $$\text{Hz}$$ otherwise. float or Quantity
function

Gets/sets the output function of the function generator

Type: SCPIFunctionGenerator.Function
offset

Gets/sets the offset voltage of the function generator.

Set value should be within correct bounds of instrument.

Units: As specified (if a Quantity) or assumed to be of units volts. Quantity with units volts.
phase