Test Controller New Device

TestController, New device

This is a short explanation on how to add a new device, it will only explain principles and not details, but it contains links to the details.

Contents
    Overview
        Establish connection
        Add data columns
        Read values from device
        Add control of device
        Add off settings if relevant
        Optionally add #interface section, this is required for some TC functionality.
        If there are multiple similar devices add them
    Variable output data
        Selection of output data is done by mode selection in TestController
        Selection of output data is done on device or by device
    Adding advanced functions
    #scpiCmd
    General notes
SCPI device drivers
Non SCPI device drivers
Main page

Overview
First you need to find what type of protocol it uses, it can be SCPI, but not everything uses that.
When you have found protocol type, you need to match it to a TC supported protocol:
SCPI device drivers
Non SCPI device drivers
What is on the above two pages are the general protocols supported by TC. TC also has a list of more specialized protocols that I have not documented.

When you have the protocol you need to get a connection to the device, if TC already have something with the same type of protocol you can use that as a start.
For this part you start TC in debug mode, with only that device loaded.
The steps are:

Establish connection
Add data columns
Read values from device
Add control of device
Add off settings if relevant
Optionally add #interface section, this is required for some TC functionality.
If there are multiple similar devices add them

You will generally want to do you development and test of protocols in ..\documents\TestController\Devices it is the place for user defined devices.

Establish connection

For SCPI or SCPIx there is a shortcut: Select "Load devices" page, right click on "Search socket" and select "Create new SCPI definition"

For all other devices a new txt file must manually be create and formatted as a device definition, place the file in ..\documents\TestController\Devices. The easiest way to do this is usually to copy a existing definition and use that as a starting point.
For this step it only need to contain the most rudimentary definitions, it will typically contains some of these and may contain a few other:

#idString
#name
#handle
#port
#baudrate
#drive

To find out exactly which ones check the protocol description for the desired protocol.

Device drivers overview

Add data columns

Data columns must match the type of data the device returns, if the device can switch between different data there must be defined columns for all of them and some definitions may contain a selector to enable/disable that data type.

For this use: #value

For definitions without a select, restart TestController and check the "Current values" page, it will show all the defined columns (On this page they are shown as row, on the table page they are shown as columns).

Data type definitions

Read values from device

Define the commands used to read the data, it can be one or more command and it is possible to make some commands optional.

These commands are placed after #askValues like this:

Fetch 3 values:
#askValues :meas:volt?;:meas:curr?;:meas:pow?

Fetch 6 values, this is formatted on multiple lines to make it more human readable, TestController ignore this.
#askValues
MEASure:VOLTage? (@1); MEASure:CURRent? (@1);
MEASure:VOLTage? (@2); MEASure:CURRent? (@2);
MEASure:VOLTage? (@3); MEASure:CURRent? (@3);

Fetch 1 value depending on mode:
#askValues [MODE:Frequency,Period,Duty_Cycle,Pulse_Width]:Read?;[MODE:Count]:FETC:ARR? -1;

To interpret the numbers it is sometimes necessary to add some special processing of the received values:
The first is a simple format specifier, the second one is a expression to process the raw input data:
#askValuesReadFormat
#askValuesMathFormat

Before the reading commands work, the device may need to be initialized with one of:
#initCmd
#prepareSample

The first is usually used to disable manual control of the device and may switch it to a known state.

When TestController stops commands to enable manual control and turn and output off is a good idea, they are placed here:

#finalCmd

Basic communication

Add control of device

For devices that allows control over the communication line, this is done with these two definitions:

This one is used for settings that changes what data the device returns, that will typically be bench multimeters, but some other devices also qualify. These commands can only be used when not logging:
#cmdMode

For all other parameters use this definition, it is much more flexible and can be used at any time. TestController will build a form with the definitions:
#cmdSetup

Selecting mode
Configuration menu

Add off settings if relevant

With multi device setups it is nice to have a fast way to disable everything, especially if something goes wrong, this definition handles that.
It is usually used for power supplies, loads and generators.

It needs one or more commands that will turn the power off after this:
#outputOff

In TestController this command is invoked when writing "#off" on the command line or in a script, the button "Outputs off" and the alarm popup can also perform these command. They will be transmitted in parallel to all devices for a fast response.

Optionally add #interface section, this is required for some TC functionality.

The interface section will categorize the device, this can be used in scripts to fetch a device of this type.
It can also define some standardized command to control a device, making it more device independent when used from a script, these standardized commands is also used from some places in TestController and devices without the commands will not be supported for these functions.

For using the first found power supply (with defined interface) to deliver 5V use this script:
=var ps=getDevice("PS");
=setVoltage(ps,5);
=setCurrent(ps,1);
=setOn(ps,1);
This is very nice with scripting, because the script will work with nearly any power supply or other device and not only one specific brand/model.

A generic interface

If there are multiple similar devices add them

Often a manufacturer makes a series of devices with same functions and that uses the same protocol, only difference is range for some of the selections. Instead of making a new definition for each device it is possible to transform a definition to a abstract definition and then let TestController make multiple concrete definitions for the different devices in the series.
This is done with #meta and #metadef
Generally the concrete definition will not be visible, but only exist inside TestController, but there are debug options to save them.

Creating multiple devices from one configuration file

Variable output data

Some devices do not have a fixed set of output data, DMM are the most obvious type where output data can be volt/current/resistance depending on range. These devices requires some special settings in TestController.
These setting establish mode names and these mode names can be used to select what #value statements are used. In the #askValues statement it is possible to adjust the commands depending on active modes.
Usually only one mode name is active, but it is possible to have multiple mode names.

Selection of output data is done by mode selection in TestController

This is typically for bench meters.

TestController will have a popup for selected modes, this popup is defined with a list of #cmdMode

Each time a mode is selected TestController will use a #askMode to get the actual mode of the device, the answer to this command may be processed with #askModeMathFormat to isolate the actual mode.

The internal mode name will be changed by the #cmdMode statement to the modeLabel specified in the command.

Selecting mode
#askMode

Selection of output data is done on device or by device

This generally includes handheld DMM's and LCR meters.

Because TC do not automatic see that new data types are selected, it must be part of the definition and it is usually one of the statements after #askValues or it can be deducted by the units in the answer to #askValues.

To process the #askValues answer for modes use #modeFromValue, it is also required to avoid the modes affect the values in #askValues, this is done with #askValuesReadFormat and #askValuesMathFormat

The #modeFromValue do not require a command but will have to process the answer received by #askValues and instead of isolating the values, it must isolate the modes.

If no matching #cmdMode exist, the mode name will be the string returned by #modeFromValue or #askMode

#modeFromValue

Adding advanced functions

I addition to support for standard command, TestController also has a section where it is possible to add programs to support a device. This can be to download log files or fetch screen shots, but many other functions can be made.

The Other popup

#scpiCmd

This definition is valid in many drivers, even though it is not explicit explained

The actual functionality of #scpiCmd is always the same, but the commands that can be used will vary by definition. There is a way to define #scpiCmd so it is a program, not just commands.
Be aware that #scpiCmd must not call another #scpiCmd, only one can be active at a time.

One very important thing about #scpiCmd is that they share variables and that they are retained between calls.

#scpiCmd
Defining commands

General notes

The SCPI driver is the basic for most drives, this means setting described for SCPI will often also work for other drivers.