(8.D.2.5) Audio Weaver Tuning Command Syntax
- David Buzzell (Unlicensed)
- Gary Worsham
- Catherine Spain
Overview
As shown below, there are 3 main components of an Audio Weaver system that require communication in order to tune an audio system. The Designer GUI will generate text based tuning commands (AWS) based on the layout and any user tuning commands. These commands are sent to AWE Server, which in turn compiles the AWS commands into binary commands (AWB) that are sent to the target running the AWE Core. The target processes the AWB commands and then generates a reply message that is sent back to the AWE Server.
The text-based commands may also be generated by external tools and scripts rather than by AWE Designer. Example scripts, written in Python and MATLAB, are shown below. These scripts connect to the AWE Server at TCP port 15007 (to bypass port 15001, which AWE Designer GUI uses) and reads and writes the ScalerDBControl module’s currentGain variable in an active layout in real-time. The remainder of this document describes the full set of tuning commands and arguments.
The AWD which works with these scripts is attached below. Load this AWD into Audio Weaver, then build and run the layout. Finally, run the script.
Python 2.7 and 3.11
import socket
import time
TCP_IP = 'localhost'
TCP_PORT = 15007
BUFFER_SIZE = 1024
# Open a TCP socket to AWE Server
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((TCP_IP, TCP_PORT))
# Read the value of the scaler's gain
s.send(b'get_value,Scaler1.currentGain\n')
data = s.recv(BUFFER_SIZE)
print (data)
# Attenuate channel 1 to 0.5
s.send(b'set_value,Scaler1.currentGain,0.5\n')
data = s.recv(BUFFER_SIZE)
print (data)The expected output is shown below.
MATLAB (tested with r2023b)
% Open a TCP socket to AWE Server
client = tcpclient('127.0.0.1', 15007, "Timeout", 1000);
% Read the value of the scaler's gain
writeline(client, 'get_value,Scaler1.currentGain');
readline(client)
% Attenuate channel 1 to 0.5
writeline(client, 'set_value,Scaler1.currentGain,0.5');
readline(client)The expected output in the MATLAB console is shown below.
INI file settings
Colors may be customized in the INI file as follows:
[InspectorColors]
TileEdge — default 180,180,180, the color the edges of meter and slider controls are drawn.
DrawSides — default 1, when set boxes are drawn around meter and slider controls using TileEdge color
InspectorFace — default 230,230,230, the color dialog faces (other than the server dialog) are drawn
DropList — default 240,240,255, the color drop list backgrounds are drawn
TextColor — default 0,0,0, the color static text controls are drawn
By default none are specified in the INI file, so the given defaults are used.
Commands
All commands are sent by TCP/IP. All commands are of the form:
[coreID,] command_key_word [, argN]
in other words, a CSV string. White space is not significant in commands unless within a string value. Any value containing commas (generally only file names) must be quoted with double quotes. Arguments may be redundantly double-quoted.
If present, the numeric coreID specifies the core for which the command is intended. Multicore systems have cores with IDs starting at zero. If no ID is specified, zero is assumed. Single core systems have only one core with ID zero. In the following sections, core IDs are not shown in command descriptions.
Multicore systems have 2 or more cores. On SMP systems (Windows and Linux) you can specify how many cores you want to use. Embedded systems have a fixed number of cores. In both cases, each core is an independent AWE instance sharing system I/O with all other cores. Up to 16 cores may be bound to an input (source) pin, and IPC pins are provided to pass data between cores.
Some commands such as destroy, audio_pump, audio_stop and so on are commands to the system (or BSP), not to any specific core/ Such commands may have a core ID prefix, but it is ignored. These commands are considered to be BSP commands, and are noted as such in the detailed description.
Commands are received on one of 6 sockets:
15001 - for Designer use
15003 - for Designer GUI use
15005 - for special use (advanced)
15007 - general purpose
15009 - general purpose
15011 - general purpose
When using command line server in a user system avoid using the first three sockets so Designer has sockets available for tuning and control. The general purpose sockets are for user use.
Commands marked below as GUI only act only in Windows AWE Server. Those commands report success and are ignored on command line versions.
The reply from all commands is either:
success [, args ...]
or
failed, reason
The command keyword is not case sensitive.
All commands may fail for reasons not to do with the command. If the target crashes, or the link goes down, you may get a reply “failed,reason explaining what failed”. Most commonly, these will be:
failed,heap allocation request too large (ran out of heap in any command)
failed,bad packet received (target probably crashed)
failed,message too long (target BSP configuration error likely)
failed,bad heap pointer (target probably crashed)
failed,CRC error (link corruption or BSP memory corruption)
failed,communications error (link corruption or BSP memory corruption)
failed,message timed out (link failed or target crashed)
failed,linked list corrupted (target memory corrupted)
Details of all possible target errors are in Errors.h. Most are specifically due to errors in the command. However, obscure cases can arise with any command that can cause any message in Errors.h. All command replies should be tested for failed and appropriate action taken. Never ignore command replies.
The commands are summarized as follows (expand to view table):
add_module
Syntax:
add_module,layout_instance_name,offset,module1, ... ,moduleN
where:
layout_instance_name – identifier for a previously allocated layout,
offset – must be an integer >= 0,
each module must be the name of a module created by create_module
This call adds the specified modules to the layout. The layout and modules must already have been allocated by previous server calls. The layout internally contains an array of module pointers. This function sets the module pointers starting at the zero-based offset within the array. Call this function multiple times to populate all modules within the layout.
On success the reply is:
success
add_symbol_id
Syntax:
add_symbol_id,name,className,ID
Adds an entry to the symbol table based on its ID within the linked list of objects. Arguments:
name - name of the object. Must be unique.
className - class name of the object. (Module class, wire class, etc.)
ID – unique ID assigned to the object at instantiation time.
If successful, an object of the specified className will be added to the symbol table. This command is typically used to attach to a running layout.
The reply is one of:
success,name=0x%08x
failed, argument count
failed, ID invalid
failed, no such class as className
failed, instance name already defined
audio_pump (BSP)
Syntax:
audio_pump [, file_name [,record=record_file] ]
If file_name is given, creates a WAV/MP3 file reader at the rate of the file, otherwise creates a sound card reader. It then creates an output device and calls the framework pump at a rate suitable to pump samples.
If there are no wires bound to input or output pins, the code directly connects the input to the output, making a simple player. This capability is for testing.
If the second argument starts with 'record=' then a file is specified to capture output. This file will be a WAV file with as many channels as the output and at the same rate. Warning: this file will grow without bound and should be used only for limited test purposes.
If the layout specified rate does not match the rates supported in hardware, the nearest supported rate is used.
The reply is one of:
Success, sample rate
failed, open sound card for input returned an error
failed, player create returned 0x%08x
failed, renderer create returned 0x%08x
where the value is the error code from the sound subsystem.
If the server is connected to a target, the file_name argument is not permitted. If the file is not found as specified, and does not have an absolute path, it is searched for in the audio path. See set_path.
audio_stop (BSP)
Syntax
audio_stop
Unconditionally terminates the audio pump if running. The reply is always:
success
If the server is connected to a target, the target DMA and rendering is halted.
bind_wire
Syntax
bind_wire,wireName,pinName
Causes wireName to be bound to the pinName. It is an error for an output I/O pin to be bound more than once. Input or Output are the default I/O pins. All wire binding is released by destroy.
The reply is:
success,heap1,heap2,heap3
clear_credentials (Windows)
Syntax:
clear_credentials
Unconditionally removes the user credentials and if it exists the off-line license from the INI file. The command has effect on Windows only and does not involve the target in any way.
The reply is:
success
clear_symbols (Windows, Linux)
Syntax:
clear_symbols
Empties the server symbol table. This does not involve the target in any way.
The reply is:
success
close_input (BSP)
Syntax:
close_input,devIndex
When several device are merged for audio input (numbered 0 - N-1) close one of these devices by its index, causing zero samples to be generated in its place. This command is a specialized command for users that need to disconnect from a device that is about to be reconfigured. See reopen_input.
close_output (BSP)
Syntax:
close_output,devIndex
When several device are merged for audio output (numbered 0 - N-1) close one of these devices by its index. Samples being written to that device are discarded. This command is a specialized command for users that need to disconnect from a device that is about to be reconfigured. See reopen_output,
cmd
Syntax:
cmd,opcode [,arg1, ... ,argN]
This is a backdoor command, which allows an arbitrary command packet to be sent to the target. Where
opcode – 8-bit command opcode (see ProxyIDs.h)
arg1, … , argN – packet payload. No CRC; this is automatic.
Some commands do not take any arguments. For example, a call to destroy the target would look like
cmd,12
Another example is a call to Create Module. It calls ClassModule_Constructor(), and its arguments are:
cmd,15,1,<ClassID>,<nIO>,<K>,<wire1>,...,<wireJ>,<module1>,...,<moduleK>
where the number of wires J is encoded in the nIO bitfield. The command has one result - the module address.
The return is either:
success [<ret1>, ... ,<retN>]
or a normal failure code.
compile (BSP)
Syntax:
compile,flags,source_file,destination_file [, target_buffer_size ]
Instructs the server to compile source_file which must be a file containing valid commands from this document (generally an AWS file created by Designer) into destination_file in AWB binary format.
If target_buffer_size is not specified, then 264 is assumed. Commands will be compiled so as to fit in the specified command buffer. It is important when compiling for a target with a non-default buffer size to specify the buffer size to use. Note that current AWE builds have a buffer size of 4105. The command will fail if the buffer size specified is outside the range 16-4105.
The flags argument is no longer used. It is retained for backwards compatability, supply zero.
The command fails if source_file contains a make_binary command.
The command silently strips any command that tries to read a value in any way, or to operate in any way on a GUI object (inspector dialogs) from the output bit stream.
On success, the reply is:
success
otherwise
failed,reason
There are many possible reasons for failure.
connect (BSP)
Syntax:
connect,client_name,port
Instructs the server to reply to client_name on the given port. client_name must be the name of the PC running the client. The reply is:
success,client_name,port
On receipt of this reply, the client knows it is connected.
This command is for legacy purposes only, and does nothing.
create_active (BSP, GUI only)
Syntax:
create_active,dialog,left,top,moduleName [, bgnd_color [, text_color]]
where:
dialog – must be a dialog created by create_dialog,
left,top, – describes a position on the dialog surface
moduleName – a dot-expression that evaluates to the name of a module, optionally multiple expressions separated by semicolons may be used
bgnd_color – will be the dialog background color, default from [InspectorColors] InspectorFace=230,230,230
text_color – will be the text color of text controls, default [InspectorColors] TextColor=0,0,0
Creates a small control comprising 4 radio buttons in the order Active, Muted, Bypassed, Inactive. The control initializes its state from the specified module (or first module if there are several semicolon separated names). At 5Hz, it reads the module state (or first module if there are several semicolon separated names), causing the display to update if the module state changes.
On choosing a radio button, all modules (if there are several semicolon separated names) will be set to the new state.
create_bitmap (BSP, GUI only)
Syntax:
create_bitmap,dialog,left,top,width,height,fileName
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height – describes a rectangle on the dialog surface
fileName – is the name of an image file (BMP only) to display
Causes the specified image to be rendered on the dialog in the specified rectangle. Images are rendered beneath any controls the dialog may have, and, if more than one is specified, are drawn in order – that is the most recently specified bitmap appears above all earlier ones.
If the height or width are negative (usually –1), then only the [top,left] position is used – the size of the rectangle is obtained from the image; otherwise the image is stretched or shrunk as needed in both axes to fit the rectangle specified.
create_button (BSP, GUI only)
Syntax:
create_button,dialog,left,top,width,height,caption,script_file
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height – describes a rectangle on the dialog surface
caption – the text to appear on the button face
script_file – names a file of commands to be executed when the button is clicked
Creates a button control on the dialog of the specified size. On clicking the button ,the commands in the scrip file are executed.
ScriptFile may be commands instead of a filename; those commands are:
RemoveControls – deletes all the controls on a dialog
RemoveBitmaps – deletes all the images created by create_bitmap.
create_checkbox (BSP, GUI only)
Syntax:
create_checkbox,dialog,left,top,width,height,legend,attributes,dot-expression
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height – describes a rectangle on the dialog surface
legend – the text to appear to the right of the checkbox
attributes – a string of attribute controlling the appearance of the check box control
dot-expression – an expression to assign the value of the checkbox (0=not checked, 1=checked) each time the state of the checkbox changes
The attributes string must be a space separated string consisting of one or more of the following. If items are repeated, the right-most one is the one that takes effect.
readonly=val – 0 or 1, default 0; – when set, prevents the user changing the selection
Creates a checkbox control on the dialog of the specified size. On clicking the checkbox (causing its state to toggle) the new check state is assigned to the dot-expression. As with all assignments, the Set() function of the appropriate module is called after the assignment. At a rate of 5Hz, the expression is examined: if it changes the check mark is updated.
create_dialog (BSP, GUI only)
Syntax:
create_dialog,dialogName,left,top,width,height,width2,height2,caption[ ,bgnd_color [, combo_color [, text_color]]]
where:
dialogName – must be a an identifier not in use by any object
left,top,width,height – describes the size and position of the dialog surface
width2,height2 – describes the alternate width and height of the dialog – zero values mean there is no alternate size.
caption – will be the dialog caption
bgnd_color – will be the dialog background color, default from [InspectorColors] InspectorFace=230,230,230
combo_color – will be the color of drop list backgrounds, default from [InspectorColors] DropList=240,240,255
text_color – will be the text color of text controls, default [InspectorColors] TextColor=0,0,0
Creates a new dialog with the given name and caption. Dialogs and all their child controls are destroyed either by destroy or specifically by destroy_dialog.
create_droplist (BSP, GUI only)
Syntax:
create_droplist, dialog,left,top,width,height,nameValueList,caption,attributes,dot-expression
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height – describes the position and width of the drop list control
nameValueList of the form “string=value ….” – used to populate the list and specify the value associated with each item
caption – specifies the caption to appear above the drop list control
attributes – a string of attributes controlling the appearance of the combo box control
dot-expression – an expression to assign the value of the selection each time the selection changes
The attributes string must be a space separated string consisting of one or more of the following. If items are repeated, the right-most one is the one that takes effect.
readonly=val – 0 or 1, default 0; when set, prevents the user changing the selection
Creates a droplist control on the dialog of the specified size. On selecting an item in the droplist associated value is assigned to the dot-expression. As with all assignments, the Set() function of the appropriate module is called after the assignment. At a rate of 5Hz, the variable is examined: if it has changed, the selection is updated.
create_awslist (BSP, GUI only)
Syntax:
create_awslist, dialog,left,top,width,height,nameValueList,caption,attributes
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height describes the position and width of the drop list control
nameValueList of the form “string=filename ….” – used to populate the list and specify the file name associated with each item
caption – specifies the caption to appear above the drop list control
attributes – a string of attribute controlling the appearance of the combo box control
dot-expression – an expression to assign the value of the selection each time the selection changes
The attributes string must be a space separated string consisting of one or more of the following. If items are repeated, the right-most one is the one that takes effect.
readonly=val – 0 or 1, default 0; when set, prevents the user changing the selection
Creates a droplist control on the dialog of the specified size. On selecting an item in the droplist the associated file is executed as an AWS script file.
create_edit (BSP, GUI only)
Syntax:
create_edit,dialog,caption,left,top,attributes,caption,dot-expression [,in-expression]
where:
dialog – must be a dialog created by create_dialog,
left,top – describes the position and width of the drop list control
attributes – a string of attribute controlling the appearance of the edit control
caption – specifies the caption to appear above the edit control
dot-expression – an expression to assign the value of the edit box
in-expression – if present is checked at 5Hz, and updates the edit control when it changes
Creates an edit control with a caption above in a box 69 wide by 42 high.
The attributes string must be a space separated string consisting of one or more of the following. If items are repeated, the right-most one is the one that takes effect.
format=format_specifier – a printf style format to use when formatting values, default %.2f
stepsize=step – default 0, the amount by which displayed values will be quantized
min=val – default -100, the minimum displayable value on the meter
max=val – default 0, the maximum displayable value on the meter
readonly – 0 or 1, default 0; when set, prevents the user editing the value
create_filelist (BSP, GUI only)
Syntax:
create_filelist,dialog,name,left,top,height,buffer_expression,buffer_size_expression,async_expression, type_expression[,filepath[,rate]]
where:
dialog – must be a dialog created by create_dialog
name – specifies the caption to appear above the control
left,top,height – describes the position and height of the control
buffer_expression – expression specifying the start address of the buffer used to transfer data to the target
buffer_size_expression – expression specifying the size of the transfer buffer.
async_expression – expression specifying where the PC should write asynchronous notifications.
type_expression – expression specifying where the PC should a 32-bit integer containing the first 4 characters of the file extension.
filepath – optional list of files to populate dialog with at startup
rate – rate in Hz at which to poll and fill the transfer buffer.
The file list control is used to stream data from a file to the target. The transfer buffer holds a total of buffer_size + 1 32-bit words. The final word in the transfer buffer, buffer[buffer_size] is the handshaking word. At a 10 Hz rate, the control checks whether
buffer[buffer_size] == 0
If non-zero, nothing happens. If equal to zero, the control opens the current file, seeks to the current seek position, reads buffer_size*4 bytes from it (if possible), fills buffer with the actual bytes read, and closes the file. The low 24 bits of the handshaking word at buffer[buffer_size] is set to the number of bytes reads. The high 8 bits are set to one of the following notifications:
FIOS_NewStream – Indicates that we are at the start of a new file
FIOS_NextBlock – Set for the second block onward until the next to last block
FIOS_LastBlock – Indicates that this is the last block of data in a file.
(These are defined in Framework.h).
Typically, a single write to the target of length buffer_size+1 words occurs. Only at the end of the file are two separate write performed; the data followed by the handshaking word.
If the end of file is reached and there are no more files to play, the writing of data stops. Otherwise, the next file is opened and playback continues.
The asynchronous handshaking word notifies of other conditions.
FIOS_Stopped - generated by Stop only
FIOS_Paused - generated by Pause only
FIOS_Error - generated by a file I/O error when reading the current file, no data is sent
The type_expression indicates the extension of the file being played to the target processor. type_expression is updated whenever the first block of a new file is played. The file extension is converted to upper case, zero-padded or truncated, and packed into a 32-bit integer. The value written is in little-endian format and the least significant byte of the word holds the first character. For example,
mp3 0x00 0x33 0x50 0x4D
'3' 'P' 'M'create_graph (BSP, GUI only)
Syntax:
create_graph,dialog,left,top,width,height,attributes,dot-expression,count
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height – describes the position and size of the graph
attributes – a string of attribute controlling the appearance of the meter
dot-expression – describes an element taken to be the first in an array
count – the number of elements to use
The attributes string must be a space separated string consisting of one or more of the following. If items are repeated, the right-most one is the one that takes effect.
format=format_specifier – a printf style format to use when formatting values, default %.2f
mapping=[db20|undb20|lin[ear]] – default db20. The value is displayed according to the mapping.
stepsize=step – default 0, the amount by which displayed values will be quantized
meteroffset=offs – default 0, an amount to be added to values before use
min=val – default -100, the minimum displayable value on the meter
max=val – default 0, the maximum displayable value on the meter
numbers – default 0, when non-zero specifies that numbers should be drawn above each element
This command creates a graph object of the specified size. The width of the object is divided by count to give the width of each stripe. 10 times a second, the target array is queried for count values, and those values used to display the graph stripes. If numbers is set, then the top 16 pixels of the graph is used to display the numeric value of each element according to the format specified. The width of each strip needs to be 25 or more when displaying numbers to avoid truncation of the text.
create_grid (BSP, GUI only)
Syntax:
create_grid,dialog,left,top,width,height,attributes,dot-expression,count1[,count2]
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height – describes the position and size of the grid control
attributes – a string of attribute controlling the appearance of the grid control
dot-expression – describes an element taken to be the first in an array
count1 – the size of the first dimension
count2 – if present is the size of the second dimension
The attributes string must be a space separated string consisting of one or more of the following. If items are repeated, the right-most one is the one that takes effect.
format=format_specifier – a printf style format to use when formatting values, default %g
min=val – default –1e10, the minimum displayable value on the grid
max=val – default 1e10, the maximum displayable value on the grid
colwidth – default 50, value must be >= 50, width of column in pixels
sidewidth – default 30, value must be >= 30, width of first column in pixels
The command creates a grid control of the specified size. If count2 is given, the control as count2+1 columns, the first being the index, otherwise the control has 2 columns, the first being the index. The control operates as a very simple spreadsheet. On changing the value of any cell, the underlying array element is assigned, and the corresponding module’s set member is called. At 5Hz intervals, the grid will repaint itself if any element has changed value.
create_layout
Syntax:
create_layout,layout_instance_name,divider,nModules
where:
layout_instance_name – must be an identifier not currently defined,
divider – must be an integer >= 1,
nModules – must be an integer >= 1
This creates a layout object named layout_instance_name that can hold a total of nModules with the given divider. A layout is a collection of modules that are all pumped together at the given division rate. Only memory for the layout is allocated and a few internal fields of the layout structure set; no modules have been added. Modules must be subsequently added by calls to add_module.
On success the reply is:
success, heap1,heap2,heap3,layout_instance_name=instanceID
create_led (BSP, GUI only)
Syntax:
create_led, dialog,left,top,width,height legend,dot-expression
where:
dialog – must be a dialog created by create_dialog,
left,top,width,height – describes the top-left corner of the LED control
legend – the text to appear to the right of the LED image
dot-expression – an expression to evaluate at 5Hz – if non zero the LED is shown lit
Creates an LED control. If the value described by dot-expression is non-zero, the LED is shown bright green, otherwise dark green. The expression is evaluated every 200 msec.
create_lookup
Syntax:
create_lookup, maxId
where:
maxID – must be a non-zero integer
Creates a lookup table that handles IDs in the range 1..maxID by providing a fast O(1) lookup table. If no table is specified, lookups are O(N/2).
update_lookup
Syntax:
update_lookup
This command is for legacy purposes, and does nothing.