icdevice

R2026b

Create device object

Description

Use icdevice to create a MATLAB^® device object.

Creation

Syntax

devObj = icdevice(driverName,hwObj)

devObj = icdevice(driverName,rsrcName)

devObj = icdevice(driverName)

devObj = icdevice(___,Name=Value)

Description

devObj = icdevice(driverName,hwObj) creates the device object devObj using the MATLAB interface instrument driver specified by driverName. The function communicates with the instrument through the interface object, hwObj.

devObj = icdevice(driverName,rsrcName) creates a device object devObj, using the MATLAB VXIplug&play instrument driver or MATLAB IVI^® instrument driver specified by driverName. The function communicates with the instrument through the resource specified by rsrcName. If a MATLAB instrument driver wrapper for the underlying VXIplug&play or IVI driver does not already exist, use ividev instead.

devObj = icdevice(driverName) constructs a device object devObj, using the MATLAB IVI instrument driver specified by driverName. The underlying IVI driver requires a logical name.

devObj = icdevice(___,Name=Value) specifies one or more property values using name-value arguments.

Note

When deploying code using IVI-C or VXIplug&play drivers, executing your code will generate additional files in the folder specified by executing the following code at the MATLAB prompt:

fullfile(tempdir,'ICTDeploymentFiles',sprintf('R%s',version('-release')))

On all supported platforms, a file with the name MATLABPrototypeFor<driverName>.m is generated, where <driverName> the name of the IVI-C or VXIplug&play driver. With 64-bit MATLAB on Windows^®, a second file by the name <driverName>_thunk_pcwin64.dll is generated. When creating your deployed application or shared library, manually include these generated files. If using the icdevice function, remember to also manually include the MDD-file in the deployed application or shared library. For more information on including additional files refer to the MATLAB Compiler™ documentation.

Input Arguments

driverName — Instrument driver name

string | character vector

Instrument driver name, specified as a string scalar or character vector. The driver can be a MATLAB interface instrument driver (.mdd file), a MATLAB VXIplug&play instrument driver, or a MATLAB IVI instrument driver. If driverName does not exist or cannot be found, the function does not create the device object. The function searches for drivers in the instrument drivers folder and on the MATLAB path.

If a MATLAB instrument driver wrapper (.mdd file) for your VXIplug&play or IVI-C driver does not already exist, you can obtain one from the instrument vendor or from MATLAB Central File Exchange. If a driver wrapper is not available from either source, contact MathWorks Technical Support.

hwObj — Interface object for instrument communication

visadev object | serialport object | tcpclient object | udpport object

Interface object for instrument communication, specified as a visadev, serialport, tcpclient, or udpport object. If hwobj is invalid, the function does not create the device object.

rsrcName — VISA resource name

string | character vector

VISA resource name, specified as a string scalar or character vector. Use this syntax with VXIplug&play and IVI drivers. The resource name identifies the instrument on the bus. For example, "GPIB0::2::INSTR" or "USB0::0x1234::0x5678::SN001::INSTR".

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: d = icdevice("tektronix_tds210",visaObj,Timeout=30,Tag="Scope1")

OptionString — Driver option string

"" (default) | driver configuration string

Driver option string, specified as a string scalar or character vector. Use this to set driver-specific configuration options such as simulation mode or range checking. For IVI-C and VXIplug&play drivers, the option string can include settings such as "Simulate=true" or "QueryInstrStatus=true".

Data Types: string | char

Timeout — Communication timeout

10 (default) | positive numeric scalar (seconds)

Communication timeout in seconds, specified as a positive numeric scalar. The timeout value determines how long the device object waits for a response from the instrument before generating an error.

Data Types: double

Tag — Object identifier tag

"" (default) | text label

Object identifier tag, specified as a string scalar or character vector. Use Tag to identify or group device objects. You can search for device objects by tag using icdevicefind.

Data Types: string | char

UserData — User-defined data

[ ] (default)

User-defined data, specified as any MATLAB data type. Use this property to store additional data with the device object.

Output Arguments

devObj — Device object

icdevice object

Device object, returned as an icdevice object. The function creates the object in a disconnected state. Use connect to establish communication with the instrument, and disconnect to end the session.

Properties

DriverName — Instrument driver name

Read-only: character vector

This property is read-only.

Name of the MATLAB instrument driver associated with this device object, represented as a character vector.

Data Types: char

DriverType — Type of instrument driver

Read-only: 'MATLAB interface' | 'VXIplug&play' | 'IVI-C'

This property is read-only.

Type of instrument driver, represented as 'MATLAB interface', 'VXIplug&play', or 'IVI-C'.

Data Types: char

InstrumentModel — Instrument model name

Read-only: character vector

This property is read-only.

Model name of the instrument as defined by the instrument driver, represented as a character vector.

Data Types: char

Manufacturer — Instrument manufacturer

Read-only: character vector

This property is read-only.

Manufacturer of the instrument as defined by the instrument driver, represented as a character vector.

Data Types: char

Status — Connection status

Read-only: 'closed' (default) | 'open'

This property is read-only.

Connection status, represented as 'closed' or 'open'. Use connect to open the connection and disconnect to close it.

Data Types: char

The device object might also have additional driver-specific properties defined by the instrument driver. Use get to see all properties and set to see configurable properties.

Object Functions

connect	Connect device object to instrument
disconnect	Disconnect device object from instrument
invoke	Execute driver-specific function on device object
icdevicefind	Find device connections
devicereset	Reset instrument
selftest	Run instrument self-test
geterror	Check and return error message from instrument
get	Instrument object properties
set	Configure or display instrument object properties
delete	Remove instrument objects from memory

Examples

Create Device Object Using visadev Interface

Create a device object for a Tektronix^® TDS 210 oscilloscope that is connected to a GPIB board, using a visadev interface object and MATLAB interface instrument driver.

v = visadev("GPIB0::2::INSTR");
d = icdevice("tektronix_tds210",v)

d =

  Driver with properties:

        DriverName: 'tektronix_tds210'
        DriverType: 'MATLAB interface'
   InstrumentModel: 'TDS 210'
      Manufacturer: 'Tektronix'
            Status: 'closed'

  Show all functions, Driver-specific properties, Class properties

Connect to the instrument.

connect(d);

List the oscilloscope settings that can be configured.

props = set(d);

Get the current configuration of the oscilloscope.

values = get(d);

Disconnect from the instrument and clean up.

disconnect(d);
delete([d v]);

Create Device Object Using VXIplug&play Driver

Create a device object for a Tektronix TDS 5000 series oscilloscope using a MATLAB VXIplug&play instrument driver.

This example assumes that the MATLAB instrument driver wrapper 'Tktds5kMATLABDriver' is already installed on your system.

Construct a device object that uses the VXIplug&play driver. The instrument is assumed to be located at GPIB primary address 2.

d = icdevice("Tktds5kMATLABDriver","GPIB0::2::INSTR")

d =

  Driver with properties:

        DriverName: 'Tktds5kMATLABDriver'
        DriverType: 'MATLAB VXIplug&play'
   InstrumentModel: 'TDS 5000'
      Manufacturer: 'Tektronix'
            Status: 'closed'

  Show all functions, Driver-specific properties, Class properties

Connect to the instrument.

connect(d);

List the oscilloscope settings that can be configured.

props = set(d);

Get the current configuration of the oscilloscope.

values = get(d);

Disconnect from the instrument and clean up.

disconnect(d);
delete(d);

Create Device Object Using IVI Logical Name

This example assumes that the MATLAB instrument driver wrapper 'IviDmmMATLABDriver' is already installed on your system.

Create a device object using an IVI instrument driver referenced by a logical name configured in the IVI Configuration Store.

d = icdevice("IviDmmMATLABDriver")

d =

  Driver with properties:

        DriverName: 'IviDmmMATLABDriver'
        DriverType: 'MATLAB IVI-C'
   InstrumentModel: ''
      Manufacturer: ''
            Status: 'closed'

  Show all functions, Driver-specific properties, Class properties

Connect to the instrument.

connect(d);

Disconnect from the instrument and clean up.

disconnect(d);
delete(d);

Create Device Object with Name-Value Arguments

Create a visadev interface object.

v = visadev("GPIB0::2::INSTR");

Create the device object with a custom 30-second timeout and a descriptive tag using name-value arguments.

d = icdevice("tektronix_tds210",v,Timeout=30,Tag="Scope1")

d =

  Driver with properties:

        DriverName: 'tektronix_tds210'
        DriverType: 'MATLAB interface'
   InstrumentModel: 'TDS 210'
      Manufacturer: 'Tektronix'
            Status: 'closed'

  Show all functions, Driver-specific properties, Class properties

Connect to the instrument.

connect(d);

Disconnect and clean up.

disconnect(d);
delete(d);

Version History

Introduced before R2006a

R2026b: Legacy mode removed

The legacy mode of icdevice has been removed. The only supported value for the LegacyMode name-value argument is now false. This is a change to its default behavior. Attempting to set LegacyMode=true generates a warning and reverts to false.

You can no longer use legacy interface objects (gpib, visa, serial, tcpip, udp) as the hwobj argument. Use the recommended interface objects instead.

Not Recommended	Recommended	Example
gpib	visadev	v = visadev("GPIB0::2::INSTR"); obj = icdevice("driver",v);
visa	visadev	v = visadev("USB0::0x1234::0x5678::SN001::INSTR"); obj = icdevice("driver",v);
serial	serialport	s = serialport("COM3",9600); obj = icdevice("driver",s);
tcpip	tcpclient	t = tcpclient("192.168.1.1",5025); obj = icdevice("driver",t);
udp	udpport	u = udpport("byte"); obj = icdevice("driver",u);

R2024b: Legacy mode will be removed

The legacy mode of icdevice will be removed in a future release. The following icdevice functions and properties will be removed:

• inspect function

• instrfind function (use icdevicefind instead)

• instrfindall function (use icdevicefind instead)

• instrnotify function

• obj2mfile function

• ConfirmationFcn property

• Name property

• ObjectVisibility property

You can specify if icdevice creates a legacy mode object by using the LegacyMode name-value argument.

• LegacyMode=true (default) creates an icdevice object using the legacy mode, consistent with past releases. In this mode, the listed properties and functions continue to operate.

• LegacyMode=false creates an icdevice object in the new mode. Use of the listed properties and functions might generate warnings or errors. You cannot combine this mode with name-value arguments for any of the properties being removed.

You can no longer specify multiple name-value arguments with a single pair of corresponding cell arrays.