# Connecting to the instrument

In this tutorial, we demonstrate how to connect to the SHFQA using a Python API and observe the configured changes in the general user interface.

## Goals and Requirements

In this tutorial you learn how to: * connect to the instrument using Python * control the Input/Output settings of the instrument using nodes.

 This tutorial is applicable to all SHFQA Instruments and no additional instrumentation is needed.

## Preparation

The tutorial starts with the instrument in the default configuration (e.g., after a power cycle). For an optimal tutorial experience, please follow these preparation steps:

• ensure that the version of ziPython, LabOne and the Firmware of the SHFQA device are updated and compatible,

• make sure that the instrument is powered on and connected by Ethernet to your local area network (LAN) where the host computer resides,

• start LabOne and open the LabOne graphical user interface using the default web browser,

• prepare an empty python script.

 You may also use a USB instead of Ethernet connection. If you do so, use the port labeled "Maintenance" on the back panel rather than the port labeled "USB". The latter is not supported with LabOne 21.08 and will be enabled with a future LabOne release.
 When connecting cables to the instrument’s SMA ports, use a torque wrench specified for brass core SMA (4 in-lbs, 0.5 Nm). Using a standard SMA torque wrench (8 in-lbs) or a wrench without torque limit can break the connectors.

## Tutorial

First we connect to the SHFQA using Python. For this we first open a daq-session to the device_id-instrument using and by replacing devXXXXX with the id of our SHFQA instrument, e.g. 12024):

# Load the LabOne API
import zhinst.ziPython as zi
import zhinst.utils as utils

device_id='devXXXXX'
apilevel_example=6

# Alternative 1
(daq, device_id) = zhinst.utils.create_api_session(
device_id, apilevel_example
)

# Alternative 2
server_host = 'localhost'
server_port = 8004

## connect to data server
daq = zi.ziDAQServer(host=server_host, port=server_port, api_level=6)

## connect to device
device_interface = '1gbe'
daq.connectDevice(device_id, device_interface)

Alternative 1 can be used when the host computer resides in the same network as the instrument. Alternative 2 does the same, but can be used to define the data server and port - for example when a remote connection needs to be established to the instrument. Remember that for a remote connection, Connectivity needs to be set From Everywhere.

After successful running the above code snippet, we check whether the Data Server version is compatible with the ziPython by evaluating:

utils.api_server_version_check(daq)

If it returns True, we are now in the position to access the device, otherwise please update your API version.

The first parameters that need to be set for every experiment are the Center Frequency and Ranges of the Channel. For this, open the In/Out tab of the GUI and select the All-subtab. In our Python script, we use the following code snippet to set the nodes for the Center Frequency of Channel 2 to 6 GHz, and the Input and Output Ranges to 0 and -10 dBm, respectively.

device_name='dev'+device_id
qa_channel=1

rf_frequency = 6.0 # GHz
daq.setDouble(f'/\{device_name}/QACHANNELS/\{qa_channel}/CENTERFREQ', rf_frequency*1e9)
input_range = 0.0
daq.setDouble(f'/\{device_name}/QACHANNELS/\{qa_channel}/INPUT/RANGE', input_range)
output_range = -10.0
daq.setDouble(f'/\{device_name}/QACHANNELS/\{qa_channel}/OUTPUT/RANGE', output_range)

Observe how the corresponding GUI values in the second panel of the In/Out tab change their values correspondingly.

 Note that although in the GUI and on the front panel of the instrument, lists (e.g. Channel numbers) always start at 1, however all representations in the APIs start counting at 0. Hence, Channel 2 on the front panel corresponds to qa_channel=1 in the API.
 To find out which node is linked to a specific setting in the GUI, either checkout the command log at the bottom of the user interface or the node tree documentation.

If we set an invalid value, e.g. a value of 6.05 GHz for the Center Frequency (Note that this value can only be set in multiples of 100 MHz) through

daq.setDouble(f'/\{device_name}/QACHANNELS/\{qa_channel}/CENTERFREQ', 6.05*1e9)

then the instrument rounds the value automatically to the nearest possible value (here: 6.1 GHz). This is immediately indicated in the GUI or through reading the node value in Python using the get-command:

daq.getDouble(f'/\{device_name}/QACHANNELS/\{qa_channel}/CENTERFREQ')