Command

A command reads, writes, or writes/reads an instrument. The commands of an instrument are imported from the spreadsheet: “commands.csv”. Default values are used if a cell in the CSV file is left empty.

The columns of the CSV spreadsheet are:

  • name: The name of the command (key of the Python dictionary)
  • ascii_str: The string sent to the instrument upon set after the value is appended.
  • ascii_str_get: The string sent to the instrument. Default is ‘ascii_str?’
  • getter: Is this command a getter? (bool)
  • getter_type: Desired value returned by the getter, maps to Python conversion functions.
  • setter: Is this command a setter? (bool)
  • setter_type: Expected type of the setter value.
  • setter_range: Allowed range of the setter value. Can be a numeric list of [min, max] or a list of allowed options.
  • doc: Help message.
  • subsystem: Subsystem of the command (simply for organizing help).
  • is_config: Is this an instrument configuration that should be read as metadata at the start and end of every experiment?
  • setter_inputs: The number of setter inputs (default of 1 which is the value).
  • getter_inputs: The number of getter inputs (default of 0).

Example commands.csv

Below, portions of the the commands.csv file for the SRS810 digital lock-in amplifier are used to explain the format of an instrument Command.

Simple Command (phase)

Example of a simple command that uses many default values.
name ascii_str ascii_str_get getter getter_type setter setter_type setter_range doc subsystem is_config setter_inputs getter_inputs
phase PHAS   TRUE float TRUE float [-360.0, 729.99] Phase shift in degrees ref_phase TRUE    

The command phase is both a setter and getter. On set, ‘PHAS value’ is written to the instrument. On get, the instrument receives the query of ‘PHAS?’. The value returned by the instrument is converted to a float (determined by getter_type). phase is an instrument configuration (is_config = TRUE) and is appropriate for logging into metadata before and after experiments.

Complex Command (ch1_disp)

Example of a complex command that requires a config dictionary input upon set.
name ascii_str ascii_str_get getter getter_type setter setter_type setter_range doc subsystem is_config setter_inputs getter_inputs
ch1_disp DDEF {value} {ratio} DDEF? TRUE byte_array_to_numarray TRUE int [0, 4] CH1 display to X, R, Xn, Aux 1or Aux 2 (j=0..4) and ratio the display to None, Aux1or Aux 2 (k=0,1,2). disp_out TRUE 2  

The command ch1_disp an input, ratio, in addition to the `value input. The may be referred to as a long setter. The syntax of this set is:

ret = lia.set(value = 'R', name = 'ch1_disp', configs = {'ratio': 0})

The configs dictionary must have keys that match all of the format keys in the ascii_str of the command.

The Command Class

class command.Command(name, ascii_str='', ascii_str_get='', getter=True, getter_type=<class 'float'>, setter=True, limits=None, setter_type=<class 'float'>, doc='', subsystem=None, getter_inputs=None, setter_inputs=None, lookup={}, is_config=False, getter_override=None, setter_override=None, returns_image=False)[source]

A command to be sent to an instrument

Todo

  • Add a switch to enable or disable the lookup table
  • defaults for long getters and setters
  • long getters/setters: need range requirements and names for 2nd and beyond getter inputs
Parameters:
name : string

The name of the command, used as lookup key to the instrument’s dictionary of commands

ascii_str : string

What is sent to the instrument.

ascii_str_get : string, optional

What is sent to the instrument when getting a value. If not specified ‘ascii_str’ will be used.

getter : Boolean

Is this command a getter?

getter_type : function, float

Converts the instrument returned value to a new type for processing. Example: float

setter : Boolean

Is this command a setter?

limits : list

Minimum and maximum allowed values for the set operation.

setter_type : function, float

Currently not used; may be used to check if set value is the proper type

doc : string, optional

Documentation for this command; will be printed with help.

subsystem : string, optional

The subsystem (of the instrument) that this command fits into Used for organization help information.

getter_inputs : list (of strings), optional

For non-conventional get functions (long getters) that send extra parameters. This is a list of the input parameters that are needed. These are keys to the config dictionary.

setter_inputs : list (of strings), optional

For non-conventional set functions (long setters) that send extra parameters (beyond ‘value’). This is a list of the input parameters that are needed. These are keys to the config dictionary.

lookup : dictionary, optional

A lookup table for values that can be mapped to more human-readable results. E.g. lookup = {‘SLOW’: 0, ‘FAST’: 1} The keys are the human-readable names, the dictionary values are what is sent and received from the instrument.

is_config : bool, optional

is a “configuration” variable that should be measured and logged at the start and end of an experiment.

getter_override : function, optional

run this upon get

setter_override: function

runs this upon set

returns_image: bool, optional (defaults to False)

does this command return an array or image (a value that cannot be stored in the NoSQL database)