RPC API

From SpinetiX Support Wiki

(Redirected from RPC)
Jump to: navigation, search
"Documentation"

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

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

Direct RPC calls

Direct RPC calls can be used to control the player when it can be directly accessed through POST requests over the HTTP protocol.

To send an RPC command to the device, the client needs to send a POST request, having the content type set to “application/json” and formatted according to the JSON-RPC protocol, to http://HMP_address/rpc .

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.

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.


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

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

If successful, the response would be the following:

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

{"result":{},"error":null,"id":1}

Direct RPC calls using AJAX calls

AJAX calls can be used to send direct RPC commands to the player.

For instance, you can send a restart command to the player using a jQuery AJAX call :

$.ajax( {
    type: "POST",
    url: "http://HMP_address/rpc?spx-api-key=[rpc-api-key]",
    contentType: 'application/json', 
    xhrFields: { withCredentials: true },    // this is necessary when using CORS 
    data: JSON.stringify( {
        method: "restart", params: [ ], id: 1
    } )
}).done( function( data ) {
    if ( !data.error ){
        // device is restarting
     }
});

where [rpc-api-key] must be replaced by the actual RPC API key configured on the HMP.


"Technical note"
  • Since firmware 3.0.5, cross-origin resource sharing (CORS) has been enabled onto HMP devices for RPC commands, thus allowing sending RPC commands from simple AJAX clients (e.g., HTML pages, REST clients etc.).
  • Since firmware 4.2.0 / 3.4.0, and rpc-api-key is now need to perform RPC commands from a domain which is different from the device itself to protect against CSRF (Cross-site request forgery) attacks.

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:

BEGIN:VCALENDAR 
VERSION:2.0 
PRODID:-//Spinetix.com/NONSGML Spinetix Control Center//EN 
BEGIN:VEVENT 
UID:14d64d53-a926-4a71-848d-c78452b345fe 
DTSTART:20110101T010000 
DTEND:20110101T013000 
SUMMARY:inline-rpc 
DESCRIPTION: {"method":"restart","params":[],"id":1} 
RRULE:FREQ=DAILY;WKST=SU 
END:VEVENT 
END:VCALENDAR

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.

Examples

Update the content using Pull mode

  • The add_pull_action() command can be used to trigger the update of the HMP content in a pseudo-push scenario. Configure the Pull mode to use a remote RPC concentrator and from this one send the following command to update / replace the content of the HMP with a demo project from SpinetiX server:
    add_pull_action( { type: 'publish', uri: 'http://demo.spinetix.com/pullmode/SpinetiX_Hotel.xml' } );

See also

This page was last modified on 8 August 2017, at 21:07.