Mathworks MATLAB partnerUsing Mathworks MATLAB® with Pickering LXI Drivers

An introduction into how to use the MATLAB® programming platform to control Pickering Interfaces' PXI and LXI devices

The PXI and LXI devices provided by Pickering Interfaces are controlled by the drivers provided as part of the Clientbridge software suite. The user can control the instruments from the MATLAB environment by loading the driver (dlls) and executing the corresponding functions for the intended functionalities. The below mentioned sections explains some of the functionalities, to help the user to understand how the MATLAB programming can be done using the functions provided by the driver dlls.

Note - 

  • To know about the other functions available as part of the drivers, please refer to Picmlx.h and Piplx.h available in the folder as part of the Clientbridge installation. C:\Program Files\Pickering Interfaces Ltd\ClientBridge\Include
  • Example MATLAB scripts to demonstrate controlling of different card functionalities are available here.
  • For further assistance or queries, please contact us at [email protected].

Contents

  1. Loading libraries
  2. Connect to a device 
  3. Open Specified Card 
  4. Retrieving Card ID 
  5. Operating Switches 
  6. Reading and Writing a Sub-unit 
  7. Writing to Crosspoint 
  8. Operating programmable resistors 
  9. Operating programmable voltage sources 
  10. Operating Battery Simulator 
  11. Close Specified Card 
  12. Disconnect from device 
  13. Unload Libraries 
  14. User Friendly Approach 

Loading Libraries

Loading a library dll to MATLAB can be done using the loadlibrary(). To access libraries, use the the term "loadlibrary”, here is an example to access the LXI drivers PIPLX and PICMLX:

loadlibrary('Picmlx_w64’, 'C:\Program Files\Pickering Interfaces Ltd\ClientBridge\Include\Picmlx.h');
loadlibrary('Piplx_w64', 'C:\Program Files\Pickering Interfaces Ltd\ClientBridge\Include\Piplx.h');
%Enter appropriate pathname for dll.

The libraries can be loaded using m-file. Using the m-file will help speed up the loadlibrary() execution. 

Creating m-file 

loadlibrary('<Dll name>),'<'location of the header file>'''mfilename''<'mfile name>';
examples - 
loadlibrary('Piplx_w64', 'C:\Program Files\Pickering Interfaces Ltd\ClientBridge\Include\Piplx.h'),'mfilename','Picmlx_w64';

loadlibrary('Picmlx_w64,''C:\Program Files\Pickering Interfaces Ltd\ClientBridge\Include\Piplx.h','includepath','C:\Program Files\Pickering Interfaces Ltd\ClientBridge\Include','mfilename','Picmlx_w64';

Note - use the correct paths to the hearer files

Loading the library using the m-file

loadlibrary('Picmlx_w64',@Picmlx_w64);
loadlibrary('Piplx_w64',@Piplx_w64);

Once the libraries are loaded, to check the functions in the library we can use ‘libfunctionsview’ command followed by the dll's name. Let’s take an example of PICMLX.

libfuntionsview('Picmlx_w64')

after the command is executed, a window will appear displaying information on functions in external library

Connect to a device

The connection to a LXI or PXI device, is done using the PICMLX_Connect function.

Calllib() matlab command calls the functions in the external dll.

%Opening a session.
board = 0;
port = 1024;
timeout = 2000;
session=libpointer('int32Ptr',0);
address = 'PXI'; %for PXI connection
%address = '192.168.3.127'; %for LXI connection
ap = libpointer('int8Ptr',[int8(address) 0]);
calllib('Picmlx_w64','PICMLX_Connect',board,ap,port,timeout,session);%If  ans = 0 (No error returned) the device is successfully connected
SessionId=session.Value;
% Return the value session ID

Open Specified Card

Once the connection is established, using the PIPLX_OpenSpecifiedCard function enables user to open a specific PXI card on the chassis. The function will use the "calllib" command to access function in the PIPLX dll. The example below illustrates


%Create a uint32Ptr to get a return value on logical card number
cardnum=libpointer('uint32Ptr', 0);
 
% Enter the input parameters for PIPLX_connect
% Enter the SessionId obtained when connected to PXI card
% Set the BUS and SLOT to the address of the card.
calllib ('Piplx_w64', 'PIPLX_OpenSpecifiedCard', SessionId, BUS, SLOT, cardnum);
 
% If the ans = 0 (No error returned) the card is successfully opened
CardNum=cardnum.Value;
% Return the value of card number

Retrieving Card ID

After successfully opening a card, the ID of the card can be retrieved using the PIPLX_CardId function.


% an int8Ptr is defined to accept the Card ID string being returned from the PIPLX_CardId function.
      bufsize = 30;
      bufptr = libpointer('int8Ptr',zeros(1,bufsize,'int8'));
% The PIPLX_CardId function has been invoked.
% Session ID of the current connection and the number of the card for which the Card Id is retrieved is given as inputs.
calllib('Piplx_w64','PIPLX_CardId’,SessionID,CardNum,bufptr,bufsize);
% Converting the characters to string.
      Card_Id = convertCharsToStrings(char(bufptr.value));
      fprintf ('\nCard ID is %s  \n\n',Card_Id);

Operating Switches

After successfully establishing the connection and opening the card, user can now able to operate switches. PIPLX_OpBit allows user to operate switch one at a time. Here is an example:

% Enter the input parameters for PIPLX_OpBit
% Use Session ID and card number obtained in previous steps
% OutSub - Output Sub Unit number
% BitNum - Output Bit number
% state - "1" ON  , "0" OFF
calllib('Piplx_w64', 'PIPLX_OpBit', SessionId, CardNum, OutSub, BitNum, State);

Reading and Writing a Sub-unit

The user can read/set the status of multiple bits of a sub-unit by using the functions 

  • PIPLX_ViewSub – Read the status of bits of the sub-unit. 
  • PIPLX_WriteSub – Set the bits of the sub-unit.

% uint32Ptr are defined to hold the type number, rows and columns of the sub-unit to be used.
%SubUnit -  is the sub-unit number the user want to control.  
TypNumptr = libpointer('uint32Ptr',0);
Rowsptr = libpointer('uint32Ptr',0);
Colsptr = libpointer('uint32Ptr',0);
calllib('Piplx_w64','PIPLX_SubInfo',SessionID,CardNum,SubUnit,1,TypNumptr,Rowsptr,Colsptr);

% Retrieving the number of rows and Columns of the sub-unit from the corresponding defined pointers.
Rows = Rowsptr.Value;
Cols = Colsptr.Value;
fprintf ('The subunit has %d Rows and %d Columns. \n\n',Rows,Cols);
      
% Calculating the number of DWORDs needed for           
bitsize = double(32);
DwordSize = floor((Rows * Cols)/bitsize);
if ((DwordSize*32) < (Rows*Cols))
            DwordSize = DwordSize + 1;
end
                
%Reading the sub-unit.
SubUnitptr = libpointer('uint32Ptr',zeros(DwordSize,'uint32'));
calllib('Piplx_w64','PIPLX_ViewSub',SessionID,CardNum,SubUnit,SubUnitptr,Rows);
	
% Enter the bit of the sub-unit to be controlled
prompt = 'Enter the Bit to be energized -> ';
Userinp = input(prompt);    
	
% Logic to set the corrent bit the DWORDS for the sub-unit.
if (Userinp <= (Rows * Cols))
      	UserinpD = double(Userinp);
        wordset = (floor(UserinpD/bitsize)) + 1;
        wordpos = (UserinpD -((wordset - 1)*bitsize));
                       
        if (wordset && (wordpos == 0))
              wordset = wordset - 1;
              wordpos = (UserinpD -((wordset - 1)*bitsize));
        end
                        
        subunitvalue = SubUnitptr.Value;
        intout = bitset(subunitvalue(wordset),wordpos,1);
        subunitvalue(wordset) = intout;
        SubUnitptr.Value = subunitvalue;
end

%Writing to the Sub-unit.
calllib('Piplx_w64','PIPLX_WriteSub',SessionID,CardNum,SubUnit,SubUnitptr,DwordSize);         

Writing to Crosspoint

A crosspoint (matrix card bit) can be controlled using the functions 

  • PIPLX_ViewCrosspoint – get the status of the crosspoint. 
  • PIPLX_OpCrosspoint – energize or de-energize the crosspoint.

% uint32Ptr are defined to hold the type number, rows and columns of the sub-unit to be used.
%SubUnit -  is the sub-unit number the user want to control.
TypNumptr = libpointer('uint32Ptr',0);
Rowsptr = libpointer('uint32Ptr',0);
Colsptr = libpointer('uint32Ptr',0);
calllib('Piplx_w64','PIPLX_SubInfo',SessionID,CardNum,SubUnit,1,TypNumptr,Rowsptr,Colsptr);

% Retrieving the number of rows and Columns of the sub-unit from the corresponding defined pointers.
Rows = Rowsptr.Value;
Cols = Colsptr.Value;

fprintf ('The subunit has %d Rows and %d Columns. \n\n',Rows,Cols);
                
fprintf('Enter the crosspoint locations to be energized\n');
fprintf('Column(X) Max -> %d  ,',Cols);
prompt = 'Enter column(X) location:';
ColInp = input(prompt);
                
if (Rows > 1)
      fprintf('Row(Y) Max -> %d  ,',Rows);
      prompt = 'Enter row(Y) location:';
      RowInp = input(prompt);
end

valptr=libpointer('int32Ptr',0);          calllib('Piplx_w64','PIPLX_ViewCrosspoint',SessionID,CardNum,SubUnit,RowInp,ColInp,valptr);
fprintf(‘Current status of the crosspoint locations is -> %d \n', valptr.Value);

%Energizing the crosspoint.
%State = 0;      %1 - ON, 0 - OFF
State = 1;
calllib('Piplx_w64','PIPLX_OpCrosspoint',SessionID,CardNum,SubUnit,RowInp,ColInp,State);

%De-energizing the crosspoint.
%State = 0;      %1 - ON, 0 - OFF                          calllib('Piplx_w64','PIPLX_OpCrosspoint',SessionID,CardNum,SubUnit,RowInp,ColInp,State);

Operating Programmable Resistors

The programmable resistor sub-unit values can be read and set using the following functions 

  • PIPLX_ResGetResistance – get the current value of resistance of the card. 
  • PIPLX_ResSetResistance – set the resistance for the card.

%Defining a double pointer to accept the resistance value from the PIPLX_ResGetResistance
Resptr = libpointer('doublePtr',0);

%Reading the Resistance.   
calllib('Piplx_w64','PIPLX_ResGetResistance',SessionID,CardNum,SubUnit,Resptr);
fprintf(‘Current value of resistor card is -> %d \n', Resptr.Value);
%Setting the Resistance.
prompt = 'Enter the Resistance value to be set for the card -> ';
Resistance = input(prompt);    % Enter the Resistance value here
Mode = 0;
calllib('Piplx_w64','PIPLX_ResSetResistance',SessionID,CardNum,SubUnit,Mode,Resistance);

Operating Programmable Voltage Sources

The programmable voltage source sub-unit values can be read and set using the following functions 

  • PIPLX_VsourceGetVoltage – get the current value of voltage set for the card. 
  • PIPLX_VsourceSetVoltage – set the voltage for the card.

%Reading the current voltage of the card.
Voltptr = libpointer('doublePtr',0);
calllib('Piplx_w64','PIPLX_VsourceGetVoltage',SessionID,CardNum,SubUnit,Voltptr);
fprintf(‘Current value of voltage card is -> %d \n', Voltptr.Value);

%Setting the voltage of the card.
prompt = 'Enter the Voltage value to be set for the card -> ';
Voltage = input(prompt);    % Enter the Voltage value here
calllib('Piplx_w64','PIPLX_VsourceSetVoltage',SessionID,CardNum,SubUnit,Voltage);

Operating Battery Simulator

The battery simulator sub-unit values can be read and set using the following functions

  • PIPLX_BattGetCurrent – get the current for battery simulator card. 
  • PIPLX_BattSetCurrent – set the current for battery simulator card. 
  • PIPLX_BattGetVoltage - get the voltage for battery simulator card. 
  • PIPLX_BattSetVoltage - set the voltage for battery simulator card.

%Reading the voltage of the battery simulator card.
Voltptr = libpointer('doublePtr',0);
calllib('Piplx_w64','PIPLX_BattGetVoltage',SID,CardNum,SubUnit,Voltptr);
fprintf(‘Current value of voltage card is -> %d \n', Voltptr.Value);

%Setting the voltage of the battery simulator card.
prompt = 'Enter the Voltage value to be set for the card -> ';
Voltage = input(prompt);    % Enter the Voltage value here
calllib('Piplx_w64','PIPLX_BattSetVoltage',SID,CardNum,SubUnit,Voltage);

%Reading the current of the battery simulator card.
Currptr = libpointer('doublePtr',0);
calllib('Piplx_w64','PIPLX_BattGetCurrent',SID,CardNum,SubUnit,Currptr);
fprintf('Present Current is %d \n',Currptr.Value);

%Setting the current of the battery simulator card.
prompt = 'Enter Current to be set';
            Current = input(prompt);
calllib('Piplx_w64','PIPLX_BattSetCurrent',SID,CardNum,SubUnit,Current);

Close Specified Card

To close a specific card, use PIPLX_CloseSpecifiedCard function in PIPLX library.

% Enter the current session ID and card number in the input parameters
calllib ('Piplx_w64', 'PIPLX_CloseSpecifiedCard', SessionId, CardNum)

Disconnect from device

To disconnect from a device, use PICMLX_Disconnect function in PICMLX library.

% Enter the current session ID in the input parameter
calllib ('Picmlx_w64','PICMLX_Disconnect',SessionId);

Unload Libraries

To unload the libraries loaded to MATLAB, use the following command

unloadlibrary('Picmlx_w64');
unloadlibrary('Piplx_w64');

User Friendly Approach

To perform the list of functions explained above, a set of function files (*.m files) have been developed in MATLAB which can be downloaded from here.

These MATLAB function files will use the PIPX and PICMLX library functions in an efficient way to produce a user-friendly interface. Here are the examples of the MATLAB functions.

Load_Libraries

The below function load the libraries and will handle warnings and performs error handling.

function Load_Libraries()
 
warning off all;
 
    try
      	%Enter appropriate pathname for dll.
	loadlibrary('picmlx_w32','c:\LXI\picmlx.h');
	loadlibrary('piplx_w32','c:\LXI\piplx.h');
  
    catch
        err2= MException(,'Library:FailtoLoad', ...
        'DLL Failed to Load');
        throw(err2)
    end
end

PI_Connect

This function establishes the connection to the LXI device. In case of an error a message will appear to check parameters instead of an error number and Session Id will be produced as an output.

function [SessionId]=PI_Connect(board,address,port,timeout,session)
 
   try
       session=libpointer('int32Ptr',0);
       calllib('picmlx_w32','PICMLX_Connect',board,address,port,timeout,session);
       SessionId=session.Value;
   catch
       err1= MException('Calllib:FailtoExecute', ...
	'Calling Libraries function Failed to Execute, Check Parameters');

       throw(err1)
    end
end

PI_OpenSpecifiedCard

Takes user input of session ID, BUS, Slot to produce a card number as a return value.

function [CardNum]=PI_OpenSpecifiedCard(SessionId,BUS,SLOT,cardnum)
 
   try
      cardnum=libpointer('uint32Ptr',0);
      err = calllib
('piplx_w32','PIPLX_OpenSpecifiedCard',SessionId,BUS,SLOT,cardnum);

      CardNum=cardnum.Value;
 
       if (err ~= 0)
         err=err1;
        end
 
   catch
      err1= MException('Calllib:FailtoOpenSpecifiedCard', ...
      'Failed to Open Card, Check Parameters');
      throw(err1)
   end
end

PI_OpBit

Takes input parameters to operate switches. In case of an error a message will appear instead of a number.

function PI_OpBit(SessionId,CardNum,OutSub,BitNum,State)
 
    try
       err=calllib ('piplx_w32','PIPLX_OpBit',SessionId,CardNum,OutSub,BitNum,State);
 
       if (err ~= 0)
           err=err1;
       end
 
    catch
      err1= MException('Calllib:FailtoOpenSpecifiedCard', ...
      'Failed to Communicate, Check Parameters');
     throw(err1)
   end
end

PI_CloseSpecifiedCard

Close the specified card using the session ID and Card Number.

function PI_CloseSpecifiedCard(SessionId,CardNum)
 
  try
     err=calllib ('piplx_w32','PIPLX_CloseSpecifiedCard',SessionId,CardNum);
 
     if (err ~= 0)
         err=err1;
     end
 
  catch
       err1= MException('Calllib:FailtoOpenSpecifiedCard', ...
       'Failed to Close Card, Check Parameters');
        throw(err1)
  end
end

PI_Disconnect

Disconnects the session.

function PI_Disconnect(SessionId)
 
  try
 
     err=calllib ('picmlx_w32','PICMLX_Disconnect',SessionId);
 
     if (err ~= 0)
        err=err1;
     end
 
  catch
      err1= MException('Calllib:FailtoDisconnect', ...
        'Failed to Disconnect, Check session number');
        throw(err1)
  end
end

Executable commands on MATLAB workspace

Here are example executable commands on workspace which will call the above functions. Address of BUS and SLOT may vary. Input parameters will be different for each system.

(Note: in this example the string 'PXI' is used instead of an IP address, this permits control of cards in the local PXI bus.)

Load_Libraries()
 
[SessionId]=PI_Connect(1,'PXI',1000,2400,1)
 
[CardNum]=PI_OpenSpecifiedCard(SessionId,6,12,1)
 
PI_OpBit(SessionId,CardNum,1,1,1)
 
PI_CloseSpecifiedCard(SessionId,CardNum)
 
PI_Disconnect(SessionId)

How did we do?
0 out of 0 people found this helpful.