From SpinetiX Support Wiki

(Redirected from Remote procedure call)
Jump to: navigation, search

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


RPC stands for Remote Procedure Call, which is a kind of request–response protocol, where a client sends a request message to a dedicated interface of the HMP server to execute a specified procedure with supplied parameters and the HMP server sends a response back to the client, either to acknowledge or to signal an error.

The RPC API allows controlling the player, both when it can be directly accessed (through direct RPC calls within the same network) and also when it is not directly accessible (through indirect RPC calls via an RPC Concentrator).

The RPC API was added in 2.2.2 release of firmware and it is based on JSON-RPC protocol over HTTP using POST calls. On HMP300 and HMP350 devices, the RPC API can also be accessed using a secured URL (HTTPS).

RPC commands

The following RPC requests calls are accepted by the HMP:

RPC command From Notes
add_pull_action 2.2.3 Sends a Pull Mode action to be executed by the HMP.
firmware_update 2.2.0 Starts a process of firmware update from SpinetiX server in the background. A handle is returned that could be used with firmware_update_status call.
firmware_update_status 2.2.0 Returns the status of a previously started firmware update process.
get_config 2.2.3 Returns the device configuration, similar to the configuration backup feature.
get_info 2.2.0 Returns some basic info for the device, such as: serial number, name, model, operation mode, firmware version, firmware status, up time, temperature, storage etc.
reset 4.4.0 Resets the player to factory default settings or any of the following: user content, network cache data, web storage data, internal clock calibration, logs.
restart 2.2.0 Initiates a clean restart of the device, one minute after the call is received.
set_config 2.2.3 Sends a configuration string to be applied onto the HMP.
set_password 2.2.0 Sets or removes the password for an user on the HMP.
shutdown 2.2.6 Initiates a clean shutdown of the device, one minute after the call is received.
webstorage_cmpxchg 3.1.0 Sets the value of one or more items from the web storage; if an expected value is passed, the item is modified only if its current value matches the expected value.
webstorage_get 3.1.0 Gets the value of one or more items from the web storage.
webstorage_list 3.1.0 Gets the list of items currently available in the web storage.
webstorage_remove 3.1.0 Removes one or more items from the web storage.
webstorage_set 3.1.0 Sets the value of one or more items from the web storage.
Note Note:
The webstorage_*** commands don’t apply to HMP300 and DiVA.

Direct RPC calls

Direct RPC calls can be used to control the player when it can be directly accessed over the HTTP protocol. To send an RPC command to the device, the client must use a POST request, having the content type set to “application/json” and formatted according to the JSON-RPC protocol.


The RPC API offers the following endpoint: POST http(s)://HMP_address/rpc

Note Note:
HTTP Secure can only be used with HMP350, HMP300, and DiVA players.

Call body

The request is a single object serialized using JSON, containing three properties:

  • method - a String containing the name of the RPC command to be invoked.
  • params - an Array of objects to pass as arguments to the method.
  • id - the request ID, used to match the response with the request that it is replying to; this can be of any type.

For instance to send a restart command, the following POST request must be done:

POST /rpc HTTP/1.0
Host: spx-hmp-001d50001001.local
Content-Type: application/json


Call response

The response will be a content of type “application/json” containing a single object serialized using JSON, containing three properties:

  • result - the object that was returned by the invoked method; this must be null in case there was an error invoking the method.
  • error - an Error object if there was an error invoking the method; it must be null if there was no error.
  • id - this must be the same id as the request it is responding to.

If the call above is successful, the response would be the following:

HTTP/1.1 200 OK
Content-Type: application/json


Direct RPC calls using AJAX

AJAX calls can be employed within web pages to send RPC commands. If the script is loaded from the player content server, then the authorization is done when logging onto the player. If the script is located on another host (CORS), then you need to manually enter the credentials in the browser's pop-up dialog when asked or include the credentials through the "Authorization" header. Furthermore, to protect the player against CSRF when using CORS, the spx-api-key query string parameter must be appended to the end-point, as following:


where {rpcApiKey} is the API Key configured on that player, either from Control Center, under Advanced Applications > RPC Security section, or by using the <rpc-api-key> configuration tag.

Note Notes:
  • CORS (cross-origin resource sharing) was enabled on the player side in firmware 3.0.5, thus allowing sending RPC commands from simple AJAX clients (e.g., HTML pages, REST clients, etc.).
  • CSRF (Cross-site request forgery) protection was added in firmware 4.2.0 / 3.4.0.
  • The support for the "Authorization" header was added in firmware 4.5.0.
  • It is possible to configure manually the same API key for different devices, so that the same AJAX call can be used on all of them.

You can send a restart command to the player using the following jQuery AJAX call :

const rpcApiKey = 'sample-ff5b-46c8-acdc-d356b71f5f0f',
      rpcObject =  { method: 'restart', params: [ ], id: 1 },
      authorization = 'Basic ' + btoa(login + ':' + password),
      url = '' + rpcApiKey ;

    type: 'POST',
    url: url,
    contentType: 'application/json', 
    beforeSend: function (xhr){
          xhr.setRequestHeader('Authorization', authorization);
          xhr.withCredentials = true;    // necessary for CORS 
    data: JSON.stringify( rpcObject )
}).done( function( data ) {
    if ( !data.error ){
        alert('The player is restarting.');

RPC Concentrator

RPC Concentrator is a server application that collects data from multiple players through HTTP requests. It can be used for two purposes:

  • Receiving notifications from the player - this enables monitoring of restarts and having a heartbeat of the devices.
  • Sending RPC commands to devices behind firewalls or NAT devices.

The RPC Concentrator settings can be configured on HMP Control Center from

RPC notifications

The following RPC notifications are sent by the HMP to the configured RPC concentrator:

RPC notification From Notes
info 3.1.0 This can be used to return the same information as with the get_info call at predefined intervals.
ready 2.2.0 A heartbeat-like notification sent each time the player contacts the RPC concentrator. It can convey the response to previous RPC calls back to the RPC concentrator.
restarted 2.2.0 Sends a notification upon a player restart, containing the time at which the player restarted.
pull_status 3.0.0 Sends a notification to the RPC concentrator when a Pull Mode action is completed.
Note Note:
The serial number of the player is included within each notification message.

Indirect RPC calls

Indirect RPC calls are needed when the player is behind a firewall or a NAT, so the RPC transaction needs to be initialized by the player itself.

The player starts the transaction by sending a ready notification to the RPC concentrator, which can send a RPC command back to the player by adding that command inside the body of the HTTP reply. If so, the player will execute the RPC command and send its result within the next ready notification. The RPC concentrator may then issue a new RPC command in the same manner. And so on.

Server-side application samples

Also check the sample PHP scripts for Pull Mode used for managing the content displayed on the HMP.

RPC Server

SpinetiX is providing a server-side application (written in PHP) for managing and testing RPC functionality of HMP devices. Its purpose is to serve as an example and to guide the implementation of an RPC pull mode server for HMP devices.

Note Note:
Make sure to check the README file before getting started!

HMP Monitoring Server

SpinetiX is providing a server-side application for managing the configuration and monitoring the status of HMP devices. This example uses an RPC Concentrator and the Pull mode to manage devices that are not on the local subnet. Its purpose is to serve as an example and to guide the implementation of an HMP monitoring application.

Note Note:
Make sure to check the README file before getting started!

HMP Management Server

SpinetiX is providing a server-side application for managing HMP devices in direct mode. This example uses direct RPC calls, info XML and the Snapshot. Its purpose is to serve as an example for building an application to manage HMP devices that are on the local network.

Note Note:
Make sure to check the README file before getting started!

Inline RPC

Since firmware 3.0, it is possible to specify RPC commands directly inside the ICS file controlling the Pull Mode. For that, simply add an event where the event summary (title, subject) is “inline-rpc” and the event description contains the RPC command to be executed.

Note that the HMP must be running at the starting time of the inline-rpc event for the RPC command to be executed. With other words, if the HMP (re)boots somewhere during the event duration, the RPC command will not be (re-)executed.

For instance, to trigger a restart of the HMP every night at 1 am, the event would look like this:

PRODID:-//Spinetix.com/NONSGML Spinetix Control Center//EN 
DESCRIPTION: {"method":"restart","params":[],"id":1} 

RPC Errors

400 Bad Request
When sending and RPC command to the HMP a 400: Bad Request error will be received in the following cases:

  • A GET request is used to access the /rpc page (i.e. the /rpc page is opened in a web browser).
  • The Content-Type is not set to application/json.
  • The content of the POST request is empty or is not a valid JSON string.
  • The POST request is made using JavaScript code - this is not working since the JavaScript code is executed locally and therefore not complying with the Same origin policy. More explicitly, your browser will actually make an OPTIONS request first, instead of the POST request, to which the HMP will respond with a 400 error.

401 Unauthorized
In case the administrative access is password-protected, the Digest authentication must be used for direct RPC commands (otherwise these will fail with a 401 HTTP error). An alternative is to use indirect RPC calls instead.


Remotely restart the player

The restart command can be used to remotely restart the player.

{ "method":"restart",
  "id": 1

Remotely change the player configuration

The set_config command can be used to set a configuration (partial or complete) onto the player. For instance:

{ "method":"set_config",
  "params": [ { 
      "xmlconfig": "<?xml version=\"1.0\"?><configuration version=\"2.0\"><screen-aspect-ratio>16:9</screen-aspect-ratio><display-orientation>rotateRight</display-orientation><enable-audio>yes</enable-audio><device-name>office-screen</device-name><reboot/></configuration>" 
  } ],
  "id": 2

Update the content remotely through Pull mode

The add_pull_action command can be used to trigger the update of the HMP content in a pseudo-push scenario through Pull Mode - the following command updates the content of the HMP with a demo project from SpinetiX server:

{ "method":"add_pull_action",
  "params":[ { 
    "type": "publish", 
    "uri": "http://demo.spinetix.com/sample_projects/Office/spx-listing.xml"
  } ],
  "id": "get office content"

See also

This page was last modified on 13 July 2020, at 21:19.