Matlab Automation API

Introduction

Audio Weaver is closely coupled with Matlab. The Matlab Automation API consists of a collection of Matlab functions which interact with Audio Weaver. The Matlab Automation API allows users to utilize the full power and flexibility of Matlab to configure and control Audio Weaver.

Controlling an Audio Weaver Layout
One important use of the Matlab Automation API is to control an Audio Weaver layout created with AWE Designer. A Matlab script can be used to:

• Obtain a Matlab structure containing all information of an Audio Weaver Layout
  • View layout modules, module variables, module properties at Matlab command line
  • Read/Write module variables and properties via Matlab
• Interact via Matlab with a live running layout, (running in Native mode on PC or running on an embedded target)
• Control the layout on a block by block basis:
  • Drive the layout input with any data:
    • .wav file
    • .mp3 file
    • .mat file
    • .csv file
    • Data created by user either statically or dynamically
  • Read and write module parameters
  • Read and write intermediate signal values:
    • Read any signal at any point in the signal flow
    • Write data into the layout at any point in the signal flow
    • Process intermediate signal values with Matlab and inject the processed value back into the signal flow
• Set module arguments
• Analyze and evaluate layout outputs with Matlab processing and plotting

Full Scope of the Matlab Automation API
In addition to controlling an Audio Weaver Layout the Matlab Automation API can be used for:

• Configuring the Audio Weaver Environment
• Profiling
• Processing Files Quickly -- Faster Than Real Time
• Build Automation
  • Continuous Integration
  • Generate Target Files
• Signal Flow Automation
  • Traverse a large layout and extract or inject information
• Power Debugging
• Presets
  • Automatically load a layout with multiple sets of preset values
• Managing Flash File System
  • Use Matlab scripts to interact with on board flash memory

Prerequisites for Using the Matlab Automation API

• Familiarity with Matlab command syntax and scripting
  Matlab Basics
• Familiarity with the Audio Weaver Designer and Server Basics
  Audio Weaver Basics

Installation and Setup

Setting up Matlab and Audio Weaver to use the Matlab Automation API

• Install Matlab
  • You need a standard Matlab license and the Signal Processing toolbox
  • The Matlab Automation API is compatible with Matlab 2021b or later however 2022b gives by far the most efficient performance and we recommend this.
• Install Audio Weaver Pro
  The Matlab Automation API is included with the “Pro” versions of Audio Weaver; it is not part of the Standard version.
  Audio Weaver Pro Download
• Update Matlab's search path to include Audio Weaver
  • Set Matlab search path to include AWE\matlab where AWE is the full pathname of your Audio Weaver installation. This can be done with the addpath command from Matlab command line; e.g. :
    addpath('C:\DSP Concepts\AWE Designer 8.2025.1 Pro\matlab')
    You can also use the MATLAB menu item File --> Setup Path to update the path
• Launching AWE Designer and AWE Server
  You can now launch AWE Server and AWE Designer from the Matlab command line
  • awe_designer --> launches AWE Server and AWE Designer
  • awe_init --> launches only AWE Server

Basics of Matlab Automation API

Here we describe the main components of the Matlab Automation API and their usage.

• Key Matlab Structures

  • AWE_INFO
    AWE_INFO is a global variable within the Audio Weaver MATLAB API.   AWE_INFO is a structure whose fields control various aspects of Audio Weaver.   AWE_INFO's fields may be set to control the Audio Weaver environment and read to get the status of the environment.  

  A subset of important AWE_INFO fields, along with comments and examples can be found here:
  AWE_INFO Full Doc

  A complete description of each field of AWE_INFO can be found here:
  AWE_INFO Full Doc

  • GSYS
    The GSYS structure is a MATLAB structure that contains the entire state of the Audio Weaver Designer GUI. The GSYS structure holds a snapshot of everything within the Audio Weaver Designer interface. GSYS is a complex structure with much information and many fields. Much of the GSYS structure is rarely needed when using the Matlab Automation API. The most important field in GSYS is GSYS.SYS. A complete description of each field within GSYS can be found here:
    GSYS Full Doc

  • GSYS.SYS
    The GSYS.SYS structure is the most commonly used field of GSYS when using the Matlab Automation API.   GSYS.SYS provides all information about the modules of an Audio Weaver layout and their interconnections and settings. GSYS.SYS provides a programmatic way to inspect and manipulate the structure and parameters of your Audio Weaver design from within MATLAB. A complete description of GSYS.SYS can be found here:
    GSYS.SYS Full Doc

• Getting Access to the Key Matlab Structures
  First we must get access to the GSYS structure. This can be done in two different ways:
  1.)Using load_awd()
  2.)Using get_gsys()

• get_gsys() VS load_awd()
  The Matlab Automation API provides 2 mechanisms for getting the GSYS structure.

  • GSYS = get_gsys("Example.awd");
  • GSYS = load_awd("Example.awd");

  GSYS = get_gsys("Example.awd")

  Used to load an Audio Weaver design which is open in AWE Designer. get_gsys() requires an absolute path name as its argument, or the invocation of get_gsys() must come from the same directory as the .awd file. get_gsys() requires that both the AWE Server and AWE Designer are running and Example.awd must be open in AWE Designer. get_gsys() allows live interaction with a design which is running in AWE Designer, either in native mode or on an embedded target. We can use the GSYS.SYS structure obtained from get_gsys() to set and read values from the layout on the running target. Usage of get_gsys() is demonstrated in Example 1 below.

  GSYS = load_awd("Example.awd")

  Used to load an Audio Weaver design from an .awd file on disk to the GSYS MATLAB structure. load_awd() can take absolute or relative path names as its argument, e.g. load_awd("../Example.awd"). load_awd does not require either AWE Server or AWE Designer to be running. We can use the GSYS.SYS structure obtained from load_awd() to set and read values from the layout. load_awd is usually used for controlling an AWE layout for evaluation, automation, or regression testing. Usage of load_awd() is demonstrated in Examples 2 and 3 below.

• Getting Access to AWE_INFO
  We must first get a GSYS structure, then we can declare a global variable AWE_INFO which will be fully populated with the info from the Audio Weaver environment. e.g.:
  GSYS = load_awd("Example.awd");
  global AWE_INFO;
  Usage of AWE_INFO is demonstrated in Examples 2 and 3 below.

• Viewing System Structure, (GSYS.SYS), and Internal Module Parameters
  First we must get the GSYS structure into our Matlab environment:
  GSYS = load_awd("Example2.awd");
  % For convenience we want to refer to GSYS.SYS with the variable S
  S = GSYS.SYS;
  Now that we have the system structure GSYS.SYS in Matlab, we can view it at the Matlab command line. The system structure contains one entry per module in the system. e.g. for our Example2.awd: K>> S = NewClass // Newly created subsystem
  Annotation1: [Annotation]
  Annotation2: [Annotation]
  TypeConversion1: [TypeConversion]
  Data_In_AWE: [Sink]
  ScaleIn: [ScalerV2]
  MuteIn: [MuteSmoothed]
  InputMeter: [Meter]
  WhiteNoise: [WhiteNoise]
  FIR1: [FilterbankFIRV2]
  ScaleWhiteNoise: [ScalerV2]
  MuteWhiteNoise: [MuteSmoothed]
  PinkNoise: [PinkNoise]
  ScalePinkNoise: [ScalerV2]
  MutePinkNoise: [MuteSmoothed]
  SingleTone: [SineSmoothedGen]
  ScaleSingleTone: [ScalerV2]
  MuteSingleTone: [MuteSmoothed]
  Interleave1: [Interleave]
  RouteSimulatedData: [Router]
  Add1: [Adder]
  MuteOut: [MuteSmoothed]
  OutputMeter: [Meter]
  TypeConversion2: [TypeConversion]

  We can now view all the internal parameters of any of the modules. e.g. we can enter S.ScaleIn:
  K>> S.ScaleIn
  ScaleIn = ScalerV2   // General purpose scaler with a single gain
  gain: 7 [dB]   // Gain in either linear or dB units.
  smoothingTime: 0 [msec]   // Time constant of the smoothing process (0 = unsmoothed).
  isDB: 1   // Selects between linear (=0) and dB (=1) operation
  targetGain: 2.23872113   // Target gain in linear units.
  currentGain: 1   // Instantaneous gain applied by the module.
  smoothingCoeff: 1   // Smoothing coefficient.

• Basic Usage of the Matlab Automation API
  The Matlab Automation API contains a large number of commands. The complete list of commands can be found here:
  Matlab Automation API Commands
  To control an Audio Weaver layout only a small subset of these commands is usually used. Below we give the commands used for 2 cases:
  1.)Interacting live with a running layout. Here we use a Matlab script to interact with a layout running in Native mode on the PC or running on an embedded hardware target. The Matlab commmands are the same regardless of the target.
  2.)Interacting offline with an Audio Weaver layout. We drive data of our choice into the layout's input pin, modify module variables and read and analyze outputs. The commands shown below are by far the most commonly used to control AWE layouts and are often all you will need.

• Interacting Live With a Running Layout
  Below is a typical sequence of Matlab Automation API commands, (and standard Matlab commands), used to interact live with a running Audio Weaver layout. The Matlab Automation API commands are shown as bold face italic below.

• Launch AWE Designer
  • Use the awe_designer command from the Matlab command line to launch AWE Server and AWE Designer.
• Open the Audio Weaver layout in AWE Designer, e.g. Example1a.awd
• Connect to desired target with AWE Server and run the layout in AWE Designer

Place the following commands into a Matlab script:
Get the GSYS structure for Example1a.awd
* GSYS = get_gsys("Example1a.awd");

Get GSYS.SYS
* S = GSYS.SYS;

Now we can interact with the running layout. e.g.:
while(1)
sinkData = S.SinDisplay.value;
plot(sinkData);
pause(.5);
end
This is the code used in Example1a. We do a Matlab plot of the Sink Display module SinDisplay. We can use the inspector for the Scaler1 module and observe the results in the Matlab plot.

• Interacting Offline with an Audio Weaver Layout

Below is a typical sequence of Matlab Automation API commands, (and standard Matlab commands), used to interact offline with an Audio Weaver layout. The Matlab Automation API commands are shown as bold face italic below.
These are the set of commands used in Examples 2 and 3 in the Controlling an Audio Weaver Layout section below.

• Launch AWE Server
  • You can use either the awe_init or awe_designer commands from the Matlab command line. awe_init launches only AWE Server whereas awe_designer launches both AWE Server and AWE Designer. For controlling an Audio Weaver layout we must have AWE Server running. We do not need AWE Designer running but it will not interfere with anything. NOTE: we must have AWE Server running to execute the command S = build(S) below; the commands prior to S = build(S) do not require AWE Server to be running.
• GSYS = load_awd("Example2.awd");
  • Loads an Audio Weaver design file (.awd) directly from disk into a GSYS structure within the MATLAB environment.
  • Our main interest for controlling a layout is the SYS field of GSYS.
• S = GSYS.SYS;
  • Rename GSYS.SYS to S for convenience. S references all the layout information. S gives us access to all modules on the layout and all module variables and internal module state information.
• S.targetSpecificInfo.RT = 0;
  • Configures the Audio Weaver system for Non-Real Time Processing. Tells Audio Weaver that processing will not happen with a continuous real time audio stream, but rather within the Matlab environment via the process() function. This also disables double buffering of the input/output (I/O) pins.
• global AWE_INFO;
  • Declares AWE_INFO as a global variable within the current MATLAB workspace. AWE_INFO can now be accessed within the Matlab script to control various aspects of the Audio Weaver software.
• AWE_INFO.displayControl.showHidden = 1;
  • Makes hidden variables within modules visible to the Matlab script
• AWE_INFO.buildControl.matchDataType = 0;
  • Disables the automatic data type matching feature during the Audio Weaver build process.
• AWE_INFO.buildControl.validateTopLevelOutputPin = 0;
  • Disables the validation of the top-level output pin properties during the build process in Audio Weaver.

• AWE_INFO.buildControl.validateTopLevelBlockSizes = 0;

  • Disables the validation of the block size of the top-level output pin during the build process in Audio Weaver.

• S = build(S);
  NOTE: In order to run build(S), the Audio Weaver Server must be running. AWE Server can be launched with the awe_init command

  • S = build(S) builds the Audio Weaver system:
    • Resolves all wire information: propagation of wire properties such as the number of channels, block size, sample rate, and complexity, starting from the system input pin and proceeding through the modules to the output pin.
    • Calls the prebuild functions for the modules
    • Calls the modules' Matlab Set functions if defined to update derived variables. The channel name and channel delay functions will also be called to propagate this information.
• S.MuteIn.isMuted = 0;
  • This is an example of setting a module variable. Here the MuteIn module is set to unmuted.

• x = DataIn(StartIdx:StopIdx,:);
  WIRE_IN={x};
  [S, WIRE_OUT]=process(S, WIRE_IN, 1);
  DataOut(StartIdx:StopIdx,:) = WIRE_OUT{1};

  • Put one block of data into the Matlab array x
  • Create the cell array WIRE_IN containing the data in x
  • Run this block of data through the Audio Weaver layout processing
  • Store the output data in the Matlab array DataOut

• save_awd("Example2.awd", GSYS);

  • Save changes made by the Matlab script to the .awd file on disk.
    
    
• Saving Changes to a Layout
  When we get a GSYS structure for a layout, either with either with load_awd() or with get_gsys() we can use GSYS.SYS to modify the layout. If we want our changes to persist in the .awd file on disk we must explicitly save them.
  1.)If we obtained GSYS with:
  GSYS = load_awd('Example.awd');
  then we must save any changes with the command:
  save_awd("Example.awd", GSYS);
  2.)If we obtained GSYS, (with Example.awd open in AWE Designer):
  GSYS = get_gsys('Example.awd');
  We can save changes either with AWE Designer File --> Save or with the command:
  save_awd("Example.awd", GSYS);

A Deeper Look at the Matlab Automation API

Examples 1,2,3 below demonstrate basic control of an Audio Weaver layout. We now describe more control possibilities:

• Call By Reference for Matlab Automation API Functions
  The internal Audio Weaver Designer MATLAB framework was refactored in Designer versions 8.D.2.4 and above. AWE objects are now passed by handle rather than copied by assignment in MATLAB scripts. This refactoring on its own can lead to 20-30% improvements in layout build and load times, and also opens the door for further improvements in future versions.
  However users must be aware of how the changes affect using the Matlab Automation API.
  Some Matlab scripts which worked correctly with versions prior to 8.D.2.4 will not work correctly now
  Lets look the code snippet:
  GSYS = load_awd('example.awd'); SYS2 = GSYS.SYS; In Designer versions prior to 8.D.2.4 this code would create SYS2 as a full independent copy of GSYS.SYS. Modifications to SYS2 would have no effect on GSYS or GSYS.SYS.
  In Designer versions 8.D.2.4 and above, this could will create SYS2 as simply a pointer to GSYS.SYS. Modifications to SYS2 will be mirrored in GSYS.SYS.
  This behavior means that some Matlab scripts written for Designer versions prior to 8.D.2.4 will not work correctly.

Below is an example of a MATLAB script using AWE objects that works correctly in Designer 8.D.2.3 and earlier but will result in an error in 8.D.2.4 and above

function badexample()
% This function shows an example of a script that worked with previous
% versions of designer, but will no longer work starting at 8.D.2.4/5
% Previously, modifications of SYS2 below would not affect GSYS.SYS.
GSYS = load_awd('example.awd');
% Make a copy of GSYS.SYS with direct assignment, then modify SYS2
% by deleting a marker module 'M1'. SYS2 now points to GSYS.SYS
% so modifications to SYS2 will change the original GSYS.SYS.
SYS2 = GSYS.SYS;
SYS2 = delete_module(SYS2, 'M1');
% This build will now complain about missing module M1 and/or bad
% connections when building the original system
GSYS.SYS = build(GSYS.SYS);
return

The error from the example above looks like this:

Error using awe_module/prebuild
AWE ERROR:Wiring error at the top-level system
AWE ERROR:Module Scaler1 input pin 'in1' is not connected

The following function uses the MATLAB copy function instead of a direct assignment to create SYS2. This function will work in Designer versions 8.D.2.4 and above. Using copy is backwards compatible with previous versions of Designer (8.D.2.3 and earlier), so it is always the preferred way to create new copies of AWE objects in MATLAB scripts.

function goodexample()
GSYS = load_awd('example.awd');
% Make a copy of GSYS.SYS, then modify SYS2. This will not modify the
% original GSYS.SYS
SYS2 = copy(GSYS.SYS);
SYS2 = delete_module(SYS2, 'M1');
% The original system is unchanged so it will still build
GSYS.SYS = build(GSYS.SYS);
return

Other programming paradigms are not affected by the updates in 8.D.2.4 and above, so only scripts of the style shown above need to be updated to use the latest versions of Designer. However you need to remember that if you want a separate independent copy of a GSYS.SYS structure you must do: SYS2 = copy(GSYS.SYS).

• Reading Module Arguments

We can read module arguments from a Matlab script using the module's constructorArgument function.
Lets illustrate with a DC Source module named DC1 on our layout, (call this layout RMA.awd). If we look at the Arguments list in the module properties window we see 4 arguments:
numChannels
blockSize
sampleRate
controlPin
We get the GSYS.SYS structure of the layout from a Matlab script:
fNameAWD = 'RMA.awd';
% Load the Audio Weaver layout
GSYS = load_awd(fNameAWD);
S = GSYS.SYS;

If we set a breakpoint after we get GSYS.SYS, we can type S.DC1.constructorArgument from the Matlab command line and we get:
K>> S.DC1.constructorArgument
ans = 1×4 cell array
{1×1 awe_variable} {1×1 awe_variable} {1×1 awe_variable} {1×1 awe_variable}
i.e. DC1.constructorArgument is an array of cell arrays with one entry for each module argument. We can access the names and values of each module argument using the name and value fields of each cell array. e.g.:

K>> S.DC1.constructorArgument{1}.name
ans = 'numChannels'
K>> S.DC1.constructorArgument{1}.value
ans = 1

One thing to note is that the blockSize and sampleRate argument values if not filled in explicitly by the user will inherit their values from the layout input pin. In this case they will show up as empty cell arrays using constructorArgument. e.g. :

K>> S.DC1.constructorArgument{3}.name
ans = 'sampleRate'
K>> S.DC1.constructorArgument{3}.value
ans = []

In this case we can read their values from the module output pin. e.g.:

K>> S.DC1.outputPin{1}.type.blockSize
ans = 32
K>> S.DC1.outputPin{1}.type.sampleRate
ans = 48000

• Setting Module Arguments
  We can read module arguments using the constructorArgument function however we must use the readd_module() function to set them. Changing the values of module arguments will often affect memory allocation and thus the system must be built again. The readd_module() function updates the module by recreating it using a different set of instantiation arguments.
  SYS=readd_module(SYS, HNAME, OLDNAME, NEWNAME, ARGS);
  Arguments:
  SYS - @awe_subsystem object.
  HNAME - hierarchical name of the subsystem containing the module.
  To change a module in the top-level system, set HNAME=''.
  OLDNAME - existing name of the module.
  NEWNAME - new name for the module.
  ARGS - cell array of input arguments.
  The function updates the module and all connections and returns the modified system SYS.
  Often we will not rename the module, and thus OLDNAME and NEWNAME will be the same. Example syntax with a DC Source module:
  numChannels = 9;
  blockSize = S.inputPin{1}.type.blockSize;
  sampleRate = S.inputPin{1}.type.sampleRate;
  controlPin = 0;
  DCArgs = {numChannels blockSize sampleRate controlPin};
  S = readd_module(S, '', 'DC1', 'DC1', DCArgs);
  It is important to note that readd_module() returns a new copy of its S structure argument. Thus if we obtained S as S = GSYS.SYS, then after the call to readd_module, the changes made to S are not automatically copied to GSYS.SYS, and to save the changes we must copy S back to GSYS.SYS. Below is Matlab code illustrating this issue:

  % Name of Audio Weaver layout to be controlled
  fNameAWD = 'readd_module_tester_1.awd';
  fNameAWD2 = 'readd_module_tester_2.awd';

  % Load and build the Audio Weaver layout
  GSYS = load_awd(fNameAWD);
  S = GSYS.SYS;
  global AWE_INFO;
  AWE_INFO.displayControl.showHidden = 1;

  % Set DC1 to have 9 channels
  numChannels = 9;
  blockSize = S.inputPin{1}.type.blockSize;
  sampleRate = S.inputPin{1}.type.sampleRate;
  controlPin = 0;
  DCArgs = {numChannels blockSize sampleRate controlPin};
  S = readd_module(S, '', 'DC1', 'DC1', DCArgs);
  GSYS.SYS = S;

  % Save changes made by this script to the .awd file
  save_awd(fNameAWD2, GSYS);

  We could achieve the same result by doing:
  GSYS.SYS = readd_module(GSYS.SYS, '', 'DC1', 'DC1', DCArgs);

• Setting Clock Divider
  We can read and write the clock divider for any module using Matlab scripts.
  Lets illustrate with a DC Source module named DC1 on our layout, (call this layout CDTest.awd). First in AWE Designer GUI we can set the DC1 build property clockDivider to 1B1. We can read the clock divider from Matlab as:
  fNameAWD = 'CDTest.awd';
  % Load the Audio Weaver layout
  GSYS = load_awd(fNameAWD);
  S = GSYS.SYS;
  Set a break point after getting GSYS.SYS and run the script. Then at Matlab command line type: S.DC1.clockDivider and we get:
  K>> S.DC1.clockDivider
  ans = 1.001001000000000
  1.001001000000000 is an internal numerical representation of the 1B1 clock divider value.
  We can set the S.DC1.clockDivider to a new value, (e.g. the value for 1C1), but we must set it to the internal numerical representation of 1C1. So we must first obtain this value. We can get the value using the Matlab Automation API function convert_thread_id() with the syntax:
  newValue = convert_thread_id('1C1', 'clockDividerF'). (this gives us newValue = 1.002001000000000). Now we can set S.DC1.clockDivider to 1C1 with the Matlab code:
  S.DC1.clockDivider = newValue;

• Reading and writing intermediate signal values
  We can add extra sources and sinks in the layout which allow us to read data at any point in the signal flow and to inject data into any point in the signal flow. We can take intermediate data and process it with Matlab functions and then inject the processed data into the layout. e.g. if we had a Matlab implementation of a special beamformer, we could take data from some point in our layout's signal flow, run that data through the beamformer and inject the beamformer output back into the layout. This is illustrated in Example 3 below.

• Setting breakpoints in Matlab script
  We can gain insight into the behavior of our AWE layout using breakpoints
  • Stop execution after a selected number of data blocks
  • Stop execution based upon signal values or module variable value
  • Examine the state of the system at the breakpoint
• Setting module variables based upon intermediate data
  We can examine our system's state on a block by block basis and set module variables to different values based upon our analysis.
• Data analysis with full power of Matlab
  We can use all Matlab functions to analyze, process and plot our ouput data or intermediate data

• Getting and setting module Runtime Status
  Modules on an Audio Weaver layout may have one of 4 run time status values:
  'active', 'muted', 'bypassed' and 'inactive'.
  We can use the get awe_getstatus() function to get the Runtime Status of any module on our layout
  e.g. STATUS=awe_getstatus(S.MuteIn);
  We can use the awe_setstatus() function to set the Runtime Status of any module on our layout
  e.g. S.MuteIn = awe_setstatus(S.MuteIn, 'bypassed');

  Details of module Runtime Status can be found here:
  AWE Modules' Runtime Status

• Viewing hidden variables
  Some AWE modules have variables which are hidden when viewing on the Designer canvas. We can make these visible using Matlab by executing:
  global AWE_INFO; AWE_INFO.displayControl.showHidden = 1; This will make the hidden variables visible for reading/writing from our Matlab Automation API script. The hidden variables will also be visible now when we view modules' fields from the Matlab command line.

• Looking at variable ranges
  We can read/write and view the ranges of module variables: e.g. for our Example 2 when we have obtained S as S = GSYS.SYS

  • Entering S.ScaleIn.gain.range at the Matlab command line gives
    K>> S.ScaleIn.gain.range
    ans =
    -24 24
  • We can read the ranges in a Matlab script:
    LowerLimit = S.ScaleIn.gain.range(1);
    UpperLimit = S.ScaleIn.gain.range(2);
  • We can set the ranges as e.g. :
    S.ScaleIn.gain.range(1) = -27;
    S.ScaleIn.gain.range (2) = 27;

• Examining Variable Sizes
  We can read these sizes of any variable arrays but we cannot set them. Resetting variable sizes affects memory allocation and thus must be done prior to building the system. Must be done with the readd_module function.
  e.g. NumCoeffs = S.FIR1.coeffs.size;

Controlling an Audio Weaver Layout

We give 3 examples. Each example consists of a .awd file and one or more .m files. These are available for download. It is recommended to download the files and run the demos. You can then experiment with modifying the files.

Example 1
Live Tuning on a Target
When an AWE Design is running on a target, (PC or embedded), we can get the GSYS with get_gsys() and read and write module variable on the target in real time.
Example 1 consists of 3 files:

• Example1.awd
• Example1a.m
• Example1b.m

These files may be downloaded here:
Example 1

Example 1a
We run an infinite loop in our Matlab script. Each loop iteration we read the value of the SinDisplay sink array and plot it. We pause .5 seconds between loop iterations. The user can use the inspector of the Scaler1 module to vary the gain of the sinusoid signal. User can observe the changes made on both the Matlab plot and on the SinDisplay sink module inspector.
Instructions:
1.)Open Example1.awd with AWE Designer
2.)Optionally you can connect to an embedded target with AWE Server
3.)Run the design with the Designer Run button
4.)Open inspectors for the SinDisplay and Scaler1 modules
5.)Run Example1a.m from Matlab.
6.)Vary the gain by hand with the Scaler1 inspector and observe the amplitude change in both the Matlab plot and in the SinDisplay inspector.

Example 1b
We change the gain of our Scaler1 module with our Matlab script. We change the gain 3 times with a selectable pause between changes, (default pause = 3 seconds).
Instructions:
1.)Open Example1.awd with AWE Designer
2.)Optionally you can connect to an embedded target with AWE Server
3.)Run the design with the Designer Run button
4.)Open the inspector for the SinDisplay module
5.)Observe the sin wave displayed with amplitude 1
6.)Run Example1a.m from Matlab and observe the amplitude of the sin wave change from 1 to 30 to 50 to 70 with 3s pauses between changes

Example 2
Basic Control of an Audio Weaver Layout
This example illustrates the basic usage of the Matlab Automation API to control an AWE layout.
The example consists of 3 files:

• Example2.awd
• Example2.m
• Bach Piano 48kHz.mp3

These files may be downloaded here:
Example 2

Example2.awd consists of line/file input plus 3 simulated data sources: single tone, pink noise, white noise. These sources can be mixed together in a variety of ways. Example1.m is a Matlab script which illustrates the most fundamental aspects of controlling a layout:

• Load and save the .awd file
• Setting module parameters
• Build and run
• Pumping data
• Reading output data

Example2.m takes the input data Bach Piano 48kHz.mp3 and runs it through the layout with some processing. The ouput data is written to a Matlab array. The input and output data are plotted and displayed and the output data array is played back with the Matlab function audioplayer(). Example2.m has detailed comments to help explain the usage of each of these functions.

Example 3
Reading/Writing Intermediate Signals
This example shows how we can add 'extra' sink modules to a layout in order to read intermediate signals, and add 'extra' source modules to inject signals into the layout. In this example we read the intermediate signal WhiteNoiseFiltered from an 'extra' sink module. We then process WhiteNoiseFiltered with Matlab: time reversing it and taking the logarithm of its absolute value. We then inject this processed data into the layout's signal flow by writing it to the 'extra' source module: ML_Processed_Data. We then plot WhiteNoiseFiltered and our output data.
Note: We must be aware that the injected data is not processed by the layout until after the next execution of the process function.
The example consists of 2 files:

• Example3.awd
• Example3.m

These files may be downloaded here:
Example 3

Configuring Audio Weaver

• Configuring Module Paths
  Audio Weaver Designer has an internal module search path which tells AWE Designer where to find module libraries. AWE Designer ships with a standard set of module libraries and the module search path set to include these. If you need to use other module libraries, (like a custom module library you created), then you must modify the module search path to include the desired library. This can be done from the AWE Designer GUI using the "File → Set Module Path" menu option. We can also do the same thing from a Matlab script using the Matlab Automation API function: add_module_path().
  It is important to understand that simply modifying your standard MATLAB path is not sufficient; you must add the base module directory to the Audio Weaver module search path using add_module_path(). Both AWE Server and AWE Designer must be running when we run add_module_path(). After running add_module_path(), AWE Designer must be restarted for the changes to be reflected in the AWE Designer module browser.
  Syntax:
  1.)PATH = add_module_path(DIR);
  Where DIR is the full pathname of the directory where the custom modules reside. e.g. DIR = 'C:\My_Repos\MyCustomModules'. This adds DIR to the end of the module search path. The return value PATH is a cell array containing each directory on the module search path.
  2.)PATH = add_module_path(DIR, '-end'); or PATH = add_module_path(DIR, '-begin');
  This adds DIR to the end or the beginning of the module search path. (If no argument is specified for the 2nd field then the default is '-end')
  3.)PATH = add_module_path(DIR, '-end',1); or PATH = add_module_path(DIR, '-begin',1);
  This removes DIR from the module search path

• Switching AWE Designer Versions
  Audio Weaver supports multiple simultaneous installations. Each version will be installed in a separate directory. We can select which version of Audio Weaver to use by taking the following steps:

  1. Launch Matlab

  2. From the Matlab command line enter:

     1. clear all
        -Removes all variables, functions, and MEX-files from the workspace and memory. Ensures no leftover variables or compiled code from the previous Audio Weaver version remain in memory, which could interfere with the new version.
     2. clear classes
        -Clears persistent class definitions, especially from .m and .p class files that have already been loaded. MATLAB caches class definitions after loading them. If two versions of Audio Weaver define the same class differently, MATLAB could continue using the outdated version unless this cache is cleared.
     3. restoredefaultpath -Resets MATLAB's path to factory default, removing any previously added folders (including old Audio Weaver paths). Prevents conflicts between versions by ensuring no lingering paths from the previous installation are still on MATLAB’s search path.
     4. addpath(DIR)
        -DIR is the full pathname of the matlab folder in the desired Audio Weaver installation
        -Adds the path to the desired version of Audio Weaver's MATLAB integration code. Ensures MATLAB uses the functions, class definitions, and scripts associated with the new Audio Weaver version you want to run.
     5. which awe_designer
        -Observe that Matlab reports the path to the desired version of Audio Weaver
     6. awe_designer
        -Launch the desired version of Audio Weaver

• Debug/Release Module Status
  Often we want to have extra modules in our layouts which are used solely for development and debugging like Meter or Sink modules to visualize signal activity. We may not want these modules to be included in the final deployed product release build. Audio Weaver has a mechanism to control this on a module by module basis. There are 2 components to this mechanism:
  1.)The Build Configuration for the layout. This can be set to either Release or Debug from the AWE Designer GUI using Layout --> Layout Properties --> Build Configuration.
  2.)Each module on the layout can be set to a Debug Status of either Debug or Release. This can be set with the AWE Designer GUI by right clicking a module --> Debug Status. When the layout Build Configuration is set to Debug then all layout modules are included in the final build. When the layout Build Configuration is set to Release then only the modules with Debug Status of Release will be included in the final build. When modules are excluded from the final build they are also excluded from any generated target files, (.AWB, .AWS, etc.)
  Setting Build Configuration and Debug Status Programmatically
  First we need the GSYS.SYS structure, and the AWE_INFO structure:
  GSYS = load_awd('XXX.awd');
  S = GSYS.SYS;
  global AWE_INFO;
  We can set the Build Configuration using AWE_INFO.buildControl.buildConfiguration:
  AWE_INFO.buildControl.buildConfiguration = 'Release';
  or
  AWE_INFO.buildControl.buildConfiguration = 'Debug';
  We can set the Debug Status of any module by setting the module's isDebug field to 1 for Debug, and 0 for Release:
  S.moduleName.isDebug = 1;
  e.g.:
  S.Mute1.isDebug = 1;

Profiling

Audio Weaver allows profiling of a layout for MIPS and Memory consumption. Profiling can be done from the AWE Designer GUI using Tools --> Profile Running Layout. We can also do profiling from a Matlab script.

One profiling option from AWE Designer is:
Tools --> Profile Running Layout --> Profile Block by Block.
We can do the same thing if Example.awd is already open and running in Designer with the Matlab code:

Example.awd must be open in Designer and running on a target, (PC or embedded target)
GSYS = get_gsys('Example.awd');
diary profiling.txt
target_profile(GSYS.SYS);
diary off

This will create a file “profiling.txt” in the current MATLAB folder. If you simply want to display the profiling result on the MATLAB console, you can omit the two “diary” commands.

Profiling Over Long Periods of Time
We may want to repeatedly profile over very long periods of time, (hours/days). This can give us a view into system performance changes over long periods of time. Sample Matlab script to do this:
% Example.awd must be open in Designer and running on a target, (PC or embedded target)
GSYS = get_gsys('Example.awd');
diary profiling.txt
for ctr = 1:numProfiles
pause(numSeconds);
target_profile(GSYS.SYS);
end
diary off

profiling.txt will contain the concatenation of the individual profiles. This file can be parsed and used to study system performance over time.

Processing File Quickly -- Faster than real time

Audio Weaver allows us to process one or more .wav or .mp3 files through an Audio Weaver layout much faster than real time. This can be done from the AWE Designer GUI using Tools --> Process Files. We can also do this with a Matlab script:

% Audio Weaver Server must be running. Audio Weaver Designer does not need to be running.
tic
% Name of Audio Weaver layout to be controlled
fNameAWD = 'ProcessFilesTester.awd';
% Names of audio input and output files.
% We must specify full absolute path names!
WAVIN = 'C:\Users\rhutc\OneDrive\Desktop\DSPC\AWE_Doc_2025\MatlabAutomationAPI\ProcessFilesTest\Bach Piano 48kHz.mp3';
WAVOUT = 'C:\Users\rhutc\OneDrive\Desktop\DSPC\AWE_Doc_2025\MatlabAutomationAPI\ProcessFilesTest\OUT.wav';
% Get the GSYS structure for the AWE layout
GSYS = load_awd(fNameAWD);
S = GSYS.SYS;
[OUT, SUCCESS] = process_file(S, WAVIN, WAVOUT);
toc

We can also process a batch of .mp3/.wav files faster than real time with a Matlab script which performs the above code in a loop. The Matlab files for the single file example above and for batch processing can be found here:
Fast File Processing Matlab Scripts

Build Automation

Continuous Integration / Regression Testing
Continuous Integration (CI) is a software development practice where developers frequently integrate their code changes into a shared repository. Each integration triggers automated regression tests allowing teams to detect issues early and fix them quickly.
Audio Weaver users can use the Matlab Automation API to create Matlab scripts as part of an automated integration and testing work flow. The Matlab scripts can be used to verify that changes to AWE layouts by one or more engineers do not degrade the layouts' performance. For regression testing it is assumed that:

• You have developed a set of test vectors to evaluate layout performance
• You have developed metrics to verify accepable performance

You can use the methods described in the Controlling an Audio Weaver Layout section above to create Matlab scripts to:

• Drive your layout(s) with each of your test vectors
• Read layouts' output for each test vector
• Analyze layout output to see that acceptance metrics are met

These Matlab scripts can be used as a part of a team's implementaion of a continuous integration and automated build workflow.

Assigning Module Object IDs
Module Object IDs in Audio Weaver are unique integer identifiers assigned to modules, wires, and layouts within your Audio Weaver design. Object IDs act as addresses or handles that the Audio Weaver Server (running on your PC) and your custom control code on the target processor use to identify and interact with specific module instances. They allow you to send tuning commands to a running layout on the target without requiring direct interaction with MATLAB or AWE Designer. By default, Object IDs are automatically assigned when an Audio Weaver system is built. However the automatically assigned object IDs will change each time the layout is modified and rebuilt. This can break the embedded target control code. The solution is to assign custom Object IDs for any modules you to control at runtime. These custom IDs are in the range of 30000 to 32767. If a custom object ID is assigned, it will overwrite the automatically generated value during the build process. Custom Object IDs will not change when we rebuild or modify and AWE layout. This allows control code to reliably reference modules on a target.
We can set Object IDs using AWE Designer by setting the objectID field under the module properties build tab. We can also set Object IDs from a Matlab script:
GSYS = load_awd("FILE.awd");
S = GSYS.SYS;
S.MODULE_NAME.objectID = IDNUM;     % IDNUM is in the range 30000 to 32767.
Assigning custom Object IDs is important to understand when generating target files, as explained below.

Note: we can also use a Matlab script to recursively traverse an entire layout, (as described in the Signal Flow Automation section below), and assign Object IDs selectively. e.g. assign Object IDs to all Scaler modules and all AEC modules.

Generating Target Files
Audio Weaver Designer enables the user to create various files that can be deployed to or used by the target processor. This feature is accessed in Designer with:
Tools ---> Generate Target Files.
Generate Target Files gives us a popup window allowing generation of 7 types of files plus some control options. We first summarize the file types and control options, then we show how to implement this functionality with a Matlab script.
Target File Types
1.)Audio Weaver Script, (.aws)

• Contains all information of an AWE layout, (.awd file)
• Human readable format
• Contains valid commands which AWE Server understands and can execute
• Commands include information about the modules used, connections between them, and parameter settings

2.)Audio Weaver Binary, (.awb)

• Contains all information of an AWE layout, (.awd file)
• Compiled version of a .aws file
• Not human readable
• Easier for an embedded target's firmware to decode than .aws
• Most commonly used in production on embedded targets

3.)Tuning Symbol File, (.tsf)

• Contains the symbols needed when connecting to a running target
• Essential for using Tools --> Attach to Running Target in AWE Designer
• .tsf file allows Designer to connect to the layout running on the target and manipulate it as if you had loaded that layout directly via Designer

4.)ControlInterface.h

• Provides symbolic information which allows external code to interact with and control an AWE layout running on a target processor
• C/C++ header format with #define's for all relevant symbols
• Allows reading/writing of module variables and properties
• Works with standalone external code running on the target device, (AWE Designer/AWE Server not needed)
• 2 files are generated: _ControlInterface.h and _ControlInterface_AWE6.h. _ControlInterface_AWE6.h. is for legacy compatibility with the AWE 6 product line. The AWE 6 product line was in use for almost four years before being replaced by AWE 8.

5.)initAWB.c,h Files

• Produces 2 files: XXX_initAWB.c and XXX_initAWB.h
• These files contain all the information of the entire Audio Weaver Binary (.AWB) representation of your layout, structured as an initialized C array
• XXX_initAWB.c and XXX_initAWB.h can be directly integrated and compiled into targtet firmware
• Enables standalone loading of an AWE layout onto embedded processors which do not have a file system.

6.)ModuleList.h

• ModuleList.h is a C/C++ header file containing a list of all modules used in a layout
• Includes only modules necessary for the layout to run. Excludes unused modules and modules with Debug Status = 'Debug'
• Specifies which modules must be included in the final target firmware to support a given .awb file
• Allows a Board Support Package (BSP) author to build an AWE Core target with only the minimum set of modules required.
• Enables optimization of memory usage by excluding unnecessary modules
• In the case of multiple AWE instances a ModuleList.h file is produced for each instance detailing the modules needed for that instance

7.)HeapSize.h

• Audio Weaver manages its own set of 3 or 4 internal memory heaps (FAST, FASTB, SLOW, SHARED)
• HeapSize.h specifies the minimum sizes of each heap required for the AWE layout
• In the case of multiple AWE instances a HeapSize.h file is produced for each instance detailing minimum heap sizes needed for that instance
• Helps BSP developers allocate the appropriate amount of memory for the AWE Core's heaps. Helps to trim the heap sizes defined in the BSP if they are larger than needed

Target Files and Custom Object IDs
You should assign a Custom Object ID to a module in an AWE layout if you intend to control that module at run-time in your deployed product. Custom IDs will then be included in the target files:

• .aws
• .awb
• .tsf
• initAWB.c,h
• ControlInterface.h --> ONLY modules with Custom Object IDs will be included in this file. Thus for using this file, it is mandatory to assign Custom Object IDs to all modules you want to interact with on the layout

Enable Audio Checkbox

• When checked, (which is the default) this appends an audio_pump command to your generated .awb (Audio Weaver Binary) and .aws (Audio Weaver Script) files. The appended audio_pump command will initiate audio processing upon loading.
• When unchecked no audio_pump command is appended and upon loading audio processing will not begin until a manual audio_pump command is issued. This could be controlled by a specific event like a button push. The BSP must provide a mechanism to allow starting the audio pump after loading.

Split multi-layout Checkbox

• Unchecked is the default
• Designed to work with multi-instance layouts
• When checked separate .awb files will be generated for each instance in a multi-instance layout
• Max Num Parts field gives control over what instances will be in their own .awb We get a seperate .awb generated for each instance up to Max Num Parts, and any additional instances are included in the last .awb. So if we have 4 instances, (indexed 0-3), and we set MaxNumParts to 2 then we get 2 .awb's generated. The first .awb contains instance 0 and the the 2nd .awb contains instances 1,2,3. Likewise if we have 4 instances and set Max Num Parts to 3 we will get instance 0 in the first .awb, instance 1 in the next .awb and instances 2,3 in the last .awb. This allows control over which instances can be loaded to distinct cores on an embedded target.
• Supports progresive loading

Create Lookup Table Command Checkbox

• New Feature added in Designer version 8.D.2.5
• Unchecked is the default
• When checked sets AWE_INFO.buildControl.createLookup to 1
• When checked adds a create_lookup command to the generated .aws (Audio Weaver Script) and .awb (Audio Weaver Binary) files
• Allows inclusion of a lookup table in the generated .awb and .aws files to improve the efficiency of ID lookups on the target hardware

Generating Target Files via Matlab Scripts
The Matlab Automation API function generate_target_files() allows us to generate all target files described above programatically from Matlab.
First lets look at the function prototype for generate_target_files()

function generate_target_files(GSYS, baseName, saveDir, sArrayName, nCoreID, calledFromGUI)
% Generate target files based on the GSYS props options selected
%
% Inputs:
% GSYS - Global System object for the loaded layout
% GSYS.props.generateAWSCompileWindow - generate AWS file
% GSYS.props.generateTargetInfo - generate a modulelist.h file
% GSYS.props.generateHeapUsed - generate heapSize.h file
% GSYS.props.generateAWB - generate AWB file
% GSYS.props.generateTSF - generate .tsf file
% GSYS.props.generateAwbH - generate initAWB.c,h array files
% GSYS.props.generateEval - encrypt AWB file
%
% baseName - base name for generated files
% saveDir - directory for saved files
% sArrayName - C array base name - (optional) default is baseName
% nCoreID - multi-canvas core ID - (optional) default is 0
% calledFromGUI - (optional) set to true if called from Designer GUI
% default is false

Notes:
1.)The _ControlInterface.h files are always generated even if all the above GSYS.props fields are set to zero.
2.)generate_target_files() allows encryption of the .awb file by setting GSYS.props.generateEval = 1

Below is Matlab code to illustrate the use of this function

% Name of Audio Weaver layout to be controlled
fNameAWD = 'TargetFilesTest.awd';

% Set values for all function arguments
baseName = 'TT';
saveDir = 'C:\Users\rhutc\OneDrive\Desktop\DSPC\AWE_Doc_2025\MatlabAutomationAPI\TargetFiles';
sArrayName = 'TTC';
nCoreID = 0;
calledFromGUI = 0;

% Get the GSYS structure for the AWE layout
GSYS = load_awd(fNameAWD);

% Declare global AWE_INFO after gettting GSYS
global AWE_INFO;

% Set GSYS.props fields to select files to be generated
GSYS.props.generateAWSCompileWindow = 1;     % generate .aws file
GSYS.props.generateTargetInfo = 0;     % generate a modulelist.h file
GSYS.props.generateHeapUsed = 0;     % generate heapSize.h file
GSYS.props.generateAWB = 0;     % generate .awb file
GSYS.props.generateTSF = 0;     % generate .tsf file
GSYS.props.generateAwbH = 0;     % generate initAWB.c, h array files
GSYS.props.generateEval = 0;     % encrypt .awb file

% Set values for control check boxes
%
% Enable Audio Check Box
GSYS.props.enableAudioPump = 1;
%
% Split multi-layout Checkbox
GSYS.props.generateNumParts = 4;
GSYS.props.generateSplitAWB = 0;
%
% Create Lookup Table Command Checkbox
AWE_INFO.buildControl.createLookup = 0;

% Function call to generate the files
generate_target_files(GSYS, baseName, saveDir, sArrayName, nCoreID, calledFromGUI);

Signal Flow Automation

The Matlab Automation API can be used to automatically traverse an AWE layout and read/write information from/to any desired layout modules. We can automatically do a full traversal of a layout including processing of all layers of subsytems. This approach is most useful for larger layouts with many levels of subsystems and modules. e.g.:

• We have profiled the layout and we see excessive MIPS consumption for AEC modules, we could create a Matlab script to reduce the number of taps for all AEC modules
• We have a lot of meter modules on our layout which are not needed except for debug purposes. We can write a script to set all meter modules to inactive runtime status.
• We can write a script to collect and analyze the values of any set of module variables.

Two Matlab functions, a simple layout, and a script showing how to use the Matlab functions are provided to demonstrate the basics:

• displayLayout.m
  This function recursively traverses an AWE layout. It prints out entry and exit of each subsystem, and each module's class name, name, and full hierarchy name are printed.
• traverseModify.m
  This function recursively traverses an AWE layout. It prints out entry and exit of each subsystem, and each module's full hierarchy name is printed. This function can be customized to perform specific modifications to any module on the layout by adding code to the 'Modify' section. Several examples are provided in the 'Modify' section.
• SignalFlowAutomation.m
  This script shows an example of using displayLayout() and traverseModify().
• SFAuto_Example.awd
  These files can be downloaded here:
  Signal Flow Automation Basics

Audio Weaver designs can run on a target with multiple processor cores. Different modules and subsystems can be set to run on different cores. The Matlab Automation API allows us to parse a mult-core layout and read/write information from/to any desired layout modules on any of the cores. A Matlab script and an AWE layout are provided to illustrate this.

• Change_Module_by_Core.m
  This script traverses the NordyADP_Test_Example.awd layout and changes the runtime status to a user selectable value for all modules on a user selected core. This script can be used as a template and modified to read/write any desired modules filtering by core ID.
• NordyADP_Test_Example.awd
  These files can be downloaded here:
  Parsing a Multi-Core Layout

Assigning Module Object IDs
We can use the traverseModify.m function to recursively traverse a layout and assign Object IDs in a selective manner. e.g. assign Object IDs to all Scaler modules and all AEC modules. See the Assigning Module Object IDs topic in the Build Automation section above.

Identifying class names
When we pick out all modules of a class we use a line like:
if strcmp(S.className,'ScalerV2')
where ScalerV2 is the module's class name. We must use the correct string for the class name. Its important to note that the AWE Designer module browser does not list the exact string needed for class name, and sometimes the module browser listing is very different from the actual class name. e.g. The module browser lists 'General Purpose Scaler' for the module with class name 'ScalerV2'. We can find the correct class name in 2 ways:
1.)Read it off the AWE Designer canvas. The class name is specified under each module in square brackets. e.g. '[ScalerV2]'
2.)Run the displayLayout() function and read the output

Saving changes
We usually start by getting the GSYS structure for the layout with the load_awd() command. e.g. GSYS = load_awd('XXX.awd); When we traverse a layout and make changes, if we want the changes to be saved we must explicitly save the layout with the save_awd() command e.g. save_awd('XXX.awd', GSYS);

Power Debugging

Debugging with the process() function
We can use the Matlab Automation API to drive a data set through a layout one block at a time and examine layout behavior block by block. This can be very valuable for debugging. For this approach we use the Matlab API function calls show in Example 2 above. We can also set Matlab breakpoints and examine the state of the system right when the trouble begins. e.g. if we see our output becoming unstable we can test each block to see the output value and if it crosses a certain threshold then we can stop at a breakpoint. Then we can examine system state by hand at the Matlab command line or run a special hand written Matlab function to examine the system state and do some analysis, plotting etc. to give us clues about the problem.
This idea is illustrated with the code snippet:

for blkCtr=1:numBlocks
    % Set up this block of data
    % x = DataIn_fract32(StartIdx:StopIdx,:);
    x = DataIn(StartIdx:StopIdx,:);
    WIRE_IN={x};
    % Process one block of data
    [S, WIRE_OUT]=process(S, WIRE_IN, 1);
    DataInAWE(StartIdx:StopIdx,:) = S.Data_In_AWE.value;
    DataOut(StartIdx:StopIdx,:) = WIRE_OUT{1};
    if(max(abs(DataOut)) > ErrorThreshold)
      ErrorAnalysisProcessing(); % Set breakpoint here. Analyze layout to find cause of problem
    end
    % Increment StartIdx, StopIdx
    StartIdx = StartIdx + blockSize;
    StopIdx = StopIdx + blockSize;
end

Debugging with a running layout

• For this approach we use the Matlab API function calls shown in Example 1 above.
• We run our layout live on the target
• Modify layout variables via Matlab script commands and observe the results with layout inspectors
• Read layout data and module variables into Matlab and process/analyze/plot the information
• Matlab commands will not be synchronized with layout's data pumping

Using Hidden Variables
Some module variables are not normally visible in the Designer GUI, and are not normally accessible via Matlab scripts. When we set AWE_INFO.displayControl.showHidden to 1 these become visible in Designer GUI and accessible via Matlab scripts. Hidden variables can include module state variables and derived variables. These are often not needed in normal operation, but accessing them can become important for debugging. The syntax is: AWE_INFO.displayControl.showHidden=1; We can now view all these variables and examine them for values which are too big, too small or assume values of Inf or NaN.

Debugging Inf/NaN values
Inf and NaN values can enter a signal flow for various reasons including:

• Divide by zero
• Overflow in floating point math
• Invalid arguments to logarithmic or power functions
• Parameter corruption or range violations
• Uninitialized or corrupted memory
• Incorrect fixed point to floating point conversion

• etc.
  Once a value of Inf or NaN enters the signal flow it can propagate and infect the entire signal path since the result of any operation with NaN or Inf is almost always NaN or Inf. Module state variables are often infected. This infection can cause audio dropouts, instability, or failures of downstream processing. This can be difficult to debug because the symptom may show up long after the original entry of NaN/Inf into the signal flow.

• If the problem can be reproduced consistently, then we can use the techniques described in the Signal Flow Automation section above to recursively traverse the layout and examine state variables of all modules. This can show us when we have values of NaN/Inf.

• A refinement of this is to pump data thorough the layout one block at a time, and each block traverse the layout and examine values of all state variables, then log the occurrences of NaN/Inf. Our Matlab script can break at the first block where these values occur. This approach can help isolate the origin of the NaN/Inf values.
  We have created 2 Matlab scripts to help with this:
  1.)find_NaN_Inf.m
  function Report = find_NaN_Inf(S, Report)
  Traverses a layout specified by GSYS.SYS and produces a report detailing all occurrences of NaN/Inf and all occurrences of numbers with magnitude > 1e32. Very large magnitude numbers could be normal but they could also indicate the start of problems.
  Report is an Nx4 cell array. Where N is the number of module variables containing NaN or Inf values. Each row of the report has the 4 fields:
  {Full hierarchy name of the module}
  {Variable name}
  {Inf or NaN or BigMag}
  {Indices of the variable which contain NaN/Inf/BigMag}
  (If the variable is a multidimensional array then we get the linearized indices. i.e. if the variable is A(10,7,3) then we first linearize: ALin = A(:) then find indices of elements of ALin containing NaN/Inf).
  2.)PDTest1.m
  Loads and analyzes a moderate complexity layout, (test_gcc_v7_functional.awd). The script pumps data in one block at a time and each block runs find_NaN_Inf(). We wait until a selected block and introduce some NaN and BigMag values. We than verify that these values are reported correctly.
  All files for this can be found here:
  Block by Block Layout Traversal Search for NaN/Inf

Debugging with AWS messages and AWB packets
This area is quite complex and detailed. Below we give an overview and introduction to it. More complete documentation can be found at:
Audio Weaver Tuning Command Syntax
AWE Core 8.D.10 Documentation
AWE Core 8.D.12 Documentation

Audio Weaver Script (.aws) and Audio Weaver Binary (.awb)
An Audio Weaver layout, (.awd file), can be fully represented with Audio Weaver Script, (AWS/.aws file). A .aws file is human readable and consists of the commands to configure and control an Audio Weaver system. These are the commands sent from Matlab to the AWE Server, or from AWE Designer to the AWE Server. Note that in native mode AWE Server also functions as the target. i.e. in native mode AWE Server simulates a PC target. When we are connected to an embedded target the .aws commands are first translated into binary message packets, referred to as Audio Weaver Binary (AWB/.awb file). These binary packets are then sent to the embedded target processor. The binary format is much easier for the embedded target to decode than the .aws format.
AWS includes commands to add modules, make connections between modules, set module parameters, etc. Building and running an AWE layout generates the AWS commands used for building/running. Examining AWS and AWB can be valuable for debugging.

There are several different ways we can get AWS and AWB information.

MatlabLog and PacketLog
AWE Designer GUI allows us to produce log files containing AWS and AWB commands. This feature can be turned on by editing the .INI file directly with AWE Server: Help --> Open INI file and set MatlabLog = 1, and/or PacketLog = 1. In later versions of Audio Weaver these can be set with the AWE Server GUI without editing the INI file: File --> Preferences brings up a window with a Logging Section and the checkboxes Packet Log and Matlab can be checked. This will produce output files in the C:\DSP .\Bin\win32-vc142-rel\logs folder of the Audio Weaver installation: packet.txt and/or matlab_command.txt.
packet.txt contains the binary message packets, (AWB commands), sent to the target and contains the binary message packets representing the target's responses. matlab_command.txt contains the same information as packet.txt, (commands sent to target, and target responses ) in human readable AWS form. Additionally matlab_command.txt contains some extra 'book keeping' information which flows between the AWE Server and Matlab/AWE Designer but never actually goes to the embedded target. The extra information includes e.g. connect,localhost, check_license, etc.
When this feature is turned on, these files are produced automatically upon running a layout from AWE Designer.

Generating .aws and .awb Files with Generate Target Files Feature
We can generate the .aws and .awb files representing a layout directly using either the AWE Designer GUI, (Tools --> Generate Target Files), or with a Matlab script. This is described in detail in the Build Automation --> Generating Target Files section of this document:
Generating Target Files
The .aws file contains the commands sent from AWE Server to the target. The .aws file contains none of the extra 'book keeping' information found in the MatlabLog file: matlab_command.txt. Likewise the .awb file contains the binary packet representation of the .aws file, (ONLY the information actually set to the target.) The .aws file contains exactly the same information as the PacketLog file: packet.txt.

Debugging with AWS Information

awe_diary() VS AWE_INFO.buildControl.echoCommands=1
We can examine the .aws information with both the The Matlab Automation API function awe_diary() and by setting AWE_INFO.buildControl.echoCommands=1. These have similar but distinct functions with pros and cons.
awe_diary()
The Matlab Automation API function awe_diary() can be used to log the commands sent from Matlab to the AWE Server, or from AWE Designer to the AWE Server, (.aws ), to a file. It can also be used to play back the .aws commands contained in a previously logged file. awe_diary() logs ONLY the commands used to set up the layout, nothing else.
Example code for using awe_diary:
% Log the .aws commands for building to file
fNameAWD = 'LoggingTester.awd';
% Load the Audio Weaver layout
GSYS = load_awd(fNameAWD);
S = GSYS.SYS;
awe_diary('on', 'AWEDiary_LT.aws');
S = build(S);
awe_diary('off');

% Play back the .aws commands from AWEDiary_LT.aws
% Sends the messages contained in FILENAME to the Audio Weaver Server, one message at
% a time.
awe_diary('play', 'AWEDiary_LT.aws');
This accomplishes the same thing as using the AWE Server GUI: File --> Execute Script --> select AWEDiary_LT.aws
You can also playback .aws diary files directly from Windows Explorer. The .aws extension is associated with the Audio Weaver Server. Simply double-click an .aws file to execute it.

We can also append .aws to an existing file:
awe_diary('on', FILENAME, APPEND);
Allows an optional APPEND argument (Boolean). If APPEND=1, commands are appended to the file; if APPEND=0 (default), the file is first deleted.

By default, the diary file is written in the current MATLAB working directory. You can specify an alternate directory by setting the global variable AWE_INFO.diaryControl.outputDirectory. e.g.:
global AWE_INFO;
AWE_INFO.diaryControl.outputDirectory='c:\myfiles\scripts';

AWE_INFO.buildControl.echoCommands=1
When we set AWE_INFO.buildControl.echoCommands to 1 it causes the following information to be sent to the MATLAB output window:
1.)Commands sent from Matlab to the AWE Server, or from AWE Designer to the AWE Server, (same information as is recorded by awe_diary()) 2.)Additional commands sent to AWE Server which are not recorded by awe_diary(). These are commands which are not related to setting up the layout, e.g. flush, get_heap_size, etc.
3.)All responses sent from the target after receiving its commmands. NOTE: In native mode AWE Server is the target. i.e. AWE Server simulates a PC target.

Example Code for Using AWE_INFO.buildControl.echoCommands=1
1.)Display AWS commands in Matlab command window:
fNameAWD = 'Example.awd';
GSYS = load_awd(fNameAWD);
S = GSYS.SYS;
global AWE_INFO;
AWE_INFO.buildControl.echoCommands=1;
build(S);
2.)Log AWS commands to a file:
% Note we use Matlab's diary function to log Matlab console output, (not the same as awe_diary()!)
fNameAWD = 'Example.awd';
GSYS = load_awd(fNameAWD);
S = GSYS.SYS;
global AWE_INFO;
AWE_INFO.buildControl.echoCommands=1;
diary AWSCommands.txt;
build(S);
diary off;

Differences between awe_diary() and AWE_INFO.buildControl.echoCommands=1
1.)Destination: awe_diary() records informattion to a file and AWE_INFO.buildControl.echoCommands=1 causes information to be sent to the Matlab output window.
2.)Content: awe_diary() records only a subset of commands sent to AWE Server, AWE_INFO.buildControl.echoCommands=1 sends a more complete set of commands sent to AWE Server + target's responses to these commands.

When to use awe_diary() VS AWE_INFO.buildControl.echoCommands=1
awe_diary() is used when we want to isolate the commands used for creating a layout: creating modules, adding wires etc. This is gives us the same information as generating a .aws file from a layout using AWE Designer GUI Tools --> Generate Target Files. One important usage of this is for creating preset files which can be used to dynamically tune a running embedded target. See the Presets section below.
AWE_INFO.buildControl.echoCommands=1 can be used to observe if a command sent to the target fails and is useful for debugging communication between Matlab/AWE Designer and the tartet.

Debugging Using awe_diary() and AWE_INFO.buildControl.echoCommands=1
Complete documentation of AWS commands can be found here:
Audio Weaver Tuning Command Syntax

Some useful debugging AWS commands are:

1.)create_module
2.)write_float_array
3.)write_int_array
4.)add_module
5.)audio_pump

Studying the AWS commands for a layout can help debug build failures. We can observe the create_module command and see if we have the correct number of wires, and correct variable initializations. We can observe if create_module fails, or an array write fails, or audio_pump fails. This gives clues as to the source of the problems: module's constructor is broken, set function has incorrect logic, issues with the processing function. If we get an error regarding the number of module arguments, we can count the number of arguments passed to create_module and determine if the matlab code is wrong, DLL is wrong, or the on target library is wrong.

This is especially useful when debugging custom modules. See the Cutom Module Developer's Guide for more detailed info on this: Audio Weaver Custom Module Developer's Guide

We can also use the AWS commands to debug when we have no custom modules. This can be valuable for both native and embedded targets. We can observe the AWS commands as a layout is loaded and this will tell us if we have exceeded available memory. Similarly in the case where we have a multi-instance layout which has more instances than are available on the target then observing the AWS commands while loading the layout will reveal the problem.

Debugging with AWB Information AWS and AWB contain the same information and both can be used to debug AWE systems. It is always easier to use AWS since it is human readable. However there are some situations where AWS information is not available and we must work directly with AWG information.
1.)Often on an embedded target the layout and tuning and control information will be loaded exclusively with AWB information.
2.)Often an embedded target's tuning interface/control interface will use only AWB information. Often embedded control/tuning code runs on one embedded processor, (e.g. an ARM core), and writes tuning control info to another embedded processor which does the audio processing, (e.g. a SHARC). In these cases the communication is virtually always via AWB packets.
When we are debugging these kinds of systems then we must work with AWB data. We have no choice but to examine the bits and bytes to debug crashes and other incorrect behavior. Here we are dependent upon some kind of 'sniffer' which can access the AWB packets for us to view.

Debugging Crashes
If we are working with an AWE Layout which crashes when run, (either on an embedded target or in native mode), and we are able to load and run via our PC, then we can debug this using the MatlabLog and PacketLog features of AWE Designer. Studying these log files can lead to clues about what is causing the crash.

Doing a diff of 2 versions of a layout
Suppose you have a layout which is working fine, but then after some changes it has problems. You may not know exactly which changes were made.
Observing the differences between the old working layout and the new non-working layout can help with debugging. 2 possible approaches to doing this:
1.)Using the Matlab Automation API function awe_diff_systems
In your AWE Designer installation you must first set File --> Global Preferences --> Diff --> Tool Path to the full path name of your diff tool. We recommend Winmerge for this.
Now you can use the Matlab code below to get a diff report.
SYS1 = 'SYS1.awd';
SYS2 = 'SYS2.awd';
GSYS1 = load_awd(SYS1);
S1 = GSYS1.SYS;
GSYS2 = load_awd(SYS2);
S2 = GSYS2.SYS;
awe_diff_systems(S1, S2);
This pops up a Winmerge window showing the differences between S1 and S2. The format shown is of the GSYS.SYS structures, (S1 and S2), unpacked module by module and variable by variable.
Note:
We can do the same operation using AWE Designer GUI
1.)Set File --> Global Preferences --> Diff --> Tool Path to the full path name of your diff tool
2.)Tools --> Compare Layouts --> Fill in popup window with full path names of the 2 .awd's to be compared --> Compare Systems

2.)Comparing .aws files for your layouts
You can generate .aws files for both layouts as described in Build Automation --> Generating Target Files Section Then you can examine the differences using a diff tool like Winmerge. Depending on the details of your debugging, it may be advantageous to look at .aws versions of the layouts being compared.

Debugging Custom Modules
In the case where you have created custom modules or custom Matlab subsystems then you can debug these with Matlab scripting by placing breakpoints in the Matlab code components: constructor, prebuild, set functions etc. See the Module Developer's Guide for more details on this.

Presets

This section gives a basic overview of presets and presents techniques to manage presets using the Matlab Automation API. More detailed information on presets and Audio Weaver can be found in the 'Presets in Audio Weaver' App Note:
Presets in Audio Weaver App Note

In the most general terms a 'Preset' is a group of settings of module variable values in an AWE layout. Different presets can be used to create different 'tunings' or 'modes' of a layout. Automotive and home entertainment audio systems are two common real world examples of audio preset usage.

• Home Entertainment Audio System Presets/Modes:

  • Standard
  • Cinema
  • Sports
  • News

  For each mode the audio system, (AWE layout), will have module variables set to produce a listening experience optimized for that mode. e.g. for Cinema mode, module variables will be set to create or simulate surround sound, enhance dialog, make full dynamic range from whispers to explosions audible... etc.

• Automotive Audio System Presets/Modes:

  • Driver Only
  • RideShare
  • Podcast
  • Karaoke

  For each mode the audio system, (AWE layout), will have module variables set to produce a listening experience optimized for that mode. e.g. for Driver Only mode, module variables will be set to deliver high-quality sound only to the driver, reducing power usage and minimizing distraction for others.

Two common ways to use The Matlab Automation API to manage presets:

• Use a Matlab script to set presets on a layout
  1.)Create a list of preset values for each module variable we wish to set. This list could be stored in a .csv, .txt file, .mat file etc. Create a different file for each system preset, e.g.:
    Preset_Driver_Only.mat
    Preset_RideShare.mat
    Preset_Podcast.mat
    Preset_Karaoke.mat
  According to user preference and needs, these files can contain a simple array of numerical values, or more complex structures like cell arrays.
  2.)Create a Matlab script which:

  • Reads and parses a specified preset file
    User must write Matlab code to parse the file!
    e.g. read and parse Preset_Driver_Only.mat
  • Loads the .awd for the layout to be tuned, e.g.:
    fNameAWD = 'AutomotiveAudio.awd';
    GSYS = get_gsys(fNameAWD);
    S = GSYS.SYS;
  • Assigns each entry of the preset file to the appropriate module variable
    S.module1.field1 = PresetList(1);
    S.module1.field2 = PresetList(2);
    .... etc.
    The user is responsible for hard coding the assignments correctly
  • Saves the changes to the the .awd file
    save_awd(fNameAWD, GSYS);
    Or optionally save the changes to a different .awd:
    fNameOut = 'AutomotiveAudio_Preset_Driver_Only.awd';
    save_awd(fNameOut, GSYS);

• Use a Matlab script to create a 'Parameter AWB' File
  Audio Weaver layouts can be saved as '.aws' or '.awb' files. Both formats contain all the information of a .awd file. AWS stands for Audio Weaver Script and is a human readable format. A .aws file contains valid commands that the Audio Weaver Server understands and can execute. These commands typically include information about the modules used, connections between them, and parameter setting.
  AWB stands for Audio Weaver Binary. It is a compiled binary version of the .aws file. This binary format is easier to decode on an embedded target than the human-readable .aws script. .AWB files are most commonly used in production. Typically an embedded system will have flash memory which is used to store .awb files, and a mechanism to load and execute .awb files.
  We can create one .awb which has the layout full functionality, (the structure .awb), and multiple .awb's each containing different tunings, (parameter .awb's). Then we can:
  1.)Load the structure .awb to the target
  2.)Load any desired parameter .awb to implement the desired tuning.
  The Matlab code below demonstrates how we can create .aws file with just the tuning information, (a parameter .aws file), and then compile this to a parameter .awb file.
  First we open the .awd for our main layout, (Structure.awd), in AWE Designer. We then build and run the .awd with AWE Designer and leave it running. Then we execute the code below from the Matlab script PresetTest1.m:

  % Name of Audio Weaver layout to be controlled
  fNameAWD = 'Structure.awd';
  % Get the GSYS structure for the AWE layout
  GSYS = get_gsys(fNameAWD);
  S = GSYS.SYS;
  % Make some tuning changes and save the tuning change info to preset.aws
  awe_diary('on', 'preset.aws');
  S.Scaler1.gain = 30;
  S.Scaler2.gain = 50;
  S.Scaler3.gain = 70;
  awe_diary('off');
  % Compile the .aws to a .awb
  awe_compile('FullPName\preset.aws', 'FullPName\preset.awb');

  Where FullPName is the full absolute path name to the current Matlab directory. We can now use preset.awb to load the presets on the embedded target.
  Note: we can test with AWE Designer and Server that our .awb file performs as expected:
  1.)Open Structure.awd with Designer and build and run
  2.)Open the sink displays on the layout and observe all 3 sin waves are amplitude 1
  3.)From AWE Server: File --> Execute Script --> select preset.awb
  4.)Observe that the sin wave amplitudes change to 30, 50, and 70

  The files PresetTest1.m and Structure.awd can be found here:
  Parameter .awb Example Files

Flash File System

Some hardware targets provide on-board flash memory configured to work with Audio Weaver. The flash memory stores files, usually compiled Audio Weaver Scripts, (.awb files). These .awb's may be configured to either execute on startup of the embedded system, or to be invokable after startup. Files configured to execute at startup will typically be files containing the full processing functionality, ('structure .awb's'), OR containing a set of presets to be loaded at startup, ('parameter .awb's'). Files configured to be invokable after startup will typically be 'parameter .awb's' containing alternate system tunings. Storing a .awb file configured to execute at startup allows the hardware target to operate in standalone mode, that is, without having a PC attached. The target BSP will usually have a mechanism by which a .awb file in flash can be executed after startup.
It is possible to store Audio Weaver Script, (.aws) files on a target's flash memory, however we will usually use .awb files since these are much easier for the target work with.

This section describes the Matlab Automation API functions to read/write files from/to a embedded target's flash file system. The generation of structure and parameter .awb/.aws files is described elsewhere in the document.
We can generate .awb/.aws files in 2 ways:
1.)Designer GUI: Tools --> Generate Target Files
This can also be done via Matlab Scripting, see the Generating Target Files Section above
2.)Using the Matlab Automation API function awe_diary() as described in the Presets section above

When the Server connects to a hardware target, the target reports back its capabilities and features to the Server. This information is displayed within the Server's Output Window. One of the lines shown indicates whether the target provides a Flash File System:
Is FLASH supported: Yes/No
If the target provides a Flash File System then, after connecting AWE Server to the target, we can interact with it via 4 Matlab Automation API functions:

• target_flash_dir(coreID)
  Entering target_flash_dir at the Matlab command prompt will print the flash directory information in the MATLAB command window. coreID is an optional argument to specify a core in a multi-core system. If this argument is omitted it will default to coreID of AWE_INFO.testControl.runOnCore We may obtain the flash directory information from a Matlab script using:
  L=target_flash_dir(coreID);
  This returns an array of structures, one per file, with the following fields:
  L(1).fileName - name of the file
  L(1).attrib - overall attribute byte
  L(1).isStartup - Boolean specifying whether the file should be loaded at startup.
  L(1).isCompiled - Boolean indicating that the file contains compiled
  L(1).isAWS - Boolean indicating that the file contains Audio Weaver Script.
  L(1).isPreset - Boolean indicating that the file contains compiled Audio Weaver Script with preset information.

• target_flash_add(FILENAME, ATTRIB, coreID)
  Writes a file to the flash file system on the target DSP board.
  Arguments:
  FILENAME - name of the file on the PC.
  You can specify a relative file name in which case the file is referenced relative to the AWE_Server.exe executable. Alternatively, you can specify an aboslute path. The FILENAME can be at most 24 characters.
  ATTRIB - integer bitfield specifying the file attributes of the file to be written. Each of the bits have the following meaning:
  0 - RESERVED
  1 - indicates that the file is processed at startup
  2 - indicates a data file (e.g., coefficients)
  3 - indicates a command AWS script (usually with extension .aws)
  4 - indicates a compiled AWS file (usually with extension .awb)
  5 - indicates a preset AWS script
  Generally we do not load .aws files to flash since they are harder for an embedded target to work with, requiring more MIPS/Memory which are typically limited on an embedded target. Thus although ATTRIB can take on many values, the 4 which are most commonly used are shown below and pertain to compiled .awb, (compiled .aws) files.
  24 Compiled Script file (non-bootable)
  26 Compiled Script file (bootable)
  40 Compiled Preset File (non-bootable)
  42 Compiled Preset File (bootable)
  coreID - optional argument to specify which core to run on.
  If this argument is omitted it will default to coreID of AWE_INFO.testControl.runOnCore.

• target_flash_delete(FILENAME, coreID)
  Deletes the file specified with FILENAME from the flash file system on the target, with core specified by coreID. If the coreID argument is omitted it will default to coreID of AWE_INFO.testControl.runOnCore.

• target_flash_erase(coreID)
  Completely erasses the flash memory on the specified core of the target DSP board. If the coreID argument is omitted it will default to coreID of AWE_INFO.testControl.runOnCore.

Matlab Automation API Reference

IN PROGRESS

A subset of Matlab Automation API functions along with comments and examples can be found here:
General Audio Weaver Commands

Complete list of Matlab Automation API functions can be found here:

• /matlab
• /matlab/developer
• /matlab/@awe_module
• /matlab/Designer

---

Appendix

Tables

Table Header	Table Contents
Example 1	Example Data
Example 2	Example Data