ProppFrexx Control-Commands

You have a question or need an advice about how to do something? Ask it here!
Post Reply
User avatar
radio42
Site Admin
Posts: 8295
Joined: 05 Apr 2012 16:26
Location: Hamburg, Germany
Contact:
ProppFrexx Control-Commands

Post by radio42 »

By using so called 'Control-Commands' you can trigger almost any activitiy (action) you might also perform via the graphical user interface.
A single control-command encapsulates a certain action to perform (e.g. start the scheduler, play the next track, play a cardwall entry, change the volume of a mixer-channel etc).
The complete list of all available control-commands can be found in the appendix of the user manaul.

Where are Control-Commands used?
Control-Commands can be used at several places. The most common scenarios are the following:
  • You want to use your external (MIDI) controller to remotely controll cetain elements of ProppFrexx ONAIR (e.g. control mixer-channels, control the playback of Players or Cardwalls) etc.
  • You want to update your web-site whenever a new track starts to play)
  • You want to control the status of an OnAir light whenever a mixer-input is 'On'
  • You want to synchronize ProppFrexx with another application (vice versa)
  • etc.
However, you can mainly distinguish between the following two modes:
1. Trigger an external 'action' when something 'happens' within ProppFrexx
2. Trigger an internal 'action' when something 'happens' outside of ProppFrexx


Trigger an external 'action' when something 'happens' within ProppFrexx ONAIR
To do so you can use any of the defined internal 'Events'. An event is a predefined notification point within ProppFrexx ONAIR which is triggered whenever the related event actually occurs.
Beside global System-Events (see the general settings dialog, section 'Events/Commands') there are:
  • Track related events (triggered with that particular track, like 'OnTrackPlayed' or 'OnTrackStopped' or even triggered when a certain playback position is reached)
  • Mixer-Channel related events (triggered with that particular mixer-channel, like 'OnFaderStart' or 'OnMute' etc.)
  • Streaming-Server related events (triggered with that particular streaming server, like 'OnServerStarted' or 'OnServerStopped' etc.)
  • Scheduler related events (triggered with )
You might assign any number of control-commands to each single event (a single control-command is always represented in its own line, as such multiple commands are placed each on its own line). You might directly type the control-command into the text editor (if you already know its name all all its parameter values); however, the recommended way is to use the build-in 'Control-Commands Builder' (just click on the 'Edit' button within the event editors field) to invoke it.
As indicated before, control-commands mostly do have parameters (see the user manual for details). The full syntax is:

Code: Select all

<control-command-name> <parameter1>|<parameter2>|...
Meaning:
The first value is the name of the control-command. If parameters are needed, they are separated from the control-command-name by a space and the individual parameters are then separated by the pipe-character ('|').
Example1:

Code: Select all

CW1_PLAY_CARD 1
This control-command would start playing the first card in the Cardwall I. "CW1_PLAY_CARD" is the control-command-name and "1" is the only parameter.

Code: Select all

MIXER_OUTPUT_VOLUME_SET OUT1|0.5
This control-command would set the volume of the OUT1 mixer-channel to a linear value of 0.5 (which is -6dB). "MIXER_OUTPUT_VOLUME_SET" is the control-command-name and "OUT1" and "0.5" are the two parameters.

Note: When using the 'Control-Commands Builder' you might notice, that 'Parameter' line might be populated with some 'help' text, which contains/describes the needed parameters. It is important to notice, that this text is really be some help text and does NOT reflect the syntax of the parameters.
Example (the "MIXER_OUTPUT_VOLUME_SET" action might show the following parameter help text):

Code: Select all

[<mixername>|]<volume(0.0...1.0)>
Any text enclosed in square brackets ('[', ']') means, that these parameters are optional.
Any text enclosed in peaked brackets ('<', '>') specify one parameter and needs to be replaced by its actual parameter value.
Any text enclosed in round brackets ('(', ')') just gives you a hint about the possible value range.
In the example above it means:
<mixername> is optional and should be replaced by the name of the mixer-channel to use (e.g. replace this with OUT1, as shown above).
<volume(0.0...1.0)> is mandatory and should be replaced with the volume value to use (which might be between 0.0 and 1.0).


Trigger an internal 'action' when something 'happens' outside of ProppFrexx ONAIR
ProppFrexx ONAIR comes shipped with various external GPIO (general purpose input/output) interfaces, which can be used to communicate with external applications or hardware. These are:
  • TCP Device: allows native communication with any TCP/IP based client
  • MIDI Devices: allows receiving (and sending) MIDI messages from/to up to two different MIDI devices
  • Serial I/O: allows receiving (and sending) data from/to a serial interface port
  • GamePort: allows receiving events from a general game port or joystick device
  • Keyboard Hotkey: allows you to assign commands to any keyboard event
  • Open Sound Control (OSC): allows receiving (and sending) data from/to any other OSC client/host (via UDP)
  • IO-Warrior: allows direct communication with a IO-Warrior interface card (contact closure support)
  • Velleman: allows direct communication with a Velleman interface card (contact closure support)
You setup these GPIO interfaces in the general settings dialog in the section 'GPIO/Remoting'.
Note, that you need to define a 'Mapping' between the external events (e.g. a MIDI Short Message or a GamePort button) and the control-command to be associated.
This is done in the respective 'Mapping Definition' dialog of the respective GPIO interface (just click on the flash arrow icon next to the 'Mapping' field to do so).
User avatar
radio42
Site Admin
Posts: 8295
Joined: 05 Apr 2012 16:26
Location: Hamburg, Germany
Contact:
TCP Remote Interface

Post by radio42 »

As stated above there is a general TCP interface available which can be used with any TCP client application (e.g. your own) to communicate directly with ProppFrexx ONAIR.
The TCP interface follows a certain syntax which you need to use in order to communicate with ProppFrexx ONAIR to execute certain control-commands.
This syntax is explained below...

First note, that you must enable the TCP Control within ProppFrexx.
You can do this in the general settings dialog in the section 'GPIO/Remoting' within the 'TCP Device' group.
Select a port number, and authorization password and make sure the 'TCP Control Enabled' checkbox is checked.

Now you can send TCP messages to this ProppFrexx instance (identified by the hostname or IP address of your machine and the specified port number) - this in order to remotely control ProppFrexx.

The 'TCP messages' are actually text strings (in UTF-8 form) and consist of the same control-commands as already explained.
a) You must (as the first command) send the "AUTHORIZATION" command using the password of the remote client
b) each command must be terminated by a double CRLF (\r\n)
Example:

Code: Select all

AUTHORIZATION <password>

SHOW_ALERT_WINDOW Online|You are now online!

Note, that each individual command is separated by a double CRLF (\r\n). If you need to combine multiple commands in a block, just use a single CRLF (\r\n).


The "EXEC_SEND_TCP" command might be used to send a message from one ProppFrexx instance to another ProppFrexx instance. This command has the following format:

Code: Select all

EXEC_SEND_TCP <host>:<port>|<content>
It first creates a TCP connection to the given host and port and then sends the content string to it. When done it closes the connection.
Again, when you want to remotly control another ProppFrexx client, you must first send the AUTHORIZATION command, followed by any additional commands (seperated by a double CRLF).
This means the <content> string must contain multiple control-commands itself.
How to do this?
You can use marcos within your content string, e.g. there is a ${CRLF} macro.

So here is an example of one control-command you might use to test your remote TCP control client with:

Code: Select all

EXEC_SEND_TCP 127.0.0.1:8052|AUTHORIZATION password${CRLF}${CRLF}SHOW_ALERT_WINDOW ONLINE|You are now online!${CRLF}${CRLF}
As you can see in the example, it is actually ony one line, which starts with the EXEC_SEND_TCP action followed by the host and port address of the client you want to send a message to. But the message (content string) itself is followed right after using the notation mentioned above.
So the actual message which is send to the remote client is:

Code: Select all

AUTHORIZATION password${CRLF}${CRLF}SHOW_ALERT_WINDOW ONLINE|You are now online!${CRLF}${CRLF}
So you can use this to send any number of control-commands to the remote client.
But all commands to be send must be within one line and seperated by a double CRLF and start with the AUTHORIZATION command.

A complete list of control-commands can be found in the User Manual.

E.g. the following would open a new playlist, load a playlist file and starts it:

Code: Select all

EXEC_SEND_TCP 127.0.0.1:8052|AUTHORIZATION password${CRLF}${CRLF}PLS_CURRENT_NEW ${CRLF}PLS_CURRENT_LOAD_PLAYLIST C:\test.m3u${CRLF}PLS_CURRENT_AUTOPLAY_ON ${CRLF}${CRLF}
Note1: control-commands having no parameter must still end with a single space!
Note2: multiple control-commands in the main block only use a single CRLF!
User avatar
radio42
Site Admin
Posts: 8295
Joined: 05 Apr 2012 16:26
Location: Hamburg, Germany
Contact:
Using MACROs within control-commands

Post by radio42 »

ProppFrexx manages quite long list of possible 'Macro's which can be used within control-commands.
The complete list of available Macros can be found in the User Manual.

A Macro always has the following syntax: ${<name>}

E.g. if you want to dynamically load a playlist file according to the current time, you might use the ${yyyy}, ${MM}, ${dd}, ${HH}, ${mm} or ${ss} macros

Code: Select all

EXEC_SEND_TCP 127.0.0.1:8052|AUTHORIZATION password${CRLF}${CRLF}PLS_CURRENT_NEW ${CRLF}PLS_CURRENT_LOAD_PLAYLIST C:\pls_${yyyy}${MM}${dd}_${hh}.m3u${CRLF}PLS_CURRENT_AUTOPLAY_ON ${CRLF}${CRLF}
This would load a playlist file which is composed at runtime. The time macros are replaced by the current time the command is executed and might result in e.g. "C:\pls_20100420_15.m3u".

Note:
The same macros might also be used inside a 'Program Scheduler' resp. inside certain script-lines!

Post Reply