Data Acquisition Toolbox™

Adding Lines to a Digital I/O Object

Using the Addline Function

After creating the digital I/O (DIO) object, you must add lines to it. As shown by the figure in Hardware Channels or Lines, you can think of a device object as a container for lines. The collection of lines contained by the DIO object is referred to as a line group. A line group consists of a mapping between hardware line IDs and MATLAB^® indices (see below).

When adding lines to a DIO object, you must follow these rules:

• The lines must reside on the same hardware device. You cannot add lines from different devices, or from different subsystems on the same device.

• You can add a line only once to a given digital I/O object. However, a line can be added to as many different digital I/O objects as you desire.

• You can add lines that reside on different ports to a given digital I/O object.

You add lines to a digital I/O object with the addline function. addline requires the device object, at least one hardware line ID, and the direction (input or output) of each added line as input arguments. You can optionally specify port IDs, descriptive line names, and an output argument. For example, to add eight output lines from port 0 to the device object dio created in the preceding section:

hwlines = addline(dio,0:7,'out');

The output argument hwlines is a column vector that reflects the line group contained by dio. You can display the class of hwlines with the whos command.

whos hwlines
  Name          Size         Bytes  Class

  hwlines       8x1            536  dioline object

Grand total is 13 elements using 536 bytes

You can use hwlines to easily access lines. For example, you can configure or return property values for one or more lines. As described in Referencing Individual Hardware Lines, you can also access lines with the Line property.

Once you add lines to a DIO object, the properties listed below are automatically assigned values. These properties provide descriptive information about the lines based on their class type and ID.

Table 7-2. Descriptive Digital I/O Line Properties

You can display the values of these properties for hwlines with the get function.

get(hwlines,{'HwLine','Index','Parent','Type'})
ans = 
    [0]    [1]    [1x1 digitalio]    'Line'
    [1]    [2]    [1x1 digitalio]    'Line'
    [2]    [3]    [1x1 digitalio]    'Line'
    [3]    [4]    [1x1 digitalio]    'Line'
    [4]    [5]    [1x1 digitalio]    'Line'
    [5]    [6]    [1x1 digitalio]    'Line'
    [6]    [7]    [1x1 digitalio]    'Line'
    [7]    [8]    [1x1 digitalio]    'Line'

Back to Top

Line and Port Characteristics

As described in the preceding section, when you add lines to a DIO object, they must be configured for either input or output. You read values from an input line and write values to an output line. Whether a given hardware line is addressable for input or output depends on the port it resides on. You can classify digital I/O ports into these two groups based on your ability to address lines individually:

• Port-configurable devices — You cannot address the lines associated with a port-configurable device individually. Therefore, you must configure all the lines for either input or output. If you attempt to mix the two configurations, an error is returned.

  You can add any number of available port-configurable lines to a DIO object. However, the engine will address all lines behind the scenes. For example, if one line is added to a DIO object, then you automatically get all lines. Therefore, if a DIO object contains lines from a port-configurable device, and you write a value to one or more of those lines, then all the lines are written to even if they are not contained by the device object.

• Line-configurable devices — You can address the lines associated with a line-configurable device individually. Therefore, you can configure individual lines for either input or output. Additionally, you can read and write values on a line-by-line basis. Note that for National Instruments^® E-Series hardware, port 0 is always line-configurable, while all other ports are port-configurable. Port 0 is line-configurable only for E-Series devices of the traditional National Instruments drivers. Note that NI-DAQmx devices do not support this.

You can return the line and port characteristics with the daqhwinfo function. For example, National Instruments AT-MIO-16DE-10 board has four ports with eight lines per port. To return the digital I/O characteristics for this board:

hwinfo = daqhwinfo(dio);

Display the line characteristics for each port.

hwinfo.Port(1)
ans = 
           ID: 0
      LineIDs: [0 1 2 3 4 5 6 7]
    Direction: 'in/out'
       Config: 'line'
hwinfo.Port(2)
ans = 
           ID: 2
      LineIDs: [0 1 2 3 4 5 6 7]
    Direction: 'in/out'
       Config: 'port'
hwinfo.Port(3)
ans = 
           ID: 3
      LineIDs: [0 1 2 3 4 5 6 7]
    Direction: 'in/out'
       Config: 'port'
hwinfo.Port(4)
ans = 
           ID: 4
      LineIDs: [0 1 2 3 4 5 6 7]
    Direction: 'in/out'
       Config: 'port'

This information tells you that you can configure all 32 lines for either input or output, and that the first port is line-configurable while the remaining ports are port-configurable.

Parallel Port Characteristics

The parallel port consists of eight data lines, four control lines, five status lines, and eight ground lines. In normal usage, the lines are controlled by the host computer software and the peripheral device following a protocol such as IEEE^® Standard 1284-1994. The protocol defines procedures for transferring data such as handshaking, returning status information, and so on. However, the toolbox uses the parallel port as a basic digital I/O device, and no protocol is needed. Therefore, you can use the port to input and output digital values just as you would with a typical DIO subsystem.

To access the physical parallel port lines, most PCs come equipped with one 25-pin female connector, which is shown below.

The lines use TTL logic levels. A line is high (true or asserted) when it is a TTL high level, while a line is low (false or unasserted) when it is a TTL low level. The exceptions are lines 1, 11, 14, and 17, which are hardware inverted.

The toolbox groups the 17 nonground lines into three separate ports. The port IDs and the associated pin numbers are given below

Table 7-3. Parallel Port IDs and Pin Numbers

Note that in some cases, port 0 lines might be unidirectional and only output data. If supported by the hardware, you can configure these lines for both input and output with your PC's BIOS by selecting a bidirectional mode such as EPP (Enhanced Parallel Port) or ECP (Extended Capabilities Port).

The parallel port characteristics for the DIO object parport are shown below.

hwinfo = daqhwinfo(parport);
hwinfo.Port(1)
ans = 

           ID: 0
      LineIDs: [0 1 2 3 4 5 6 7]
    Direction: 'in/out'
       Config: 'port'
hwinfo.Port(2)
ans = 

           ID: 1
      LineIDs: [0 1 2 3 4]
    Direction: 'in'
       Config: 'port'
hwinfo.Port(3)
ans = 

           ID: 2
      LineIDs: [0 1 2 3]
    Direction: 'in/out'
       Config: 'port'

This information tells you that all 17 lines are port-configurable, you can input and output values using the 12 lines associated with ports 0 and 2, and that you can only input values from the five lines associated with port 1.

For easy reference, the LineName property is automatically populated with a name that includes the port pin number. For example:

dio = digitalio('parallel', 1)

Display Summary of DigitalIO (DIO) Obj Using 'PC Parallel Port Hardware'.

 Port Parameters:  Port 0 is port configurable for reading and writing.
                   Port 1 is port configurable for reading.
                   Port 2 is port configurable for reading and writing.
   Engine status:  Engine not required.

DIO object contains no lines.

addline(dio, 0:16, 'in')

   Index:  LineName:  HwLine:  Port:  Direction:  
   1       'Pin2'     0        0      'In'        
   2       'Pin3'     1        0      'In'        
   3       'Pin4'     2        0      'In'        
   4       'Pin5'     3        0      'In'        
   5       'Pin6'     4        0      'In'        
   6       'Pin7'     5        0      'In'        
   7       'Pin8'     6        0      'In'        
   8       'Pin9'     7        0      'In'        
   9       'Pin15'    0        1      'In'        
   10      'Pin13'    1        1      'In'        
   11      'Pin12'    2        1      'In'        
   12      'Pin10'    3        1      'In'        
   13      'Pin11'    4        1      'In'        
   14      'Pin1'     0        2      'In'        
   15      'Pin14'    1        2      'In'        
   16      'Pin16'    2        2      'In'        
   17      'Pin17'    3        2      'In'        

Back to Top

Referencing Individual Hardware Lines

As described in the preceding section, you can access lines with the Line property or with a line object. To reference individual lines, you must specify either MATLAB indices or descriptive line names.

MATLAB^® Indices

Every hardware line contained by a DIO object has an associated MATLAB index that is used to reference the line. When adding lines with the addline function, index assignments are made automatically. The line indices start at 1 and increase monotonically up to the number of line group members. The first line indexed in the line group represents the least significant bit (LSB). Unlike adding channels with the addchannel function, you cannot manually assign line indices with addline.

For example, the digital I/O object dio created in the preceding section has the MATLAB indices 1 through 8 automatically assigned to the hardware lines 0 through 7, respectively. To swap the first two hardware lines so that line ID 1 is the LSB, you can supply the appropriate index to hwlines and use the HwLine property.

hwlines(1).HwLine = 1;
hwlines(2).HwLine = 0;

Alternatively, you can use the Line property.

dio.Line(1).HwLine = 1;
dio.Line(2).HwLine = 0;

Descriptive Line Names

Choosing a unique, descriptive name can be a useful way to identify and reference lines — particularly for large line groups. You can associate descriptive names with hardware lines with the addline function. For example, suppose you want to add 8 lines to dio, and you want to associate the name TrigLine with the first line added.

addline(dio,0,'out','TrigLine');
addline(dio,1:7,'out');

Alternatively, you can use the LineName property.

addline(dio,0:7,'out');
dio.Line(1).LineName = 'TrigLine';

You can now use the line name to reference the line.

dio.TrigLine.Direction = 'in';

Example: Adding Lines for National Instruments^® Hardware

This example illustrates various ways you can add lines to a DIO object associated with a National Instruments AT-MIO-16DE-10 board. This board is a multiport device whose characteristics are described in Line and Port Characteristics.

To add eight input lines to dio from port 0:

addline(dio,0:7,'in');

To add four input lines and four output lines to dio from port 0:

addline(dio,0:7,{'in','in','in','in','out','out','out','out'});

Suppose you want to add the first two lines from port 0 configured for input, and the first two lines from port 2 configured for output. There are four ways to do this. The first way requires only one call to addline because it uses the hardware line IDs, and not the port IDs.

addline(dio,[0 1 8 9],{'in','in','out','out'});

The second way requires two calls to addline, and specifies one line ID and multiple port IDs for each call.

addline(dio,0,[0 2],{'in','out'});
addline(dio,1,[0 2],{'in','out'});

The third way requires two calls to addline, and specifies multiple line IDs and one port ID for each call.

addline(dio,0:1,0,'in');
addline(dio,0:1,2,'out');

Lastly, you can use four addline calls — one for each line added.

Back to Top

Digital I/O Objects

Writing and Reading Digital I/O Line Values