# Lesson 3. Creating a Pre-Emphasis User Application Script

In this MATLAB example, you'll learn how to modify the pre-emphasis measurement that you created in Lesson 2 to be a MATLAB standalone application. MATLAB standalone applications can be run using the MATLAB Runtime without have to install MATLAB.

MATLAB Applications are created using the MATLAB Compiler. The resulting *.exe file can be run without having MATLAB installed on the oscilloscope or PC. However, the MATLAB Runtime must be installed on the oscilloscope or PC where Infiniium is installed and the MATLAB Runtime version must be the same version as was targeted when the MATLAB Application was created.

## Procedure

1. Complete Lesson 2. The resulting PreEmphasis.xml and PreEmphasis.m files should be in Infiniium's user measurements folder (\Documents\Keysight\Infiniium\User Measurements).
2. Using a text editor, open the PreEmphasis.xml file. Change the content of the file's <Script> element from PreEmphasis.m to algorithm.exe. We will create algorithm.m which will be compiled into algorithm.exe.

All letters in algorithm.m must be typed in lower case. Naming the function Algorithm.m will break the script.

PreEmphasis.xml
Drag the mouse over this listing, enter Ctrl-C to copy, and paste it into your text editor.
<?xml version="1.0" encoding="utf-8"?> <Measurement xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Script>algorithm.exe</Script> <Name>Pre-Emphasis</Name> <Abbreviation>PreEmp</Abbreviation> <!-- <Icon>MyPicture.png</Icon> --> <Comments>This measures the amount of pre-emphasis on a signal.</Comments> <MeasurementType>1 Source</MeasurementType> <ValidType>Wave</ValidType> <Dependent Name = "Amplitude"> <SourceIndex>1</SourceIndex> </Dependent> <Dependent Name = "Peak-Peak"> <SourceIndex>1</SourceIndex> </Dependent> </Measurement>

3. Make a copy of the PreEmphasis.m file and rename the copy algorithm.m. The name of a script file for a standalone application must always be algorithm.m.
4. Open the algorithm.m script file in MATLAB. Make the following edits to the script as shown in this listing:

1. Add a algorithm function definition before the first line in the script as shown in green.
2. Add the reference `InputVars.`shown in red before every input variable in the script. Do not forget to add the period character "." between `InputVars.` and the variable. For example, `SrcData` becomes `InputVars.SrcData`.
3. Add a structure of output variables shown in blue before return statements.

Script algorithm.m with Modifications
Drag the mouse over this listing, enter Ctrl-C to copy, and paste it into the MATLAB editor.
    function OutputVars = algorithm(InputVars)

    newline=double(sprintf('\n'));

    % These values need to be set by the script.
    % Set Status to Correct only when Result is computed.
    Result = 0.0;
    Units = 'dB';
    Status = 'Invalid';
    ErrorMsg = '';

    % Verify MeasurementData exists.
    if ~isfield(InputVars, 'MeasurementData')
        ErrorMsg = ['Unable to retrieve any measurement data.' newline...
                    'Measurement Data is required, please load the XML configuration file '...
                    'rather than loading the MATLAB executable directly.'];
        OutputVars = struct(...
            'Status', Status,...
            'ErrorMsg', ErrorMsg);
        return;
    end

    % Do nothing if there is no SrcData.
    SrcData = InputVars.SrcData;
    if isempty(SrcData)
        ErrorMsg = 'No data';
        OutputVars = struct(...
            'Status', Status,...
            'ErrorMsg', ErrorMsg);
        return;
    end

    % Variables get cleared only when a MATLAB measurement is installed.
    % So, clear dependent measurement results to prevent another MATLAB
    % measurement from creating them and confusing the script.
    clear Vpp Vamptd;

    % Iterate through MeasurementData to find V p-p and V amptd
    Source = InputVars.Source;
    MeasurementData = InputVars.MeasurementData;
    for i=1:length(MeasurementData)
        if strcmp(MeasurementData(i).Source1, Source)
            if strcmp(MeasurementData(i).Name, 'Peak-Peak')
                Vpp.Result = MeasurementData(i).Result;
                Vpp.Status = MeasurementData(i).Status;
                Vpp.Source = MeasurementData(i).Source1;
            elseif strcmp(MeasurementData(i).Name, 'Amplitude')
                Vamptd.Result = MeasurementData(i).Result;
                Vamptd.Status = MeasurementData(i).Status;
                Vamptd.Source = MeasurementData(i).Source1;
            end
        end
    end

    % Verify required measurements have been made.
    if (~exist('Vpp') || ~exist('Vamptd'))
        ErrorMsg = ['Unable to retrieve "Peak-Peak" and "Amplitude" measurements.' newline...
                    'Please include Dependents in your XML configuration file.'];
        OutputVars = struct(...
            'Status', Status,...
            'ErrorMsg', ErrorMsg);
        return;
    end

    % Need to have status of V p-p and V amptd carry through
    if (strcmp(Vpp.Status, 'Correct') && strcmp(Vamptd.Status, 'Correct'))
        Status = 'Correct';
    elseif (strcmp(Vpp.Status, 'Invalid') || strcmp(Vamptd.Status, 'Invalid'))
        Status = 'Invalid';
        ErrorMsg = 'Dependent measurements have invalid statuses.';

        % Return now before possibly setting to Questionable later.
        OutputVars = struct(...
            'Status', Status,...
            'ErrorMsg', ErrorMsg);
        return;
    else
        Status = 'Questionable';
        ErrorMsg = 'Dependent measurements have questionable statuses.';
    end

    % Compute Result.
    Result = 20 * log10(Vpp.Result/Vamptd.Result);

    % Return output variables as a struct.
    OutputVars = struct(...
        'Result', Result,...
        'Units', Units,...
        'Status', Status,...
        'ErrorMsg', ErrorMsg);
    end

5. Create a folder to which you will save the files that will be compiled into your standalone application. The file are:

1. Move the algorithm.m script file that you created in the previous step.

2. Copy two additional files that are required when compiling a MATLAB script into a MATLAB standalone application:

   - InteropHelper.jar
   - wrapper.m

   The location of additional files to compile is:

   - From the "Demo" shortcut folder located in \My Documents\Keysight\Infiniium\User Functions
   - Directly from the folder: \Program Files\Keysight\Infiniium\Demo\
     User Functions\Demo Compiled MATLAB

Do not place the PreEmphasis.xml file into this folder.

6. Your folder for compiling your script should now have these files:

   - algorithm.m
   - InteropHelper.jar
   - wrapper.m
7. In MATLAB's Command Window, run the deploytool command to view the Compiler dialog box.
8. In the New Task, MATLAB COMPILER section, select Standalone Application.
9. In the Standalone DesktopApp tab, add wrapper.m as the main file, and enter PreEmphasis for Application Info.
10. In the Executable Details section, enter algorithm for the Executable Name, and select Standalone Application for the Application Type. algorithm will be the name given to your .exe file.
11. In the Files Required for Standalone to Run section, add the algorithm.m and InteropHelper.jar files as shown in the following picture.
12. Save your standalone application project. Then, select Build from Build and Package.
13. When the compile completes, close the MATLAB compiler and open File Explorer. MATLAB has placed the compiled files for the application in the \StandaloneDesktopApp1\output\build folder. The executable file is algorithm.exe. Remember, at the start of this lesson you edited the PreEmphasis.xml file's <Script> element to use the algorithm.exe file.
14. Copy the algorithm.exe file to Infiniium's user functions folder (\Documents\Keysight\Infiniium\User Functions).
15. On each PC or oscilloscope where you want to run your executable, perform the following steps:

1. Install Infiniium
2. Place the PreEmphasis.xml and algorithm.exe files in Infiniium's user measurements folder (\Documents\Keysight\Infiniium\User Measurements).
3. Install the correct MATLAB Compiler Runtime (MCR) version.
4. In the Infiniium application, make a Single acquisition.
5. Choose Measure > Measurements....
6. At the bottom of the Add Measurements dialog box, click User Defined Wave Measurements....
7. In the User Measurement Setup dialog box, select an available tab.
8. Click Browse and select your XML configuration file, PreEmphasis.xml and close the dialog box.
9. Add the measurement. Click on your new Pre-Emphasis measurement button.
10. In the User Meas dialog box, select the Signal and measurement Region; then, click Apply.
11. View the results in the Results panel. Notice that the results of the two dependent measurements are not listed.

You may have to wait a few seconds for the measurement to appear.