Serial port protocol file

This page is related to the serial port page.

Serial Port Protocol Files Documentation

Release date: January 15, 2014

Applies to: HMP400/W, HMP350, legacy players

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.

Notes:

A typical way to trigger a serial command is by using one of the screen control widgets included in Elementi.
An alternative way to do the same thing without an FSM file, is to use the JavaScript COM API or the sendComPort function.
In case the serial communication doesn't work as expected configure the HMP to log more details regarding the com events.

Built-in protocol files

The HMP comes with four protocol files: three for LG LF65, Panasonic plasma and Sharp Aquos screens, and one for GPS data integration with devices compatible with the NMEA-0183 standard.

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

the HMP350 built-in protocol tool (found on the Peripherals page) or
the FSM protocol file creation tool (found on SpinetiX website - you need to be logged into your account to be able to use it).

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 below 2.2.2, the NULL character () must be written as ＀ instead of %c{0}.
- The exceptions to 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' 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

Sample FSM protocol file

Version: 1.0 (revision history)

Release date: 2012-10-26

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.

<?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

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

NEC (generic)

NEC E654/E554/E464/E424/E224

Samsung ME46A

Sony (generic)

Sony VPL-FHZ66

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 and HMP400/HMP400W with DSOS license, follow these steps:

Open HMP Control Center and go to Peripherals > Serial Port Automation page.
Select "Advanced" from the drop-down box labeled "Settings". This activates the advanced settings.
Click on the "Add Protocol File" button and upload your protocol file.
Select the radio option from the "Active" column, next to your protocol file.
Click the "Apply" button and then on the "Restart Now" button to apply the changes.