Serial port protocol file

From SpinetiX Support Wiki

Jump to: navigation, search

This page is related to serial port and applies to HMP350, HMP200, HMP130, and HMP100 devices.

"Documentation"
SpinetiX Technical Documentation - Version 3.0.1

Summary information and/or updates to the documentation can be found on this page.

Introduction

The serial port protocol file (.fsm) contains the implementation of a serial port communication protocol and describes the relationship between the action generated from or toward the player and the strings sent via the serial cable. This implementation is described as an XML document representing a finite state machine and associated transitions (this is where the .fsm extension is coming from).

The inputs to this state machine could be:

  • Requests to initiate a new control action, for instance request to power off the display;
  • Characters received on the serial port;
  • Timer expiration.

The outputs could be:

  • Characters sent out to the connected device;
  • Interactive events to be handled by the JavaScript code on the player;
  • Updates of Shared Variables;
  • Logs depending on the input on the serial port.
Note Notes:

How to write a protocol file

To create a simple protocol file that sends one or more commands to the connected device (usually PowerOn and PowerOff), you can use

Both tools are escaping of disallowed characters automatically.

  • For instance, when using this command string: 0!
, the result will be %c{2}0!
 .
  • To get the same result, you can also write the following string: 02 30 21 0D and enable the option "This is a byte string".


For more complex protocol files, you need to write the XML code yourself - the protocol syntax is detailed in the technical documentation. Testing and debugging of protocol files can be done on a PC using the SPP Studio application (currently deprecated).

Special characters

  • When writing the FSM protocol file, some commands might require some special characters (i.e. non-printable characters in ASCII) that have to be entered using either:
    1. %c{decimal_number} syntax or
    2. &#xhexadecimal_number; or &#decimal_number; syntax (i.e. numeric character reference).
  • The characters that are allowed in XML 1.0 can be entered using both syntaxes (though usually the second syntax is preferred).
  • The characters from the C0 control set (i.e. from � to  - respectively from � to  as decimal codes) must be entered using the only %c{decimal_number} syntax.
    • For instance, use %c{0} to write the NUL (Null, �) character or %c{2} to write the STX (Start of text, ) character.
      • Note that for players with the firmware version 3.0.0 and 3.0.1, the NULL character is not sent (this is a known issue).
      • Note that for players with the firmware version bellow 2.2.2, the NULL character (�) must be written as ＀ instead of %c{0}.
    • The exceptions of this set are these three characters:
      1. Horizontal Tab ("\t" in ASCII) - can be written as 	 or %c{9}.
      2. Line Feed ("\n" in ASCII) - can be written as 
 or %c{10}.
      3. Carriage Return ("\r" in ASCII) - can be written as 
 or %c{13}.

Sending commands

In many cases, the protocol file is used to send commands to external devices (like TV screens) via RS-232.

The example below can be used to send different commands to the screen:

<?xml version='1.0' encoding='utf-8'?>
<protocol xmlns='http://www.spinetix.com/namespace/1.0/spx' xml:id='test' desc='protocol' startup='start' target='monitor'>
<state xml:id='start'>
  <onStart command='PowerOn' goto='start'>
    <write data='&#xAA;%c{17}&#xFF;%c{1}%c{1}%c{18}'/>
  </onStart>
  <onStart command='PowerOff' goto='start'>
    <write data='&#xAA;%c{17}&#xFF;%c{1}&#xFF00;%c{17}'/>
  </onStart>
  <onStart command='SelectInput' goto='select_input_start'>
  </onStart>
</state>
<state xml:id='select_input_start'>
    <onTest var='$PARAM1' stringEqualTo='DVI1' goto='start'>
      <write data='%c{1}&#x30;&#x41;&#x30;&#x45;&#x30;&#x41;%c{2}&#x30;&#x33;%c{3}&#x71;&#x0d;'/>
    </onTest>
    <onTest var='$PARAM1' stringEqualTo='HDMI1' goto='start'>
      <write data='%c{1}&#x30;&#x41;&#x30;&#x45;&#x30;&#x41;%c{2}&#x31;&#x31;%c{3}&#x72;&#x0d;'/>
    </onTest>
</state>
</protocol>

Receiving commands

An FSM protocol file can be created for listening for commands from the serial port.

  • The example below (which can be downloaded as an .fsm file from the right) updates a shared variable when receiving commands.
  • An advanced example of such a "listening" FSM protocol file is NMEA-0183 protocol file.
Version 1.0 (2012-10-26)
<?xml version="1.0" encoding="utf-8"?>
<protocol xmlns='http://www.spinetix.com/namespace/1.0/spx' target='monitor' startup='start'>
  <state xml:id='start'>
    <onInput match="1" >
      <update name='menu' value='L1' />
    </onInput>
    <onInput match="2" >
      <update name='menu' value='L2' />
    </onInput>
  </state>
</protocol>

Sending and receiving commands

A protocol file can both receive and send commands and it can also update Shared Variables.

The example below updates a variable whose name and content are received via RS232 and sends back an OK message:

 <?xml version="1.0" encoding="utf-8"?>
 <protocol target='switch' startup='start' xmlns='http://www.spinetix.com/namespace/1.0/spx'>
  <state xml:id='start'>
   <onInput match="(var_[a-z]*)=([a-zA-Z0-9]*)&#x0D;&#x0A;" >
    <update name='%s{$1}' value='%s{$2}' />
    <write data='OK %s{$1} set to %s{$2}&#x0D;&#x0A;' />
    <complete status='success' />
   </onInput>
  </state>
 </protocol>

Examples

The following protocols files are already present on the HMP:

These are simple examples of protocol file used mainly to send PowerOn & PowerOff commands:

How to activate a protocol file

Once you have your protocol file, you need to upload it on the player and activate it.

Serial Port Automation - Advanced settings

To do that on the HMP350, follow these steps:

  1. Open HMP Control Center and go to Peripherals > Serial Port Automation page.
  2. Select "Advanced" from the drop-down box labeled "Settings". This activates the advanced settings.
  3. Click on the "Add Protocol File" button and upload your protocol file.
  4. Select the radio option from the "Active" column, next to the your protocol file.
  5. Click the "Apply" button and then on the "Restart Now" button to apply the changes.
Note See also
This page was last modified on 21 September 2018, at 15:22.