PASHA

PASHA, the MediaMatrix Serial Handling Adapter, is a software application that provides external serial command and read-back of designer selected controls in a MediaMatrix View File.  The hardware required for this is a standard PC serial port (usually RS-232).  Multiple serial ports, or serial command streams, can be accommodated.  RS-232, RS-422, and other cards and serial driver software modules, available from other manufacturers, can add both additional serial port features and increase communications reliability.  The serial command protocol used by PASHA is human-readable ASCII, so it is possible to test and debug PASHA control of a specific MediaMatrix View File using just a Windows-based PC with a spare serial port - MediaMatrix hardware is not required.  With a second serial port and a null-modem cable, a Windows terminal program can simulate the controlling machine.

It is important to note that in MediaMatrix 3.x the need for the PASHA.INI file has been eliminated - Control Grouping is the method used to export controls.  You may find it necessary to import View Files created in earlier versions of MediaMatrix, and these may include a PASHA.INI file for external control via serial ports.  In order to do this, use the "Tools | Import/Export | Import PASHA.INI..." command. Be aware that in earlier versions the Control IDs used were hexadecimal numbers, and were not case sensitive.  In version 3.x the Control Group name used can be any 3 alphanumeric characters, and IS case sensitive.  Therefore it is possible that a PASHA.INI file that was working in an earlier version may not work, or may have some controls that do not work, after being imported into MWare 3.x.

Software Architecture (Severely Abridged)

In MediaMatrix, there are two Windows applications that work together: PAVCON (Peavey Audio Virtual Console), which is the graphical user interface, and PADPU (Peavey Audio Digital Processing Unit), which contains the devices and controls and governs the DSP hardware. Serial control is accomplished with the addition of a third application, PASHA (Peavey Audio Serial Handling Adapter), which, through a Windows serial port, turns external serial commands into MediaMatrix commands. There is a client/server relationship between these applications, with PADPU being the server and PAVCON and PASHA being clients. PASHA translates serial commands into the same kind of commands that PAVCON uses to set and display the control values in PADPU. Only PAVCON has a user interface.

Configuring PASHA

Go to the Tools | Options | Remote Services page, and click on 'Add PASHA Port...' A dialog box will appear. Choose the correct serial port, baud rate, and data bits for your application. Only one PASHA service is allowed per serial port, but multiple serial ports can be opened at once. If the PASHA service fails to start, it is probably a conflict with the serial port. Either another program has already opened that serial port, or the serial port does not exist on the system.

User IDs and Control Groups

PASHA user IDs correspond to 3 character Control Group names in View Files. To specify a user ID for a control in MediaMatrix, open its Control Object Properties page and select the Group tab. Enable Control Grouping and give the control the desired 3 character Group Name. Any alphanumeric character may be used, and the protocol is case sensitive, so "aaa" is different from "AAA". Control Group names of other lengths are possible in MediaMatrix, but only those exactly 3 characters long can be used for serial control via PASHA.

Message Protocol

Messages are ASCII (text) strings. While they contain hexadecimal numbers, the Hex numbers are represented by ASCII (text). Do not send actual hex data, but an ASCII (text) string that represents the value to be sent.

Each message begins with a message-type character and ends (with the exception of the NAK message) with an end-of-message character '.'. Each message to PASHA results in a response message from PASHA. PASHA never sends a message except in response to an external message.

In general, the protocol supports Setting and Getting control values. User IDs are entered into Control Groups which identify a unique control or group of controls. They are specified for use with PASHA with 3 alphanumeric characters. Control values are specified with a 2 digit hexadecimal number, 00 through FF.

Controls are set to a position using the cSETVALUE 'S' command. You can determine the current setting of a control using the cGETVALUE 'G' command. The 256 values that a control can take on correspond to 256 equidistant positions of a control in a MediaMatrix view file. It is possible, and normal in some cases, for the value that a control actually takes on (and returns) to not match the value to which it was set. For instance, in the case of a switch-style control, any value sent between 00 and 7F will result in a return value of 00, and any value sent between 80 and FF will result in a return value of FF. This is because a switch can only be either ON or OFF. If it is ON, it will return a value of FF, while if it is OFF, it will return a value of 00. If commanding a Level with Trim device's Trim control, the dB range of the Trim control (set up by Trim Min. and Trim Max.) is simply divided into 256 possible values. Most devices' gain controls, however, are non-linear, and the math is not so simple. For those controls, tables are included below that map linear control values to dBs of gain, one for a gain control with range of -100dB to +12dB, another for a gain control with a range of -100dB to 0dB. Also included are tables that map control values to Router channel selections for various sized Routers.

For example, to set the channel 2 input gain specified in the demo view file PASHA32.PAV to fully counter clockwise, one first look up the UID specified in the Control Group for the control in question. In this case it is 2iG. Fully counter clockwise is 00 Hex. The cSETVALUE command is 'S' and the end-of-message character is '.'. Putting this all together gives a command string:

S2iG00.

Note that it is not required or desirable to put a carriage return after the end-of-message (EOM) character '.'. PASHA will accept the command when it receives the EOM character. Shortly thereafter it will return the value that the control has been set to:

V2iG00.

To check what a control is set to, you can use the cGETVALUE 'G' command. For example to check the setting of the channel 1 parametric EQ center frequency control, you send:

G1Cf.

Note that since you are requesting a control value, you do not send one. If the control was set to the mid point of its rotation you will get a response:

V1Cf80.

Remember it is possible, and normal in some cases, for the value that a control actually takes on (and returns) to not match the value to which it was set. For instance, in the case of a switch-style control, any value sent between 00 and 7F Hex will result in a return value of 00 Hex, and any value sent between 80 and FF Hex will result in a return value of FF Hex. For example you may have sent to the Channel 2 output mute:

S2oM3E.

However since the switch can only be on or off it will be set to off and return:

V2oM00.

If you send a command using a UID that is not in a Control Group in the view file, PASHA will respond with a cUNLISTEDUID 'U' and repeat back the Uid it does not find in the PASHA.INI file. For example if there was no Control Group hat in the view file, and you sent:

Shat48.

the response would be:

Uhat.

If you send a command using a valid UID (a 3 character Control Group name) in the view file, but one or more of the controls that Control Group references is not found in the view file, PASHA will respond with a cUNLISTEDCID 'C' and repeat back the UID you sent. For example if there was a UID ukc in the view file, and one or more of the controls to which it referred are "dead" or "orphaned", and you sent:

Sukc48.

the response would be:

Cukc.

A "dead" control will occur if the algorithm it is part of did not compile. This will happen if the algorithm is not properly wired. An "orphan" control will occur when the algorithm it was copied from has been deleted from the view file.

If you send an illegal message such as specifying a value as part of a get message, or scramble the order of message components, or there are certain other communications errors, PASHA may respond with a Negative Acknowledge mNAK '?' instead of the normal response. For example if you sent:

GHLP57.

PASHA will respond with:

?

Note this is the only message in the PASHA protocol, which does not end in an end of message character cEOM '.'.

No response will be sent if garbled data or illegal commands are received by PASHA. While PASHA will respond with a Negative Acknowledge mNAK '?' for certain communications errors, you can't be assured that it will always do so.

If there is a serial port error or communications timeout, or if there is a communications failure between PASHA and PADPU, you will get the Fail mFail 'X' message from PASHA as follows:

X.

If you send a valid message to PASHA, but PADPU is either not running, or a view file is not compiled and running, then PASHA will respond with a mNotReady message. For example if you sent:

SDeD48.

but the view file was not compiled, then you would receive back:

R.

C-LIKE MESSAGE DEFINITION

This section defines the message protocol using "C-like" declarations of constants and structures. The convention here is that words beginning with 'c', such as cSETVALUE and cGETVALUE, are character constants. Words beginning with 'f'', such as fUid and fVal, are message field structures. Words beginning with 'm', such as mSetValue and mGetValue, are message structures.

//---- Message constants
const char cSETVALUE = 'S'; // an fType value
const char cGETVALUE = 'G'; // an fType value
const char cVALUE = 'V'; // an fType value
const char cNOTREADY = 'R'; // an fType value
const char cUNLISTEDUID = 'U'; // an fType value
const char cUNLISTEDCID = 'C'; // an fType value
const char cFAIL = 'X'; // an fType value
const char cNAK = '?'; // an fType value
const char cEOM = '.'; // an fEom value

//---- Message fields
/* fType: Message Type. 1 character, denotes the message type. */
struct fType {
  char data;
};

/* fUid: User ID. 3 ASCII characters, specifies one of the User IDs entered as a Control Group name in the View File. */
struct fUid {
  char data[3];
};

/* fVal: Control Value. 2 ASCII hexadecimal digits, specifies a control value between 0 and 255. */
struct fVal {
  char data[2];
};

/* fEom: End Of Message. 1 character, appears at the end of every message, excepting mNak. */
struct fEom {
  char data = cEOM;
};

//---- Messages
/* mNak: Negative Acknowledge. Response sent to client upon receipt of unintelligible data. This could be due to a communications error or to data out of order. An mNak is not necessarily sent for every byte of bad data. */
struct mNak {
  fType = cNAK;
};

/* mSetValue: Set Control Value. Request sent by a client to set the value of a Control Group. */
struct mSetValue {
  fType type = cSETVALUE;
  fUid id;
  fVal val;
  fEom eom;
};

/* mGetValue: Get Control Value. Request sent by a client requesting the value of a Control Group. */
struct mGetValue {
  fType type = cGETVALUE;
  fUid id;
  fEom eom;
};

/* mValue: Control Value. Response sent to the client acknowledging an mGetValue or mSetValue. Note that it is possible, and normal in some cases, that the val field will not match the val that was sent in the mSetValue. */
struct mValue {
  fType type = cVALUE;
  fUid id;
  fVal val;
  fEom eom;
};

/* mUnlistedUid: Unlisted User ID error. Response indicating the fUid specified in the mSetValue or mGetValue does not match any Control Group name in the currently running View File. */
struct mUnlistedUid {
  fType type = cUNLISTEDUID;
  fUid id;
  fEom eom;
};

/* mUnlistedCID: Unlisted Control ID error. Response indicating a control withing the Control Group referenced by the fUid specified in the mSetValue or mGetValue was not found in the currently compiled View File. Probably means that the Control is "dead" or discarded. */
struct mUnlistedCID {
  fType type = cUNLISTEDCID;
  fUid id;
  fEom eom;
};

/* mNotReady: Not Ready. This means that there is no View File currently compiled and running in MediaMatrix. */
struct mNotReady {
  fType type = cNOTREADY;
  fEom eom;
};

/* mFail: Something Has Failed. This is sent in response to serial port errors, communication time-outs, and other internal errors not covered directly. */
struct mFail { 
  fType type = cFAIL;
  fEom eom;
};

MESSAGE STRUCTURES QUICK CHART

Real-time Concerns and Flow Control

In general, the serial control throughput into the MediaMatrix computer is dependent upon the number of Windows applications running, and the activity level of those applications. Any application which is actively animating a display on the screen will take time away from other applications, such as PASHA. MediaMatrix itself, if displaying any controls, requires a certain percentage of the processor power to keep those controls updated.

Serial data overruns at the MediaMatrix end can be prevented by having the external serial device wait for the response to each command it sends. If this is not possible, keep in mind that each PASHA service instance can store about 100 unacknowledged commands before overflowing its receive buffer.

Serial data overruns at the external serial device are usually not an issue since PASHA will never speak unless spoken to - the only way to elicit data from PASHA is to send a command.

Serial Control Experimentation

To experiment with PASHA control of MediaMatrix on a desktop PC, with no MediaMatrix hardware required. You'll need two free COM ports, a null-modem cable and a Windows terminal program such as Hyperterminal.

1) Open and Compile the demo view file PASHA32.PAV in the samples directory.

2) Start a PASHA remote service on one of the COM ports using Tools | Options | Remote Services, Add PASHA port...

3) Start the Windows terminal program on the other COM port, making sure to match the communication settings of PASHA.

4) Enable local echo in Hyperterminal so you see what you're typing.

5) To mute the input to channel 1, send:

S001FF.

The response should be:

V001FF.

and the mute button will light.

6) To read the channel 2 center frequency control, send:

G00B.

and the response should be:

V00B99.

with the last two characters depending on the control's position in the view file.

If you are experiencing difficulty, test your COM ports and cable by making sure that you can communicate between two copies of the Windows termainal program assigned to the two COM ports.

You can also enable PASHA debug printout in the Terminal Window. At the top level menu in Terminal Window, type "S" (for (S)ervices), then "H" (for (pas(H)a), then "D" (for (D)ebug). You should then get some printout concerning PASHA activity as it happens.

A Note About Reading Meter Values

It is possible to read MediaMatrix audio meter values with PASHA, but there is an important fact to be aware of when doing so - as an optimization to save CPU cycles, meters are only updated when their controls are being displayed in the user interface. This implies that you must either have meter child windows open on the screen, or one control from each of the meters of interest must be copied out to an open child window or the main View Window. It is preferable to copy out a non-changing control, such as the Meter Time Constant, rather than the meter control itself, to save the user interface the burden of continuously updating the display. If having these controls visible to the user is a problem, they may be rendered invisible by manipulating their Control Object Properties (turn off the following check boxes: Text, Block, Bitmap and Style). Once you make a Control Object invisible it may be very difficult to find again unless you also check Fix Size and give it some nominal size, such as 6 by 6.

A numeric display of the peak hold value is not provided in the meter devices even though the algorithm calculates it. To read a meter's peak hold indicator value, start by copying the numeric control object (the yellow box with the dB value in it). Paste the copy down someplace convenient, perhaps in the meter device. While the new copy is selected, press Alt-Enter to bring up the Control Object Properties window, and select the Id tab. Under Control Id | Control, you will notice the digit entered is 2. If you change this to a 5 and click OK, the new numeric display will now read the peak hold indicator's value. It can then have a Control Group assigned in the usual way.

Known Bugs

A bogus serial data character may be emitted whenever a serial port is closed on the PC.

Serial Control Value to Device Control Value Tables

Some selected mappings of serial control values to device control values follow. You can also generate a table for any other control using a command in the MediaMatrix Terminal window in the following manner - after compiling a View File, twiddle the control of interest, switch to the Terminal window and press the 'v' on your keyboard. This will invoke the (V)alueTable command, which will print the table to the screen. You can also capture the table to a text file or printer by invoking the appropriate Terminal window modes.

Control value to dB's of gain table: -100dB to +12.0dB type control

Control value to dB's of gain table: -100dB to +0.00dB type control

Control value to Router input selection table: 1x1 Router

Control value to Router input selection table: 2x1 Router

Control value to Router input selection table: 4x1 Router

Control value to Router input selection table: 8x1 Router