addline (Data Acquisition Toolbox)

Data Acquisition Toolbox

Search Help Desk

addline

Examples See Also

Add hardware lines to a digital I/O object.

Syntax

lines = addline(obj, hwl);

lines = addline(obj, hwl, index);

lines = addline(obj, hwl, index, port);

lines = addline(obj, hwl, port);

lines = addline(obj, hwl, index, port, names);

lines = addline(obj, hwl, index, names);

lines = addline(obj, hwl, port, names);

Arguments


`obj`	An existing digital I/O object.
`hwl`	The hardware lines added to the object. Any MATLAB vector syntax can be used.
`index` (optional)	The MATLAB indices to associate with the hardware channels. Any MATLAB vector syntax can be used provided the vector elements are monotonically increasing.
`port` (optional)	The port number. If not specified, then lines are added first from port 1, then from port 2, and so on.
`names` (optional)	A cell array containing the names of the lines.
`lines`	A vector of lines with the same length as `hwch`.

Description

addline adds hardware lines to an existing digital I/O device. The added lines constitute a line group. The values you supply for hwl depend on the hardware accessed. For National Instruments hardware, lines are "zero-based" (begin at zero). For Hewlett-Packard hardware, lines are "one-based" (begin at one). If in doubt, consult your hardware manual.

With every hardware line there is an associated MATLAB index that is used to reference the line. The index assignments follow these rules:

If index is not specified, and no hardware lines are assigned to the object, then the assigned indices start at one and increase monotonically. If hardware lines have already been assigned to the object, then the assigned indices start at the next highest value and increase monotonically.
If index is specified but the indices are previously assigned, then the requested assignment takes precedence and the previous assignment is reindexed to the next available values. If the lengths of hwch and index are not equal, then an error is returned and no lines are added to the device object.

In either case, the resulting indices must begin at one and increase monotonically up to the total size of the line group. If the line group contains gaps or indices without lines assigned, then an error is returned.

Hardware lines can be assigned descriptive names. Choosing a unique descriptive name may be a useful way to identify and reference lines. If the lengths of names and hwl are not the same, then only those lines having a corresponding names entry are named. Line names must begin with a character and contain only characters, numbers, and underscores. If you are naming a large number of lines, then the makenames function may be useful. If a line is not assigned a descriptive name, then it must be referenced by index.

Examples

National Instruments

Suppose you created a digital I/O object called DIO1 for a National Instruments board, and add the first four physical hardware lines (lines 0-3) from port 1.

DIO1 = digitalio('nidaq', 1)
addline(DIO1, 0:3);

These lines are automatically assigned the indices 1-4. You can associate descriptive names with these lines by passing a cell array of names.

addline(DIO1, 0:3, {'line1', 'line2', 'line3', 'line4'});

The cell array of line names can be created manually or with the makenames function.

You can add lines 0-3 from port 2 to the existing line group.

addline(DIO1, 0:3, 2);

The new lines are automatically assigned the indices 5-8. Suppose instead you add lines 0-3 from port 2 to the line group and assign them the indices 1-4.

addline(DIO1, 0:3, 1:4, 2);

The new lines are assigned the indices 1-4, and the previously defined lines are reindexed as indices 5-8. However, if you assigned lines 0-3 from port 2 to indices 6-9, then when the device object was started, an error would be returned since there is a gap in the indices (index 5 has no associated hardware line).