MATLAB Programming
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
powerful environment.
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. |
This section and the provided examples are not intended to be a MATLAB tutorial. See either MathWorks' online Documentation Center or one of the many online resources, for example, the MATLAB Programming Wikibook for help to get started programming with MATLAB. |
Installing the LabOne MATLAB API
Requirements
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'
download page.
Separate MATLAB Package
The separate MATLAB API package should be used if you would like to:
|
Windows, Linux or Mac
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
following:
-
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
.tar.gz
file:[PATH]/LabOne64/API/MATLAB/
-
In the MATLAB Command Window, run the MATLAB script
ziAddPath
located in theMATLAB
directory:>> ziAddPath;
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
ziDAQ
in 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
ziAddPath
):-
Run the
pathtool
and click "Add with Subfolders". Browse to the "MATLAB" directory that was located above in Step 1 and click "OK". -
Edit your
startup.m
to contain the line indicated in the output from Step 2 above. For more help on MATLAB’sstartup.m
file, type the following in MATLAB’s Command Window:>> docsearch('startup.m')
-
-
Verify your MATLAB configuration as described in Verifying Successful MATLAB Configuration .
Verifying Successful MATLAB Configuration
In order to verify that MATLAB is correctly configured to use ziDAQ
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_poll
with your device ID as the input argument:>> example_poll('dev123'); % Replace with your device ID.
If this fails, please try issuing the
connect
command, 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)`
Note, using
'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 ofmf-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 .
Getting Started with the LabOne MATLAB API
This section introduces the user to the LabOne MATLAB API.
Contents of 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:
>> doc('Contents')
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 |
Using the Built-in Documentation
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 MATLAB/Driver/ziDAQ.m
.
See the
LabOne API documentation
for a detailed overview.
Running the Examples
Prerequisites for running the MATLAB examples:
-
MATLAB is configured for
ziDAQ
as 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:
>> example_sweeper('dev123');
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. |
Using ziCore Modules in the LabOne MATLAB API
In the LabOne MATLAB API ziCore
Modules are
configured and controlled via MATLAB "handles". For example, in order to
use the Sweeper Module a handle is created via:
>> h = ziDAQ('sweep');
and the Module’s parameters are configured using the set
command and
specifying the Module’s handle with a path
, 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, '*');
The variable 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
ziCore Modules
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. |
Enabling Logging in the LabOne MATLAB API
Logging from the API is not enabled by default upon initializing a
server session with ziDAQ
, it must be enabled (after using connect
)
with the 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 ziDAQLog
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.
LabOne MATLAB API Tips and Tricks
In this section some tips and tricks for working with the LabOne MATLAB API are provided.
The structure of
ziDAQ commands.All LabOne MATLAB API commands are based on a call to the MATLAB
function
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
ziDAQ .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 |
Explicitly convert
uint64 data types to double .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
ziCheckPathInData .Checking that a sub-structure in the nested data structure returned by
can be replaced by:
|
Troubleshooting the LabOne MATLAB API
This section intends to solve possible error messages than can occur
when using 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."
A
where |
Error Message: "Attempt to execute SCRIPT ziDAQ as a function: ziDAQ.m"
There could be a problem with your LabOne MATLAB API installation. The
call to |