The MathWorks' numerical computing environment
MATLAB® has powerful tools for data analysis
and visualization that can be used to create graphical user interfaces
or automatically generate reports of experimental results in various
formats. LabOne’s MATLAB API, also known as
ziDAQ, "Zurich Instruments
Data Acquisition", enables the user to stream data from their instrument
directly into MATLAB allowing them to take full advantage of this
This chapter aims to help you get started using Zurich Instruments
LabOne’s MATLAB API,
ziDAQ, to control your instrument.
For a full reference of the MATLAB API visit the LabOne API documentation.
|The MATLAB examples can be downloaded from our GitHub repository.|
One of the following platforms and MATLAB versions (with valid license) is required to use the LabOne MATLAB API:
32 or 64-bit Windows with MATLAB R2009b or newer.
64-bit Linux with MATLAB R2016b or newer.
64-bit macOS and MATLAB R2013b or newer.
The LabOne MATLAB API
ziDAQ is included in a standard LabOne
installation and is also available as a separate package (see below,
Separate MATLAB Package). No installation as such
is required, only a few configuration steps must be performed to use
ziDAQ in MATLAB. Both the main LabOne installer and the separate
LabOne MATLAB API package are available from Zurich Instruments'
Separate MATLAB Package
The separate MATLAB API package should be used if you would like to:
No additional installation steps are required to use
ziDAQ on either
Windows, Linux or Mac; it’s only necessary to add the folder containing
LabOne’s MATLAB Driver to MATLAB’s search path. This is done as
Start MATLAB and either set the "Current Folder" (current working directory) to the MATLAB API folder in your LabOne installation or the extracted zip archive of the separate MATLAB API package (see above, Separate MATLAB Package) as appropriate.
If using a LabOne installation on Windows this is typically:
C:\Program Files\Zurich Instruments\LabOne\API\MATLAB\
and on Linux this is the location where you unpacked the LabOne
In the MATLAB Command Window, run the MATLAB script
ziAddPathlocated in the
On Windows (similar for Linux and Mac) you should see the following output in MATLAB’s Command Window:
Added ziDAQ's Driver, Utilities and Examples directories to MATLAB's path for this session. To make this configuration persistent across MATLAB sessions either: 1. Run the 'pathtool' command in the MATLAB Command Window and add the following paths WITH SUBFOLDERS to the MATLAB search path: C:\Program Files\Zurich Instruments\LabOne\API\MATLAB\ or 2. Add the following line to your MATLAB startup.m file: run('C:\Program Files\Zurich Instruments\LabOne\API\MATLAB\ziAddPath');
This is sufficient configuration if you would only like to use
ziDAQin the current MATLAB session.
To make this configuration persistent between MATLAB sessions do either one of the next two steps (as also indicated by the output of
pathtooland click "Add with Subfolders". Browse to the "MATLAB" directory that was located above in Step 1 and click "OK".
startup.mto contain the line indicated in the output from Step 2 above. For more help on MATLAB’s
startup.mfile, type the following in MATLAB’s Command Window:
Verify your MATLAB configuration as described in Verifying Successful MATLAB Configuration .
In order to verify that MATLAB is correctly configured to use
please perform the following steps:
Ensure that the correct Data Server is running for your HDAWG, HF2 or UHF Instrument (the Data Server on MF Instruments starts when the device is powered on). The quickest way to check is to start the User Interface for your device, see LabOne Software Architecture for more details.
Proceed either of the following two ways:
The easiest way to verify correct configuration is run one of the MATLAB API’s examples (see <<pm.matlab.github_repository). In the MATLAB command Window run, for example,
example_pollwith your device ID as the input argument:
>> example_poll('dev123'); % Replace with your device ID.
If this fails, please try issuing the
connectcommand, as described in the next method.
If a device is not currently available, correct MATLAB API configuration can be checked by initializing an API session to the Data Server without device communication.
An API session with the Data Server is created using
ziDAQ’s `connect(the port specifies which Data Server to connect to on the localhost) cf. Specifying the Data Server Hostname and Port ). In the MATLAB command window type one of the following:
* `>> ziDAQ('connect', 'localhost', 8005) % 8005 for HF2 Series` * `>> ziDAQ('connect', 'localhost', 8004, 6) % 8004 for HDAWG, UHFLI` * `>> ziDAQ('connect', mf-hostname, 8004, 6) % 8004 for MFLI (see below)`
'localhost'above assumes that the Data Server is running on the same computer from which you are using MATLAB. See Specifying the Data Server Hostname and Port for information about ports and host names when connecting to the Data Server. For MFLI instruments the hostname/IP address of the MFLI instrument must be provided (the value of
mf-hostname), see Specifying the Data Server Hostname and Port and the Getting Started chapter of the MFLI User Manual for more information.
If no error is reported then MATLAB is correctly configured to use
ziDAQ- congratulations! Otherwise, please try the steps listed in Troubleshooting the LabOne MATLAB API .
This section introduces the user to the LabOne MATLAB API.
Alongside the driver for interfacing with your Zurich Instruments
device, the LabOne MATLAB API includes many files for documentation,
utility functions and examples. See the
Contents.m file located in a
LabOne MATLAB API directory (see Step 1 in
Windows, Linux or Mac for its
typical location) for a description of the API’s sub-folders and files.
Run the command:
in the MATLAB Command Window in the LabOne MATLAB API directory or take a look at the LabOne API documentation for a detailed overview.
MATLAB Driver Naming
On Windows the MEX-file (the
To access `ziDAQ’s documentation within MATLAB, type either of the following in the MATLAB Command Window:
>> help ziDAQ
>> doc ziDAQ
This documentation is located in the file
LabOne API documentation
for a detailed overview.
Prerequisites for running the MATLAB examples:
MATLAB is configured for
ziDAQas described above in Installing the LabOne MATLAB API .
The Data Server program is running and the instrument is discoverable, this is the case if the instrument can be seen in the User Interface.
Signal Output 1 of the instrument is connected to Signal Input 1 via a BNC cable; many of the MATLAB examples measure on this hardware channel.
See Contents of the LabOne MATLAB API for a list of available examples bundled with the LabOne MATLAB API. All the examples follow the same structure and take one input argument: the device ID of the instrument they are to be ran with. For example:
The example should produce some output in the MATLAB Command Window, such as:
ziDAQ version Jul 7 2015 accessing server localhost 8005. Will run the example on `dev123`, an `HF2LI` with options `MFK|PLL|MOD|RTK|PID`. Sweep progress 9% Sweep progress 19% Sweep progress 30% Sweep progress 42% Sweep progress 52% Sweep progress 58% Sweep progress 68% Sweep progress 79% Sweep progress 91% Sweep progress 100% ziDAQ: AtExit called
Most examples will also plot some data in a MATLAB figure, see Figure 1 for an example. If you encounter an error message please ensure that the Running the Examples are fulfilled and see Troubleshooting the LabOne MATLAB API for help troubleshooting the error.
example_sweeper.m; the plots show the instruments demodulator output when performing a frequency sweep over a simple feedback cable.
The examples serve as a starting point for your own measurement needs. However, before editing the m-files, be sure to copy them to your own user space (they could be overwritten upon updating your LabOne installation) and give them a unique name to avoid name conflicts in MATLAB.
>> h = ziDAQ('sweep');
and the Module’s parameters are configured using the
set command and
specifying the Module’s handle with a
value pair, for example:
>> ziDAQ('set', h, 'start', 1.2e5);
The parameters can be read-back using the
get command, which supports
wildcards, for example:
>> sweep_params = ziDAQ('get', h, '*');
sweep_params now contains a
struct of all the Sweeper’s
parameters. The other main Module commands are used similarly, e.g.,
ziDAQ('execute', h) to start the sweeper. See
for more help with Modules and a description
of their parameters.
The Data Acquisition Module uses dot notation for subscribing to signals. In the data structure returned by the MATLAB API, the dots are replaced by underscores in order not to conflict with the dot notation used for member selection in MATLAB, e.g. /devNNN/demods/0/sample.r is accessed using devNNN.demods(1).sample_r.
Logging from the API is not enabled by default upon initializing a
server session with
ziDAQ, it must be enabled (after using
setDebugLevel command. For example,
>> ziDAQ('setDebugLevel', 0);
sets the API’s logging level to 0, which provides the most verbose logging output. The other log levels are defined as follows:
trace:0, debug:1, info:2, status:3, warning:4, error:5, fatal:6.
It is also possible for the user to write their own messages directly to
ziDAQ’s log using the `writeDebugLog command. For example to write a
log message of
info severity level:
>> ziDAQ('writeDebugLog', 1, 'Hello log!');
On Windows the logs are located in the directory
C:\Users\[USER]\AppData\Local\Temp\Zurich Instruments\LabOne Note that
AppData is a hidden directory. The easiest way to find it is to open a
File Explorer window and type the text
%AppData%\.. in the address
bar, and navigate from there. The directory contains folders containing
log files from various LabOne components, in particular, the
folder contains logs from the LabOne MATLAB API. On Linux, the logs can
be found at "/tmp/ziDAQLog_USERNAME", where "USERNAME" is the same as
the output of the "whoami" command.
In this section some tips and tricks for working with the LabOne MATLAB API are provided.
The structure of
All LabOne MATLAB API commands are based on a call to the MATLAB
where the output argument contains the current value of the specified node.
To set an integer node value, both the node path and the value to be set must be specified as the second and third arguments:
See the LabOne API documentation for a detailed overview.
Data Structures returned by
The output arguments that
The instrument’s node tree uses zero-based indexing; MATLAB uses one-based indexing.
See the tip Data Structures returned by
MATLAB’s native data type is double-precision floating point and doesn’t support performing calculations with with other data types such as 64-bit unsigned integers, for example:
Due to this limitation, be sure to convert demodulator timestamps to
Use the utility function
Checking that a sub-structure in the nested data structure returned by
can be replaced by:
This section intends to solve possible error messages than can occur
ziDAQ in MATLAB.
Error message: "Undefined function or method 'ziDAQ' for input arguments of type '*'"
MATLAB can not find the LabOne MATLAB API library. Check whether the
and repeating the steps to configure MATLAB’s search path in Windows, Linux or Mac .
Error message: "Undefined function or method 'example_sweeper'"
MATLAB can not find the example. Check whether the
and repeating the steps to configure MATLAB’s search path in Windows, Linux or Mac .
Error message: "Error using: ziDAQ ZIAPIException with status code: 32870. Connection invalid."
The MATLAB API can not connect to the Data Server. Please check that the correct port was used; that the correct server is running for your device and that the device is connected to the server, see Specifying the Data Server Hostname and Port.
Error Message: "Error using: ziAutoConnect at 63 ziAutoConnect() failed to find a running server or failed to find a connected a device…"
The utility function
Error Message: "Error using: ziDAQ ZIAPIException on path /dev123/sigins/0/imp50 with status code: 16387. Value or Node not found"
The API is connected to the Data Server, but the command failed to find the specified node. Please:
Error Message: "using: ziDAQ Server not connected. Use 'ziDAQ('connect', …) first."
Error Message: "Attempt to execute SCRIPT ziDAQ as a function: ziDAQ.m"
There could be a problem with your LabOne MATLAB API installation. The