FaçadeSignage Standard and Professional versions can be remotely controlled using HTTP and OSC protocols.

The whole set of commands can be invoked in both protocols, considering the difference in use-case:

  • HTTP commands can be simply called using a Web client (both a real browser or API).
    This is the optimal solution for integration with authoring software that have custom actions (like: call a URL when some condition is true).
    However the time of call reception and execution is slow, because the http protocol creates an underlying TCP connection to exchange data.
    For this reason it is ok to use for commands not used often (like playCue or playSet) but not for high-frequency commands like surfaceOpacity.

  • OSC commands need to be called composing an osc packet and sending it using a library, therefore this is the preferred method for low level integration with custom software.
    OSC calls are very quick, and are suitable both for low-frequency and high-frequency commands (for example: to fade a surface in realtime).
    Since the protocol uses UDP as transport, OSC packets are subject to packet loss.
    To create a level of reliability, the FaçadeSignage OSC receiver implements a simple way of making more calls for the same command in order to have guaranteed delivery.


Enabling Receivers

 

Command receivers need to be explicitly enabled in the Start Options for each project:



In the picture above both the Web Receiver (HTTP) and the OSC Receiver will be enabled when the project is started.

 

Available Commands


The list of available commands is available here.

Every command has a number of parameters that must be specified using the right type.
For example, the playSetIndex command has this signature:

  

playSetIndex <i:index>,<i:cue>,<b:keep_black>

 
This means that the first parameter index is of type integer, the second cue is of type integer, and the third is a boolean that can be either "true" or "1" / "false" or "0"


Calling commands using HTTP


A call to the http receiver is made on port 15000, and  composed in this way:

   

http://<facade_player_ip>:15000/api/<command>/<parameter1>/<parameter2>/..

   

So, calling playSet on the local machine would be:

    

http://localhost:15000/api/playSetIndex/1/2/false

    

Please note how parameters are passed in the Url, so that the first integer parameter (set index) is 1, the second integer parameter (cue index) is 2 and the last boolean parameter is false.

Commands without parameters can be simply called:

    

http://localhost:15000/api/rewindCurrentCue

    


Calling commands using OSC

 

Commands can be called with OSC composing an OSC message and sending it over the network towards the FaçadeSignage player, on port 33132.

Commands can be either inserted in a single OSC Bundle, or more messages can be merged in a bundle.


The anatomy of the command packet is the following:

     

/tabula/osc
string: the command
[...]: the command parameters

   

The command is a string containing the command to be executed.

The variable parameters are the ones provided in the signature of the particular command, their type depends on the command.


Example:

The playSet command of the example above (http) would be composed in this OSC packet.

              

/tabula/osc/
(string) playSetIndex                 // the command to call
(integer) 1// the index parameter
(integer) 2// the cue parameter
(bool) false// the keep_black parameter

          

The playCue command:

   

/tabula/osc/
(string) playCue                // the command to call
(integer) 0// the integer parameter to call first cue