# Connecting to the instrument

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

## Goals and Requirements

In this tutorial you will learn how to:

• connect to the instrument using Python

• control the Output settings of the instrument using nodes.

 This tutorial is applicable to all SHFSG 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 SHFSG 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 SHFSG using Python. For this we first open a daq-session to the device_id-instrument using the following code and by replacing devXXXXX with the id of our SHFSG instrument, e.g. 12050):

# 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 Output Channel. To see the parameter updates that will be performed by the Python script, open the Output 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 1 to 6 GHz and the Output Range to 10 dBm.

device_name='dev'+device_id
sg_channel=0
synth = 0

rf_frequency = 6.0 # GHz
daq.setDouble(f'/{device_name}/SYNTHESIZERS/{synth}/CENTERFREQ', rf_frequency*1e9)
output_range = 10.0
daq.setDouble(f'/{device_name}/SGCHANNELS/{sg_channel}/OUTPUT/RANGE', output_range)

Observe how the corresponding GUI values in the first panel of the Output tab change their values correspondingly. Note that in both 4- and 8-channel variants of the SHFSG, there are 4 synthesizers. In the 8-channel variant, channel pairs therefore share one synthesizer, which is why the synthesizer frequencies are set using the /{device_name}/SYNTHESIZERS/{synth}/CENTERFREQ node and not within the /{device_name}/SGCHANNELS/ branch. To check which synthesizer is being used by a particular SGCHANNEL, you can use the get command:

daq.getInt(f'/{device_name}/SGCHANNELS/{sg_channel}/SYNTHESIZER')
 Note that in the GUI and on the front panel of the instrument, lists (e.g. Channel numbers) always start at 1, but all representations in the APIs start counting at 0. Hence, Channel 1 on the front panel corresponds to sg_channel=0 in the API.
 To find out which node is linked to a specific setting in the GUI, either check out 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}/SYNTHESIZERS/{synth}/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}/SYNTHESIZERS/{synth}/CENTERFREQ')