RPC API
From SpinetiX Support Wiki
Summary information and/or updates to the documentation can be found on this page.
Introduction
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 player 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 an RPC Concentrator), with minimal delay.
The RPC API was added in firmware 2.2.1 - further changes and improvements of the RPC API were added in subsequent firmware releases.
Note:The RPC mechanism
The RPC mechanism implemented on the SpinetiX players is based on JSON-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⇾ a String containing the name of the RPC command to be invoked. params⇾ an Array of parameters to pass as arguments to the method or an empty array (i.e.,[]) otherwise.-
id⇾ a String or Number 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⇾ An Object returned by the invoked method ornullin case of an error. -
error⇾ A String with the error summary ornullotherwise. -
id⇾ The ID of the initial request it is responding to. -
errorDetails⇾ An Object containing information (codeanddata) about the error ornullotherwise. Added in firmware 4.7.1.
In case of an error executing the command, the result property is set to null 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 configured RPC 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⇾ a String containing the name of the RPC notification. params⇾ an Array 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 the
readynotification (indirect RPC):- The player sends this notification to a designated server, the RPC 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-in Control Center interface.
Endpoint
POSThttp(s)://Player_address/rpc
- To send an RPC command to the player, the client must issue a
POSTrequest, having the content type set to “application/json” and being formatted according to the JSON-RPC protocol.
Example
For instance, to send a restart command, the following HTTP POST request must be done:
POST /rpc HTTP/1.0
Host: spx-hmp-001d50001001.local
Content-Type: application/json
{"method":"restart","params":[],"id":1}
If the call above is successful, the response would be the following:
HTTP/1.1 200 OK
Content-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 the credentials of a user with appropriate rights – that user can be defined within Control 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 and TLS-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 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 (see the example below).
To protect the player against CSRF when using CORS, the spx-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, under Advanced 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 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.
Example
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 = '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 the RPC 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 the Pull Mode API to support RPC commands inside the ICS file controlling the Pull Mode.
API methods
RPC commands
| RPC command | Added in | Mod. in | 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 | 4.7.1 | 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 | 4.8.2 | Returns device info, such as: serial number, name, model, operation mode, firmware version, firmware status, up time, temperature, storage, etc. |
reset |
4.4.0 | 4.7.2 | 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 | 2.2.6 | 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 player. | |
set_password
|
2.2.0 | 4.0.0 | Sets or removes the password for an user on the player. |
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. | |
wifi_connect |
4.6.0 | Instructs the player to connect to the provided Wi-Fi network. | |
wifi_disconnect |
4.6.0 | Instructs the player to disconnect from the Wi-Fi network. | |
wifi_get_info |
4.6.0 | Returns information about the Wi-Fi networks configured on the player. | |
wifi_scan |
4.6.0 | Triggers a scan for Wi-Fi networks. |
Note:webstorage_*** commands can be used to interact with the data stored in the localStorage (and implicitly with the associated Shared Variables). These commands don’t apply to HMP300 and DiVA.RPC notifications
The following RPC notifications are sent by the HMP to the configured RPC concentrator:
| RPC notification | Added in | Mod. in | 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 | 3.1.0 | Sends a notification to the RPC concentrator when a Pull Mode action is completed. |
Note:Postman collection
This section is for people familiar with Postman application.
The "SpinetiX RPC API" postman collection contains all the RPC commands and some examples of usage.
- Download the archive on the right and unzip it somewhere.
- Import the .json file into Postman.
- Click on the 3-dot button of the "SpinetiX RPC API" collection and select edit.
- Go to "Authorization" tab and change the default username and password if needed.
- Go to "Variables" tab and change the "base_url" variable to use your player address.
- Click "Update" button.
Examples
Remotely restart the player
The restart command can be used to remotely restart the player.
{
"method":"restart",
"params":[],
"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"
}
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 send RPC commands to players, especially useful in the case those players are behind firewalls or NAT devices.
The RPC Concentrator settings can be configured from Control Center, under
- Advanced Applications > RPC Concentrator page for HMP350, HMP300, and HMP400/HMP400W with DSOS WIDGETS license (or higher);
- Content Settings > Pull Mode tab for HMP200, HMP130, and HMP100 devices.
It can also be configured with an ICS file - for more details, see Pull Mode page.
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: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: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: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 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
- 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 the top of the page applies to HMP400, HMP400W, HMP350, HMP300, DiVA, and third-party players with DSOS™ support. For HMP200 and other legacy players, see revision 2.3 of the document.