Versions Compared

Old Version 3

changes.mady.by.user Catherine Spain

Saved on

compared with

New Version Current

changes.mady.by.user Gary Worsham

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

This Developers Quick Start Guide is a companion document to the (8.D.2.1) Custom Modules Developer's Guide. It describes creating custom modules for Audio Weaver. Both of these documents reference information contained in the (8.D.2.1) MATLAB Scripting API. This document is intended for developers creating their own custom Audio Weaver module packs.

...

  • The module is instantiated by calling the module’s MATLAB m-file create function, then its prebuild function, then a set function if implemented. The module is displayed on the canvas using the icon image from the images folder with default pins and other information coming from the xml file in the xml folder.

  • Any parameters defined by the module MATLAB m-file are displayed by default underneath the module on the canvas unless marked hidden or explicitly written by calling a non-null TextLabelFunc. See (8.D.2.1) Custom Modules Developer's Guide for more information on labels.

...

  • The module’s MATLAB prebuild function and any set function is called again. Next, a module create command for the module’s current configuration is generated as part of the list of AWS text commands sent to AWE_Server. AWE_Server turns the AWS text commands into binary AWB commands and sends each of these commands over the tuning interface to the target hardware. The target hardware (can be the Native Windows server) then instantiates the module as specified by the module create command and the module’s Constructor function.

  • For this to work, the C library containing the module’s definition must be linked into the target firmware, and the module must be included in the ModuleList.h file’s list of modules compiled into the target.

...

The wizard will create the following folder structure, with default files in each folder as necessary:

📂 my_new_module

📁 my_new_module\doc

📁 my_new_module\images

📁 my_new_module\include

📁 my_new_module\inner

📁 my_new_module\lib

📁 my_new_module\matlab

?? my_new_module\projects

📁 my_new_module\projects\source

📂 my_new_module\projects\VS2010

📁 my_new_module\projects\VS2010\BuildDll

📁 my_new_module\projects\VS2010\BuildLib

📁 my_new_module\projects\xml

Note: When creating or editing module folders, the following items apply:

  • The folder VS2010 must be renamed to match the appropriate version of Microsoft Visual Studio.

  • The folder matlab cannot be deleted from the File Explorer if the MATLAB application is open.

...

The wizard creates a MATLAB m-file that defines the module arguments, pins, parameters, inner C file location, Inspectors, and more. This is the main starting point in the module creation process. See (8.D.2.1) Custom Modules Developer's Guide for an in-depth look at creating this m-file. To be discovered by Designer, this m-file must reside in the “matlab” folder defined in the Create Folders section.

...

The wizard will also create a file named “classids.csv” and place in the “parent” folder defined in the Create Folders section. This file defines the unique class ID for each of the modules in the module pack, where the IDOFFSET is the value representing the lowest classID for this Module Pack, to which subsequent incremental module ID values are added.

The content of the classids.csv file for the generated module pack (‘my_new’ pack with base ID 60600) is as follows:

...

The contents of this file for the my_new_module pack example is:

Code Block
function [MM, NAME] = make_my_new_module_library(GENDOC)
%
% make_my_new_module_library(GENDOC)
% Generates the my_new_module library.
% this includes sources, header files, schema, and overall module
% list. Arguments:
% GENDOC - Boolean that specifies whether documentation (in Word)
% format should be generated. By default, GENDOC=0.
%
% [MM, NAME]=make_my_new_module_library(GENDOC)
% Optional output arguments return the cell array of modules that was
% used to build the library and the name of the library. When an
% output argument is requested, then the function DOES NOT GENERATE
% code.
%
% Copyright (c) 2019 DSP Concepts, Inc. All Rights Reserved.
if (nargin < 1)
 GENDOC = 0;
end

% ----------------------------------------------------------------------
% Instantiate each module using default arguments
% ----------------------------------------------------------------------
NAME = 'MyNew';
MM = cell(0,0);
MM{end+1} = my_new_module('temp');
if (nargout > 0)
 return;
end

% ----------------------------------------------------------------------
% Set the code generation directory relative to the directory
% in which this m-file is stored.
% ----------------------------------------------------------------------
MFILE = mfilename('fullpath');
[pathstr, name] = fileparts(MFILE);

% Remove the last directory level
ind = find(pathstr == filesep);
ind = max(ind);
SRC_DIR = pathstr(1:ind-1);
INC_DIR = fullfile(SRC_DIR, 'Include');
DOC_DIR = fullfile(SRC_DIR, 'Doc');
INNER_DIR = fullfile(SRC_DIR, 'Inner');
DIR = {SRC_DIR; INC_DIR; DOC_DIR; INNER_DIR};

% ----------------------------------------------------------------------
% Generate the library.
% ----------------------------------------------------------------------
global AWE_INFO;
AWE_INFO.buildControl.combineSourceFiles = 0;
AWE_INFO.buildControl.ignoreClassIDs = 0;
awe_generate_library(MM, DIR, NAME, '', GENDOC);
awe_generate_doc(MM, DOC_DIR, fullfile(DOC_DIR, '_my_new_module.html'), 'my_new_module');

...

The creation steps below are supplemental to the custom module creation process discussed in (8.D.2.1) Creating Custom Modules.

  1. Start by creating a Traditional Module to get the required files and folder structure of an Audio Weaver Module.

    1. The Custom Module Pack Wizard in AWE Designer is a great starting point for getting started working with the required module files and folder structure.

  2. As you edit the module’s MATLAB (.m) file, add the following line of code in the function:

    1. M.isInterpreted = 1;

    2. Switching this flag to 0 will force the module to be executed as a typical MATLAB module. While this makes the module inaccessible for Standard Designer users, the Module Author may do this in order to use the MATLAB debugging infrastructure to help resolve issues with their module.

  3. Follow the Module Creation steps as stated to get a properly functioning module, including the Module Generation MATLAB script e.g., make_module_pack(1) in Designer Pro Edition.

  4. Open the Interpreted Module’s Visual Studio solution and build the project. Make sure the built DLL is successfully created and in the Interpreted Module’s folder.

  5. Share the entire folder of the Interpreted Module (including the DLL) with other Designer users.

    1. Once shared, any user must copy the Interpreted Module’s DLL to the same directory as their AWE_Server.exe
      (for example, C:\DSP Concepts\AWE Designer 8.C.2.4 Standard\Bin\win32-vc142-rel\)

  6. Once Designer and Server are running, install the Interpreted Module to the Module Path using the Setting Search Paths functionality.

  7. The Interpreted Module can now be dragged out from the Module Palette to Designer’s canvas, with all the same capabilities as other Audio Weaver modules.

    1. The default location for a new Custom Module is in the “Third Party” folder. This can be changed in the MATLAB script by updating the M.moduleBrowser.path value.

...

Any additional custom module functions available for Audio Weaver modules are not supported for Interpreted Modules at this time. Thus, they must not be defined in the Interpreted Module’s MATLAB file as it will make the whole module unusable in Designer. If you do have unsupported custom module functions in your Interpreted Module (for example, testHarnessFunc), make sure to comment out the function assignment before using the module.

...