Test Controller Interface definitions

Test controller, Interface definition

This page contains concrete recommendations for #interface definitions depending on device. I have split it into sections:

Primary: These are needed, if the device must support all popups in TC
Secondary: These are optional, but TC may use them if they are present.
Tertiary: TC do not use these at the current time.

I will not show the actual implementation of the different interfaces here, check some device definitions to see examples.
If a device do not support a specific function, do not implement a dummy version of the interface, just leave it out.
It is always accepted to implement more #interface definition than listed here, as long as they follow the same style of names and functions.
This list will be expanded over time.
#interface is not mandatory for a driver to implement, but if it is missing the device may not be supported everywhere in TC.
The second purpose of #interface definitions is for people that makes script to be fairly independent of actual device used, i.e. a script can work with most devices of the same type without changes.
#interfaceType is not mandatory for a driver to implement, but is useful for classifying the driver, it can be added without any #interface definitions.

Contents
    General rules
    DMM
        Primary DMM
        Secondary DMM
    Power
        Primary power
        Secondary power
        Tertiary power
    Power Supply
        Primary power supply
        Secondary power supply
        Tertiary power supply
    Load
        Primary load
        Secondary load
        Tertiary load
    AC supply, AC source
        Primary AC supply
        Tertiary AC supply
    Thermometer
        Primary thermometer
    Humidity
        Primary Humidity
    Relay
        Primary relay
        Secondary relay
        Tertiary relay
    Readout
        Primary readout
        Secondary readout
    Input
        Primary Input
    Output
        Primary Output
        Secondary output
    PWM
        Primary PWM
        Secondary PWM
    AInput
        Primary AInput
    AOutput
        Primary AOutput
        Secondary AOutput
        Tertiary AOutput
    Calibrator
        Primary Calibrator
        Secondary Calibrator
    RF generator
        Primary RF generator
        Secondary RF generator
    Notes
Main #interface manual
Main page

General rules

setOn() must not affect settings, only turn output on/off. I.e. this must be valid:
setVoltage(5);setOn(1); ...... setOn(0);setOn(1);...
Notice the output value is defined before the output is turned on and it will still be 5 volt after the second off/on cycle.
This is different from the #outputOff in the definition or setAllOff() here it is supposed to switch all outputs to off and if not possible turn them to 0.

For a device with multiple outputs or inputs the #interfaceType will contain a entry for each channel, like this:
#interfaceType relay relay:2 relay:3 relay:4 relay:5 relay:6 relay:7 relay:8

For a device with a mix of functions the #interfaceType will contain a entry for each type, like this:
#interfaceType humidity thermometer
#interfaceType input, input:2, input:3, input:4, output:5, output:6, output:7, output:8
#interfaceType input, input:2, input:3, input:4, output, output:1, output:2, output:3
The two input/output defines the same number of input/outputs, but they are addressed different. In the first one a getInputs() and getOutputs() may return the same value that contains both input and outputs, in the second one they will only contain either input or output and the address and bit position of outputs will be from 0-3.

#interface setAllOff() can be used for all devices with outputs, it will turn all channels off or if not possible set them to 0 output. To recover from this used setOn(1) to turn each channel on again. Note: a setOn(1) must not turn all channels on after a setAllOff() only the specified channel. This may mean that setAllOff() will both turn off a master and each channel where setOn(1) turns of the master and a single channel and setOn(0) turns off a single channel, but do not change master.

Generally scripts and popups are supposed to check if a specific #interface exist before calling it. For scripts saved as menu, it is possible to list required #interface's at the top and the script will only be visible if a device is loaded that supports it.

Values are always in basic SI units, it is never specified in mA or kohm, that conversion must be done in the definition or the device itself.

DMM

A multimeter is very simple:
#interfaceType DMM
If it is a multimeter that can be computer controlled use:
#interfaceType DMM BMM

Primary DMM

#interface readValue, return the current reading on the meter, usually the full definitions is: #interface readValue 0

Secondary DMM

#interface getMode, get the current mode of the meter*
#interface setMode, set the current mode of the meter*

Power

This is a power meter, it may be able to measure both AC and DC power, it is defined as:
#interfaceType Power
Power meters are fairly complex meters and often makes it possible to configure what they read, this do not work well with #interface. One way around that is to always defined the first 3 measurement as voltage current and power.

Primary power

#interface readVoltage, RMS voltage for DUT, will be the combination of DC and AC, if both are present
#interface readCurrent, RMS current for DUT, will be the combination of DC and AC, if both are present
#interface readPower, Real power for device, this will include both DC and AC power.

Secondary power

#interface readPowerFactor, read the power factor, this is the same as power/(voltage*current)
#interface readVA, read the power, including reactive power, this is the same as voltage*current
#interface readFrequency, read the fundamental frequency of the power (usual 50 or 60Hz)

Tertiary power

#interface readVoltageTHD read the total harmonic distortion (THD) of the voltage
#interface readCurrentTHD read the total harmonic distortion (THD) of the current

Power Supply

TC uses ps as type for power supplies.
for a single channel power supply this means:
#interfaceType ps
For a 3. channel power supply use this (This will affect all #interface definitions):
#interfaceType ps ps:2 ps:3

Primary power supply

#interface setCurrent, Set the constant current limit
#interface getCurrent, Read the constant current limit
#interface setVoltage, Set the output voltage
#interface getVoltage, Read the defined output voltage
#interface readCurrent, Read the actual output current
#interface readVoltage, Read the actual output voltage
#interface setOn, set the device on or off, this must be with 1 for one and 0 for off, if the power supply wants the words on/off this definitions must do the translation from 1/0 to on/off. If the power supply has two levels (channel and global) to enable output, this must turn both on, but only turn channel off.
#interface getOn, get the current output state: on/off.

Secondary power supply

#interface setRemoteSense, enable/disable remote sense, 1=on, 0=off
#interface getRemoteSense, Read status of remote sense, if readback is not support leave this one out.
#interface setAllOff, turn off all outputs, no parameter is used, this is similar to the #outputOff from the definition.

Tertiary power supply

#interface setMaxCurrent, set a upper limit on current, power supply will refuse to accept higher settings and/or turn output off.
#interface getMaxCurrent, get the max set current value.
#interface setMaxVoltage, set a upper limit on voltage, power supply will refuse to accept higher settings and/or turn output off.
#interface getMaxVoltage, get the max set voltage value.

Load

A electronic load will use this type definition:
#interfaceType load
A duel channel load will use (This will affect all #interface definitions):
#interfaceType load load:2

Primary load

#interface setCurrent, Set load to constant current and set the current.
#interface getCurrent, Read the constant current set above.
#interface setVoltage, Set the load to voltage mode and set the voltage.
#interface getVoltage, Read the voltage set above.
#interface readCurrent, Read the actual load current in any mode.
#interface readVoltage, Read the actual load voltage in any mode.
#interface setOn, set the device on or off, this must be with 1 for one and 0 for off, if the load wants the words on/off this definitions must do the translation from 1/0 to on/off.
#interface getOn, get the current load state: on/off.

Secondary load

#interface setRemoteSense, enable/disable remote sense, 1=on, 0=off
#interface getRemoteSense, Read status of remote sense, it readback is not support leave this one out.
#interface readPower, Read the actual load power in any mode.
#interface setAllOff, turn off all channels, no parameter is used, this is similar to the #outputOff from the definition.

Tertiary load

#interface setPower, Set the load to power mode and set the power.
#interface getPower, Read the power set above.
#interface setResistance, Set the resistance to power mode and set the resistance.
#interface getResistance, Read the resistance set above.
#interface setOCP, set a upper limit on current, load will refuse to accept higher settings and/or turn off.
#interface getOCP, get the max set current value.
#interface setOVP, set a upper limit on voltage, load will refuse to accept higher settings and/or turn off.
#interface getOVP, get the max set voltage value.
#interface setOPP, set a upper limit on power, load will refuse to accept higher settings and/or turn off.
#interface getOPP, get the max set power value.

AC supply, AC source

TC uses acps as type for AC power supplies, for a single channel AC power supply this means:
#interfaceType acps

Primary AC supply

#interface setCurrent, Set the current limit, if it is not supported leave this function out.
#interface getCurrent, Read the current limit, if it is not supported leave this function out.
#interface setVoltage, Set the output voltage
#interface getVoltage, Read the defined output voltage
#interface setFrequency, Set the output frequency
#interface getFrequency, Read the defined output frequency
#interface readCurrent, Read the actual output current
#interface readVoltage, Read the actual output voltage
#interface readPower, Read the actual load corrected for power factor.
#interface setOn, set the device on or off, this must be with 1 for one and 0 for off, if the power supply wants the words on/off this definitions must do the translation from 1/0 to on/off. If the power supply has two levels (channel and global) to enable output, this must turn both on, but only turn channel off.
#interface getOn, get the current output state: on/off.

Tertiary AC supply

#interface setMaxCurrent, set a upper limit on current, AC supply will refuse to accept higher settings and/or turn output off.
#interface getMaxCurrent, get the max set current value.
#interface setMaxVoltage, set a upper limit on voltage, AC supply will refuse to accept higher settings and/or turn output off.
#interface getMaxVoltage, get the max set voltage value.
#interface setMaxFrequency, set a upper limit on frequency, AC supply will refuse to accept higher settings and/or turn output off.
#interface getMaxFrequency, get the max set frequency value.
#interface setAllOff, turn off all outputs, no parameter is used, this is similar to the #outputOff from the definition.

Thermometer

A single channel thermometer will have this type:
#interfaceType thermometer
For more channels do this (Example is four channel):
#interfaceType thermometer thermometer:2 thermometer:3 thermometer:4

Primary thermometer

#interface readTemperature, return the temperature for this channel in Celsius.

Humidity

A humidity sensor will have this interface type:
#interfaceType humidity
It returns humidity in percent.
It will often also include a thermometer and they are allowed to share a channel, i.e. this is valid:
#interfaceType humidity thermometer

Primary Humidity

#interface readHumidity, return the humidity.

Relay

A single channel relay will be:
#interfaceType relay
But most relay interfaces are multichannel (Here a 8 channel):
#interfaceType relay relay:2 relay:3 relay:4 relay:5 relay:6 relay:7 relay:8

Primary relay

#interface setRelays, set all relays on the device from a bit mask where bit 0 is first relay, this ignores the multichannel aspect of a relay definition.
#interface getRelays, get a bitmask of all relays in on state, this ignores the multichannel aspect of a relay definition.
#interface setRelay, set a single relay 1=on, 0=off
#interface getRelay, get the status of a single relay.

Secondary relay

#interface setAllOff, turn off all relays, no parameter is used, this is similar to the #outputOff from the definition.

Tertiary relay

#interface getRelayArrangement, get the contact form of a single relay as the standard form letter:
- A normally open
- B normally closed
- C changeover, break before make
- D changeover, make before break.
- If the contact form is not known, leave this one out.

Readout

This is a single line display with a couple of digits that can be used to echo a value from testController.
Each digits is handled as a device, this makes it possible to address them individually.
Depending on function the device id specifies first digit that is affected, most functions will affect multiple digits.

For a 6 digit readout it will be:
#interfaceType readout readout:2 readout:3 readout:4 readout:5 readout:6

Primary readout

#interface setReadoutChar, set a character on a position of the readout
#interface getReadoutChar, get the shown character on a position of the readout
#interface setReadoutInteger, set readout to show an integer value
#interface getReadoutInteger, get the shown integer value of the readout
#interface setReadoutFloat, set readout to show a float value
#interface getReadoutFloat, get the shown float value of the readout
#interface setReadoutString, set readout to show string value
#interface getReadoutString, get the shown string content of the full readout

Secondary readout

#interface setReadoutBlink, set a character on a position of the readout to blink
#interface getReadoutBlink, get the blink status of a character position
#interface setReadoutSI, set readout to show value with SI prefix
#interface getReadoutSI, get the shown value with SI prefix of the readout

Input

Digital input that only detect two levels.
The return value is 0 or 1 for readIput, where 0=low=off, 1=high=on

Primary Input

#interface readInput, read a input bit for a single channel.
#interface readInputs, read all inputs as a bitmask, depending on hardware the bits can be intermixed with output and relay bits, but the bit numbers must match the channel numbers

Output

This is a digital output and similar to relays, but will deliver a voltage or current output when on (Relay is a switch that is on or off).
The setOn is only needed if device support on/off, just setting the output to zero is not acceptable. The #outputOff in the definition is supposed to switch all outputs to zero or turn them completely off.

Primary Output

#interface setOutputs, set all outputs on the device from a bit mask where bit 0 is first output, this ignores the multichannel aspect of a output definition.
#interface getOutputs, get a bitmask of all outputs in on state, this ignores the multichannel aspect of a output definition. This can be intermixed with inputs, but the bitnumbers must match the channel numbers.
#interface setOutput, set a single output 1=on, 0=off
#interface getOutput, get the status of a single output.

Secondary output

#interface setOn, set the device on or off, this must be with 1 for one and 0 for off.
#interface setAllOff, turn off all outputs, no parameter is used, this is similar to the #outputOff from the definition.

PWM

This is a device with controlled PWM output. Output can be either a voltage, current or a switched output (i.e. OC).

Primary PWM

#interface setDutyCycle The duty cycle of the signal, from 0 to 100.
#interface getDutyCycle get the selected duty cycle of the signal, from 0 to 100.
#interface setFrequency The frequency used for PWM
#interface getFrequency get the frequency
#interface setOn Turn PWN on or off for selected channel
#interface getOn Get on status.

Secondary PWM

#interface setAllOff Turn all PWM channels off.

AInput

Analog input, typical 0-10V or 0-20mA inputs, but can be other values.
Only one of the primary functions will usually be defined.

Primary AInput

#interface readVoltage, return the voltage for the channel
#interface readCurrent, returns the current for the channel
#interface readValue, this is used for devices where input can be switched between voltage and current for a channel

AOutput

Analog output, typical 0-10V or 0-20mA outputs, but can be other values.
If the device can switch between voltage/current it will switch when the relevant set command is used. Devices with either voltage or current will only implement commands for that.
The setOn is only needed if device support on/off, just setting the output to zero is not acceptable. The #outputOff in the definition is supposed to switch all outputs to zero or turn them completely off.
Also remember current is always in ampere, it is never specified in mA, that conversion must be done in the definition or the device itself.

Primary AOutput

#interface setVoltage, set voltage on a channel, if the output mode is switchable this will switch to voltage mode.
#interface getVoltage, read the set voltage on a channel
#interface setCurrent, set current on a channel, if the output mode is switchable this will switch to current mode.
#interface getCurrent, read the set current on a channel

Secondary AOutput

#interface readVoltage, return the actual voltage for the channel, this can be for either current or voltage channel.
#interface readCurrent, returns the actual current for the channel, this can be for either current or voltage channel.
#interface setOn, set the device on or off, this must be with 1 for one and 0 for off.
#interface setAllOff, turn off all outputs, no parameter is used, this is similar to the #outputOff from the definition.

Tertiary AOutput

#interface getAOutputArrangement, get the output type of a single channel as a single string:
- Voltage
- Current

Calibrator

Analog output with very precise levels, this will usually be one channel only and may support more output types that analog output
If the device can switch between output types it will switch when the relevant set command is used. Only commands for support output types will be present.
The setOn is only needed if device support on/off, just setting the output to zero is not acceptable. The #outputOff in the definition is supposed to switch all outputs to zero or turn them completely off.
Also remember values are always in basic SI units, it is never specified in mA or kohm, that conversion must be done in the definition or the device itself.

Primary Calibrator

#interface setVoltage, set voltage on a channel, if the output mode is switchable this will switch to voltage mode.
#interface getVoltage, read the set voltage on a channel
#interface setCurrent, set current on a channel, if the output mode is switchable this will switch to current mode.
#interface getCurrent, read the set current on a channel
#interface setResistance, set resistance on a channel, if the output mode is switchable this will switch to resistance mode.
#interface getResistance, read the set resistance on a channel
#interface setTemperature, set temperature on a channel, if the output mode is switchable this will switch to temperature mode.
#interface getTemperature, read the set temperature on a channel
#interface setThermoSensor, set simulated sensor for temperature, it can be a single letter for thermocouplers
#interface getThermoSensor, read simulated sensor for temperature, it can be a single letter for thermocouplers

Secondary Calibrator

#interface readVoltage, return the actual voltage for the channel, this can be for any mode.
#interface readCurrent, returns the actual current for the channel, this can be for any mode.
#interface setOn, set the device on or off, this must be with 1 for one and 0 for off.
#interface setAllOff, turn off all outputs, no parameter is used, this is similar to the #outputOff from the definition.

RF generator

Signal generator that can output variable frequencies in MHz and GHz range

Primary RF generator

Secondary RF generator

Notes

*These #interface definition may be redefined at a later data