Wiki

Below is the source of this page. To edit this source as well as other pages on the wiki, you must login.
====== IIO System Object ======

<note warning>These interfaces are deprecated. Please use the [[:resources:tools-software:transceiver-toolbox|Transceiver Toolbox]] or the [[:resources:tools-software:hsx-toolbox|High Speed Converter Toolbox]]</note>

The **IIO System Object** is based on the [[mw>/help/matlab/matlab_prog/what-are-system-objects.html|MATLAB System Objects™]] specification. It is designed to exchange data over Ethernet with an ADI hardware system connected to a FPGA/SoC platform running the ADI Linux distribution. 

The **IIO System Object** is available in both MATLAB and Simulink:
  * By calling it from a MATLAB script, it can be used for HIL simulation of [[mw>products/matlab/|MATLAB]] targeting different ADI platforms. 
  * By incorporating it into a [[mw>help/simulink/ug/what-is-matlab-system-block.html|MATLAB System Block]], it can be used for HIL simulation of [[mw>products/simulink/|Simulink]] models targeting different ADI platforms. 

The IIO System Object is built upon the [[/resources/tools-software/linux-software/libiio|libiio library]] and enables a MATLAB or Simulink model to:
  * Stream data to and from a target     
  * Control the settings of a target
  * Monitor different target parameters
Below is presented a top level diagram showing the architecture of a system.

{{:resources:tools-software:linux-software:libiio:clients:sys_obj.png?600|System architecture}}  

For more information about System objects, please refer to the MathWorks documentation on how to do [[mw>discovery/stream-processing.html|Stream Processing in MATLAB]].
===== Configuration File =====

The configuration file for a device has the .cfg extension and the name must match the device name set in the block's configuration dialog. It is a text file containing a set of fields that define the Linux drivers for the target device and the configuration channels that will be exposed by the Simulink block or MATLAB script. Entries in the configuration file can be commented by placing //#// at the begining of a line. The following entries can be found in a configuration file:
  * **data_in_device** - name of the Linux driver used for sending data to the device
  * **data_out_device** - name of the Linux driver used for reading data from the device
  * **ctrl_device ** - name of the Linux driver used for controlling and monitoring the device
  * **channel** - defines a control/monitoring channel. A channel is defined by a sequence of parameters as follows //<channel name, channel type, Linux attribute, associated device>//
      * //channel name// - represents the name of the channel to be displayed on the corresponding Simulink block port
      * //channel type// - can be either IN or OUT
      * //Linux attribute// - the Linux attribute that will be called to set/get data for the channel
      * //associated device// - the device to which the Linux attribute is associated to. This parameter can have the values //'data_in_device'//, //'data_out_device'// or //'ctrl_device'//. The parameter is optional, if it isn't specified then it is implied to be //'ctrl_device'//.  

Below is presented a configuration file example for the AD9361.

<code>
data_in_device = cf-ad9361-dds-core-lpc
data_out_device = cf-ad9361-lpc
ctrl_device = ad9361-phy
channel = RX_LO_FREQ,IN,out_altvoltage0_RX_LO_frequency,
channel = RX_SAMPLING_FREQ,IN,in_voltage_sampling_frequency,
channel = RX_RF_BANDWIDTH,IN,in_voltage_rf_bandwidth,
channel = RX1_GAIN_MODE,IN,in_voltage0_gain_control_mode,
channel = RX1_GAIN,IN,in_voltage0_hardwaregain,
channel = RX1_RSSI,OUT,in_voltage0_rssi,
channel = RX2_GAIN_MODE,IN,in_voltage1_gain_control_mode,
channel = RX2_GAIN,IN,in_voltage1_hardwaregain,
channel = RX2_RSSI,OUT,in_voltage1_rssi,
channel = TX_LO_FREQ,IN,out_altvoltage1_TX_LO_frequency,
channel = TX_SAMPLING_FREQ,IN,out_voltage_sampling_frequency,
channel = TX_RF_BANDWIDTH,IN,out_voltage_rf_bandwidth,
</code>

===== Property Dialog for Simulink =====

The input and output ports of the Simulink block corresponding to an IIO System Object are defined through the properties dialog of the object's block as well as through a configuration file that is specific to the targeted ADI device. The input and output ports are categorized as data and control ports. The data ports are used to receive/transmit buffers of continuous data from/to the target system in a frame based processing mode, while the control ports are used to configure and monitor different target system parameters. The number and size of the data ports are configured from the block's configuration dialog while the control ports are defined in the configuration file.

Below is presented an example of how an IIO System Object Simulink block looks like for the AD9361 device and what options can be configured from the block's properties dialog.

{{:resources:tools-software:linux-software:libiio:clients:ad9361_sys_obj.png?400|AD9361 System Object}}  
{{:resources:tools-software:linux-software:libiio:clients:sys_obj_block_cfg.png?250|Configuration Dialog}}

The block's properties dialog contains the following parameters:
  * **IP address** - represents the IP address of the target platform. This can be found by typing “ifconfig” in a terminal on the Linux side
  * **Device name** - the name of the ADI device that block will communicate with. The name of the device determines the configuration file that will be associated with the block. The configuration file name and device name must be the same.
  * **Number of input data channels** - represents the number of input data ports that the block will have
  * **Input data channel size** - number of samples that an input data buffer will have
  * **Number of output data channels** - represents the number of output data ports that the block will have
  * **Output data channel size** - number of samples that an output data buffer will have    


====== Downloads ======

<WRAP round info 80%>
In order to use the IIO System Object, your [[mw>products/matlab/|MATLAB]] license needs to include the following component:
  * MATLAB (R2015a or higher version is required) 
If you would like to use it in Simulink, your [[mw>products/matlab/|MATLAB]] license needs to include the following component:
  * Simulink
Besides, you need to have two things ready on your PC:
  * Microsoft Visual C++ 2013 Redistributable
  * A proper complier for your MATLAB. (For example, Microsoft Windows SDK is a good option.) And set it up using 'mex -setup' in the MATLAB command window.                                                      
</WRAP>

Before using the IIO System Object, the **libiio** library must be installed in the system. The installer for Windows can be found here:

<WRAP download>
**Windows libiio installer:**  
  * [[https://github.com/analogdevicesinc/libiio/releases|libiio Windows Installer]] (the .exe file)

**Libiio source code:** 
  * [[https://github.com/analogdevicesinc/libiio/tree/2014_R2|libiio source code]]
</WRAP>

The IIO System object source code and example models can be found here:

<WRAP download>
  * [[https://github.com/analogdevicesinc/libiio-matlab|IIO System Object]]
    * [[https://github.com/analogdevicesinc/libiio-matlab/blob/master/iio_sys_obj.m|iio_sys_obj.m]] is for Simulink
    * [[https://github.com/analogdevicesinc/libiio-matlab/blob/master/iio_sys_obj_matlab.m|iio_sys_obj_matab.m]] is for MATLAB
  * [[https://github.com/analogdevicesinc/mathworks_tools/tree/master/hil_models|Example models]]
</WRAP>

<WRAP round info 65%>
The example models need to have either the source code of the IIO system object copied to the folder where the model resides or to have the path to the IIO System Object source code added to the MATLAB path.   
</WRAP>
====== Setup ======

In order to establish the connection between the host PC and the target, there are several steps you need to follow on both sides.

Target side:
  - Get the latest libiio library by following the [[/resources/tools-software/linux-software/libiio#how_to_build_it|instructions]]. 

PC side:
  - Run the Windows libiio installer provided in "Downloads" section, which will install all the dlls and dependencies on your PC.
  - Find out the IP address of the target by typing "ifconfig" in a terminal on the Linux side
    - If used in MATLAB: Assign the IP address of the target to your object.
    - If used in Simulink: Open the Simulink block and type the IP address of the target in the block. Please note even if the IP address in the System objects property window seems correct, it is a good idea to edit it and click 'Apply' to avoid any caching issues.

====== Next Generation System Objects ======

Starting with MATLAB R2018b, ADI is transitioning to a new system object infrastructure based on collaboration with MathWorks Inc. When installing the [[resources:eval:user-guides:ad-fmcomms2-ebz:software:matlab_bsp|latest board support package]], it also induces documentation.
Analog Devices Wiki

Page Tools
