RS-232 Action

The RS-232 action (device_operation) allows third party applications to execute RS-232 commands via the Player API.

You can use your RS-232 connection to call the Player API using one of the following methods:

    • remote_action: Exposes the device_operation action via the command-line remote_action tool.
    • XML: Exposes the device_operation action through simple XML commands sent to port 2324.
    • Flash: Flash applications can call the Player API via ActionScript and the device_operation action.
 

To define the communication type and any custom actions, you will need to update your player’s configuration profile. For more information, see Configuration Profile – Players – The Devices and Triggers Section – The Devices Tab.

Define the communication type:

When configuring devices, it is possible to set the communication type to one of the following:

    • Serial: The configuration is straightforward: specify a name that represents the device attached to the serial port, and configure the serial port accordingly. Choose the correct COM port, speed, byte size, parity, read timeout, flow control and stop bits for your device. The exact settings to use depend on the capabilities of your serial port and attached device. Consult their user manuals for further details. The default settings will work for most devices.

      Drain Bytes is a useful parameter that will drain the specified number of bytes from the serial port before executing any RS232 command, therefore making sure it is clean. This is needed in order to support some screens that periodically fill the RS232 command buffer with garbage data, preventing the Player from correctly identifying the expected response for a given command.

Defining communication type: Serial
 

    • TCP: If TCP is selected, you will enter the hostname or IP of the TCP service as well as the port to connect to.

Defining communication types: TCP
 

Define custom actions:

Custom actions
For devices in need of control operations not listed within Broadsign’s default set of actions, custom ones can be defined using the Type “Custom”.

A custom application can use default and custom device operations on the Player API by sending an XML message to the monitor_remote port (2324).

Use XML for a default device operation:

The device_operation action can be used to remotely execute any device operation that is already defined within the Broadsign Administrator.

For example, using a Set Volume command with value 35, the XML should be:

<!-- SENT XML -->
<rc version="1" id="1" action="device_operation" name="set_volume" value="35"/>\r\n\r\n
<!-- RECEIVED XML -->
<rc version="1" id="1">
<device_operation name="set_volume" value="35" status="1" return="1415BF4478"/>
</rc>

The status flag will be “1″ when the device operation executes successfully. This means that the expected hexadecimal code was returned by the device on the first attempt, or that the error handler operation was able to recover and execute successfully.

When the status flag is “0″ it indicates that the operation failed.

In all cases, the hexadecimal code returned for the initial command (not the error handler) will be in the “return” attribute.

Use XML for a custom device operation:

Whenever a custom action is invoked via monitor_remote XML, custom will be used for action type, while the value will be a user-defined string.

For example:

<!-- SENT XML -->
<rc version="1" id="1" action="device_operation" name="custom" value="OPEN"/>\r\n\r\n
<!-- RECEIVED XML -->
<rc version="1" id="1">
<device_operation name="custom" value="OPEN" status="1" return="1415BF4478"/>
</rc>
RS-232 – XML Parameters
Parameter Description
id Contains the identifier of the request.
version The version is always 1.
action The kind of action to be taken, in this case device_operation.
name The name of the operation/action type. Default examples include set_volume and set_brightness. Note: If referring to a custom action, this value is custom.
value The value of the action type, according to your device’s settings. For example, you could configure set_volume to a value of “35”.

A custom application can use default and custom device operations on the Player API by sending a JSON message to the WebSocket server of monitor_remote (port 2326). You will need to enable the WebSocket server. For more information, see Configuration Profiles – Players – The Remote Control Tab.

Use JSON for a default device operation:

The device_operation action can be used to remotely execute any device operation that is already defined within the Broadsign Administrator.

For example, using a Set Volume command with value 35, the JSON request should be:

{
    "rc": {
        "version": "1",
        "id": "1",
        "action": "device_operation",
        "name": "set_volume",
        "value": "35"
    }
}

The received JSON would be:

{
    "rc": {
        "device_operation": {
            "name": "set_volume",
            "value": "35",
            "status": "1",
            "return": "1415BF4478"
        },
        "version": "1",
        "id": "1"
    }
}

The status flag will be “1″ when the device operation executes successfully. This means that the expected hexadecimal code was returned by the device on the first attempt, or that the error handler operation was able to recover and execute successfully.

When the status flag is “0″ it indicates that the operation failed.

In all cases, the hexadecimal code returned for the initial command (not the error handler) will be in the “return” attribute.

Use JSON for a custom device operation:

Whenever a custom action is invoked via monitor_remote JSON, custom will be used for action type, while the value will be a user-defined string.

For example:

{
    "rc": {
        "version": "1",
        "id": "1",
        "action": "device_operation",
        "name": "custom",
        "value": "OPEN"
    }
}

The received JSON would be:

{
    "rc": {
        "device_operation": {
            "name": "custom",
            "value": "OPEN",
            "status": "1",
            "return": "1415BF4478"
        },
        "version": "1",
        "id": "1"
    }
}
RS-232 – JSON Parameters
Parameter Description
id Contains the identifier of the request.
version The version is always 1.
action The kind of action to be taken, in this case device_operation.
name The name of the operation/action type. Default examples include set_volume and set_brightness. Note: If referring to a custom action, this value is custom.
value The value of the action type, according to your device’s settings. For example, you could configure set_volume to a value of “35”.
ActionScript 2.0 Sample

You can use Flash to set the volume of your device:

// Start ActionScript 2.0
var theSocket:XMLSocket = new XMLSocket();
theSocket.onConnect=function() {
theSocket.send(new XML(" action=\"device_operation\"
name=\"set_volume\"
value=\"35\" />\r\n\r\n"));
}
theSocket.onXML=function(myXML) {\
// XXX: parse and use the returned XML here
trace(myXML);
theSocket.close();
}
theSocket.connect("localhost", 2324);