Utils¶
| Name | short Description |
|---|---|
| ziAPIServerVersionCheck | Check the versions of API and Data Server match |
| ziAutoConnect | Create a connection to a Zurich Instruments server (Deprecated: See ziCreateAPISession). |
| ziAutoDetect | Return the ID of a connected device (if only one device is connected) |
| ziBW2TC | Convert demodulator 3dB bandwidth to timeconstant |
| ziCheckPathInData | Check whether a node is present in data and non-empty |
| ziCreateAPISession | Create an API session for the specified device with the correct Data Server. |
| ziDevices | Return a cell array of connected Zurich Instruments devices |
| ziDisableEverything | Disable all functional units and streaming nodes |
| ziGetDefaultSettingsPath | Get the default settings file path from the ziDeviceSettings ziCore module |
| ziGetDefaultSigoutMixerChannel | return the default output mixer channel |
| ziLoadSettings | Load instrument settings from file |
| ziSaveSettings | Save instrument settings to file |
| ziSiginAutorange | Activate the device's autorange functionality |
| ziSystemtime2Matlabtime | Convert the LabOne system time to Matlab time |
| ziTC2BW | Convert demodulator timeconstants to 3 dB Bandwidth |
ziApiServerVersionCheck¶
function versionsMatch = ziApiServerVersionCheck()
Check the versions of API and Data Server match.
Returns:
Flag if the release version of the API used in the current session does have the same release version as the Data Server (that the API is connected to).
ziAutoConnect¶
function ziAutoConnect(defaultPort, APILevel)
Create a connection to a Zurich Instruments server for HF2 and UHF instruments
Note
ziAutoConnect does not support MFLI devices.
Try to connect to a Zurich Instruments server with an available HF2 or UHFLI device. First check if a device is found by connecting to a server on defaultPort, if so create and return a connection to that ziServer. If no devices are found on that server, check if a device is found on the secondary port, if so create and return a connection to that server. A runtime error is thrown if no devices are found.
Parameters
| Name | Description |
|---|---|
| defaultPort | default port to create the connection on (must be either 8004 (UHF) or 8005 (HF2)). If not specified both ports will be tried. |
| APILevel | API level to use for the connection (default = 1) |
ziApiServerVersionCheck¶
function device = ziAutoDetect()
Return the ID of a connected device (if only one device is connected).
Returns:
Device ID of the connected device.
ziBW2TC¶
function timeconstant = ziBW2TC(bandwidth, order)
Convert the demod 3 dB bandwidth to its timeconstant.
Convert the specified 3 dB bandwidths in bandwidth to its equivalent timeconstant for the specified demodulator order.
Parameters
| Name | Description |
|---|---|
| bandwidth | 3dB bandwidth |
| order | Demodulator order |
Returns:
timeconstant
ziCheckPathInData¶
function pathExists = ziCheckPathInData(data, path)
Check whether a node is present in data and non-empty
Return true or false, depending whether the path from the device node tree is present in data, where data is a structure typically returned by poll() or, e.g., sweep.read().
Note
Wildcards are not supported.
Parameters
| Name | Description |
|---|---|
| data | data structure (typically returned by poll or, e.g., sweep.read()) |
| path | path to search |
Returns:
Flag if the path is present in data
ziCreateAPISession¶
function [device, props] = ziCreateAPISession(device_serial, maximum_supported_apilevel, varargin)
Create an API session for the specified device.
Parameters
| Name | Description |
|---|---|
| device_serial | The device's ID, this is the string that specifies the device's xnode branch in the data server's node tree. |
| maximum_supported_apilevel | The maximum API Level that is supported by the Matlab code where the returned API session will be used. The maximum API Level you may use is defined by the device class. HF2 only supports API Level 1 and other devices support API Level 5. You should try to use the maximum level possible to enable extended API features. |
| required_devtype | The required device type, e.g., 'HF2LI' or 'MFLI'. This is given by the value of the device node '/devX/features/devtype' or the 'devicetype' discovery property. Raise an error if the device's devtype does not match the required_devtype. (default = .*) |
| required_options | The required device option set. This should be in the same format as returned by the 'options' property as returned by 'discoveryGet', e.g., {'PID', 'DIG'}, although the entry may be a regular expression, e.g., {'MFK|MF|MD', 'DIG'} if the required option functionality has a different name on different device classes. Raise an error if the device's option set does contain the required_options. (default = empty) |
| required_err_msg | An additional error message to print if either the device specified by the device_serial is not the required_devtype or does not have the required_options. (default = ``) |
Returns:
device: device id
props: device properties
ziDevices¶
function devices = ziDevices()
Return a cell array of devices that are currently connected to the server using the connection previously initiated by ziDAQ('connect').
Returns:
Cell array of devices connected to the server.
ziDisableEverything¶
function settings = ziDisableEverything(device)
Disable device streaming nodes and functionality
Put the device in a known base configuration: disable all extended functionality; disable all streaming nodes.
Warning
This function is intended as a helper function for the API's examples and it's signature or implementation may change in future releases.
Parameters
| Name | Description |
|---|---|
| device | device id of the device |
Returns:
A cell array of (set-function, node, value) triples containing the settings that were configured.
ziGetDefaultSettingsPath¶
function settings_path = ziGetDefaultSettingsPath()
Return a string containing the default path for LabOne settings files as defined in the ziCore Module ziDeviceSettings.
Returns:
Default path for LabOne settings files.
ziGetDefaultSigoutMixerChannel¶
function output_mixer_channel = ziGetDefaultSigoutMixerChannel(discovery_props, output_channel)
Return the instrument's default Signal Output mixer channel used by the hardware Signal Output channel specified by output_channel.
Parameters
| Name | Description |
|---|---|
| discovery_props | Device's discovery properties as returned by discoveryGet |
| output_channel | Hardware Signal Output channel |
Returns:
Instrument's default Signal Output mixer channel
ziLoadSettings¶
function ziLoadSettings(device, filename)
Load the settings from the LabOne settings file FILENAME to the specified device, e.g., 'dev1234'.
Parameters
| Name | Description |
|---|---|
| device | device id (e.g., 'dev1234'). |
| filename | Filepath to LabOne settings file. |
Examples
Load a settings file located in the current directory:
ziAutoConnect()
dev = ziAutoDetect()
ziLoadSettings(dev, 'my_settings.xml')
Load a settings file from the default LabOne settings path:
ziAutoConnect()
dev = ziAutoDetect()
filename = 'default_ui.xml'
default_path = ziGetDefaultSettingsPath()
ziLoadSettings(dev, [default_path, filesep, 'default_ui.xml'])
ziSaveSettings¶
function ziSaveSettings(device, filename)
Save the settings from device, e.g., 'dev1234', to the LabOne settings file.
Parameters
| Name | Description |
|---|---|
| device | device id (e.g., 'dev1234'). |
| filename | Filepath to LabOne settings file. |
Examples
Save a settings file in the current directory:
ziAutoConnect()
dev = ziAutoDetect()
ziSaveSettings(dev, 'my_settings.xml')
Save a settings file to the default LabOne settings path:
filename = 'default_ui.xml'
default_path = ziGetDefaultSettingsPath()
ziSaveSettings(dev, [default_path, filesep, 'default_ui.xml'])
ziSiginAutorange¶
function range = ziSiginAutorange(device, in_channel)
Perform an automatic adjustment of device's signal input channel and return the final range set. This utility function starts the functionality implemented in the device's firmware and waits until it has completed. The range is set by the firmware based on the measured input signal's amplitude measured over approximately 100 ms.
Requirements:
-
A device type that supports autorange functionality on the firmware level, e.g., UHFLI, MFLI, MFIA. For HF2 Instruments see the example hf2_example_autorange().
-
The ziDAQ API Session (connection to the device's Data Server) has already been initialised.
Parameters
| Name | Description |
|---|---|
| device | The device ID on which to perform the signal input autorange, e.g., 'dev2006' |
| in_channel | The index of the signal input channel to autorange. |
Returns:
Final range set.
ziSystemtime2Matlabtime¶
function matlabtime = ziSystemtime2Matlabtime(systemtime)
Convert the LabOne data header systemtime field (UINT64, microseconds since unix epoch) to a Matlab serial date number.
Parameters
| Name | Description |
|---|---|
| systemtime | LabOne data header systemtime field |
Returns:
Matlab serial date number.
ziTC2BW¶
function bandwidth = ziTC2BW(timeconstant, order)
Convert the specified timeconstant to the equivalent 3dB bandwidth for the specified demodulator order.
Parameters
| Name | Description |
|---|---|
| timeconstant | Timeconstant |
| order | Demodulator order |
Returns:
3dB bandwidth.