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

Introduction

RPC stands forRemote Procedure Call, which is a kind of request–response protocol, where a client sends a request message to a dedicated interface of theplayer asking it to execute a specified action according to the supplied parameters, and the player sends a response back to the client, either to acknowledge or to signal an error. The actions that can be executed on the player are various and can range from simple ones, such as reboot or status request, to more complex ones, such as updating the firmware, configure the player, or pulling content from a server.

The player can be controlled through the RPC API, both when it can be directly accessed (direct RPC requests within the same network) and when it is not directly accessible (through indirect RPC calls via anRPC Concentrator), with minimal delay.

The RPC API was added infirmware 2.2.1 - further changes and improvements of the RPC API were added in subsequentfirmware releases.

Note:

Forlegacy players, the last document revision applying isversion 2.3.

The RPC mechanism

The RPC mechanism implemented on the SpinetiX players is based onJSON-RPC v1.0, a lightweight remote procedure call protocol where data is serialized using JSON.

The general RPC mechanism consists of two peers establishing a data connection, one peer being a SpinetiX player and the other being a client (desktop or web application) or a server application (RPC Concentrator). During the lifetime of a connection, peers may invoke methods provided by the other peer. To invoke a remote method, a request is sent. Unless the request is a notification, it must be replied to with a response.

On SpinetiX platform, HTTP requests are used as a transport for communicating between peers. The content type must be set to “application/json” and the encoding should always be UTF-8. Only one RPC command is accepted per HTTP request / response.

Command

An RPC command (remote method) is invoked by sending an HTTP request to the player RPC service or as a response to a player notification.

The request body is a JSON-serialized single object, with three properties:

• method ⇾ aString containing the name of the RPC command to be invoked.
• params ⇾ anArray of parameters to pass as arguments to the method or an empty array (i.e.,[]) otherwise.
• id ⇾ aString orNumber ID, useful for request-response matching, as it is automatically added into the response.

The RPC commands can be sent from any network location which can open a connection to the player or from the configured RPC concentrator.

Response

When the method invocation completes, the player will reply to the initial HTTP request with the result of the command or with an error.

The response body is a JSON-serialized single object, with these properties:

• result ⇾ AnObject returned by the invoked method ornull in case of an error.
• error ⇾ AString with the error summary ornull otherwise.
• id ⇾ The ID of the initial request it is responding to.
• errorDetails ⇾ An Object containing information (code anddata) about the error ornull otherwise.Added in firmware 4.7.1.

In case of an error executing the command, the result property is set tonull and the error property contains an explicative message of the error encountered, for instance: “No such method (reboot)”. Starting with firmware 4.7.1, additional information about the error may be provided under the errorDetails property.

Notification

The notifications are HTTP POST requests sent by the player to the configuredRPC Concentrator. The server is not expected to return an answer, nevertheless, it can respond and add an RPC command in the body of the response – this is useful when the RPC transaction needs to be initialized by the player behind a firewall or a NAT device.

The notification body is a JSON-serialized single object, with three properties:

• method ⇾ aString containing the name of the RPC notification.
• params ⇾ anArray of one or more objects containing different data for the RPC Concentrator.
• id ⇾ This is always set tonull.

Every notification includes the player serial number within the parameters, so that the server can easily identify the originator of a notification.

How to use this API

There are different ways to send RPC commands to the player:

• Via an HTTP POST (direct RPC):

  A client can send an RPC command directly to the player via an HTTP POST request. This method is straightforward to implement but requires the player to be reachable over network from the client sending the command. In this context the player is the RPC server.

• Via theready notification (indirect RPC):

  The player sends this notification to a designated server, theRPC Concentrator, at regular intervals – the server can chain an RPC command within the response to that notification. This method requires implementing an RPC Concentrator, but it has the advantage that RPC can be used even when the player is behind firewalls or NAT, since the communication is started by the player.

• Via Pull Mode (ICS inline RPC):

  The RPC command is specified within an event included in the ICS file controlling the Pull Mode mechanism.

Direct RPC

Direct RPC is employed when the player can be directly accessed over HTTP. Centralized tools, being desktop clients or web applications, can be used to perform different actions on the player, in addition or even instead of using the built-inControl Center interface.

Endpoint

POSThttp(s)://Player_address/rpc

To send an RPC command to the player, the client must issue aPOST request, having the content type set to “application/json” and being formatted according to the JSON-RPC protocol.

Example

For instance, to send arestart command, the followingHTTP POST request must be done:

POST /rpc HTTP/1.0Host: spx-hmp-001d50001001.localContent-Type: application/json{"method":"restart","params":[],"id":1}

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

HTTP/1.1 200 OKContent-Type: application/json{"result":{},"error":null,"id":1}

Authentication

By default, the access to the RPC endpoint is protected and the RPC client must authenticate itself by providing thecredentials of a user with appropriate rights – that user can be defined withinControl Center or by using an alternative method (Configuration API, RPC API). Note that most RPC methods require admin rights, only few accepting lower rights.

HTTP Basic andTLS-SRP authentication methods are supported.

Using AJAX

AJAX calls can be employed within web pages to send RPC commands. If the script is loaded from theplayer 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 (see the example below).

To protect the player against CSRF when using CORS, thespx-api-key query string parameter must be appended to the end-point.

POSThttp(s)://Player_address/rpc?spx-api-key={rpcApiKey}

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

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 infirmware 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.

Example

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

constrpcApiKey='sample-ff5b-46c8-acdc-d356b71f5f0f',rpcObject={method:'restart',params:[],id:1},authorization='Basic '+btoa(login+':'+password),url='http://172.21.1.137/rpc?spx-api-key='+rpcApiKey;$.ajax({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.');}});

Indirect RPC

Indirect RPC is needed when the RPC transaction needs to be initialized by the player itself – typical usage is when the player is behind a firewall or a NAT.

In this case, the player starts the communication with the server by sending a ready notification to theRPC Concentrator. If an RPC command is required to be executed by the player, the RPC concentrator puts that RPC command in the body of the HTTP reply. The player will execute that RPC command and then send another ready notification to the RPC concentrator with the result. The RPC concentrator may chain another RPC command by including it in the HTTP reply, and so forth

Inline RPC

Inline-RPC is an extension to thePull Mode API to support RPC commands inside the ICS file controlling thePull Mode.

 

See the full article about theInline RPC.

API methods

RPC commands

Note:

Thewebstorage_*** commands can be used to interact with the data stored in thelocalStorage (and implicitly with the associatedShared Variables).These commands don’t apply toHMP300 andDiVA.

RPC notifications

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

Note:

The serial number of the player is included within each notification message.

Postman collection

This section is for people familiar withPostman application.

The "SpinetiX RPC API" postman collection contains all the RPC commands and some examples of usage.

1. Download the archive on the right and unzip it somewhere.
2. Import the .json file into Postman.
3. Click on the 3-dot button of the "SpinetiX RPC API" collection and select edit.
4. Go to "Authorization" tab and change the default username and password if needed.
5. Go to "Variables" tab and change the "base_url" variable to use yourplayer address.
6. Click "Update" button.

Examples

Remotely restart the player

Therestart command can be used to remotely restart the player.

{"method":"restart","params":[],"id":1}

Remotely change the player configuration

Theset_config command can be used to set aconfiguration (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

Theadd_pull_action command can be used to trigger the update of the HMP content in a pseudo-push scenario throughPull 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"}

RPC Concentrator

An RPC Concentrator is a server application that collects data from players and dispatches RPC commands to players through HTTP requests. It can be used for two purposes: to monitor players and to sendRPC commands to players, especially useful in the case those players are behind firewalls or NAT devices.

The RPC Concentrator settings can be configured fromControl Center, under

• Advanced Applications > RPC Concentrator page forHMP350,HMP300, andHMP400/HMP400W withWIDGETS Feature Set (or higher);
• Content Settings > Pull Mode tab forHMP200,HMP130, andHMP100 devices.

It can also be configured with an ICS file - for more details, seePull Mode page.

Application samples

Also check thesample 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:

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 thePull 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:

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 theSnapshot. Its purpose is to serve as an example for building an application to manage HMP devices that are on the local network.

Note:

Make sure to check the README file before getting started!

RPC Errors

400 Bad Request

When sending an RPC command to the player, a 400 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 toapplication/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 theSame 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

The access to the RPC endpoint is protected and the RPC client must authenticate itself by providing the credentials of a user with appropriate rights, otherwise a 401 error will occur. An alternative is to use indirect RPC calls instead.

API deprecation

The technical documentation at thetop of the page applies toHMP400,HMP400W,HMP350,HMP300,DiVA, andthird-party players withDSOS™ support. ForHMP200 and other legacy players, seerevision 2.3 of the document.

See also

• Status API
• Configuration API

• APIs
• Network