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 feature of the HMP allows for remote management of the HMP, regardless of having direct access to the player (i.e. direct calls within the same network) or not (i.e. indirect calls using 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:

  • add_pull_action - sets a Pull Mode action to be executed by the HMP.(Added in 2.2.3)
  • firmware_update - starts a firmware update process.
  • firmware_update_status - returns the status of a previously started firmware update process.
  • get_config - gets the current configuration of the HMP, similar to the configuration backup feature. (Added in 2.2.3)
  • get_info - returns the HMP device information, such as: serial number, name, model, operation mode, firmware version, firmware status etc.
  • restart - initiates a clean restart of the device.
  • set_config - sets a configuration (partial or complete) on the HMP. (Added in 2.2.3)
  • set_password - sets a new password for one of the three default users of the HMP.
  • shutdown - initiates a clean shutdown of the device. (Added in 2.2.6)
  • webstorage_cmpxchg - checks the value of one or more items from the web storage and, if successful, sets the new value(s). (Added in 3.1.0)
  • webstorage_get - gets the value of one or more items from the web storage. (Added in 3.1.0)
  • webstorage_list - gets the list of items currently available in the web storage. (Added in 3.1.0)
  • webstorage_remove - removes one or more items from the web storage. (Added in 3.1.0)
  • webstorage_set - sets the value of one or more items from the web storage. (Added in 3.1.0)
"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.).
"Technical note"
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 notifications

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

  • info - send a get_info notification. (Added in 3.1.0)
  • ready - sends a ready-status notification upon configuration.
  • restarted - sends a notification upon a restart.
  • pull_status - send a notification to the RPC concentrator when a pull action is complete. (Added in 3.0.0.)

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

Server-side application samples

Also check the Pull Mode php servers for sample to manage 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.

  • Make sure you read 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.

  • Make sure you read 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.

  • Make sure you read the README file before getting started!

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 May 2017, at 16:06. This page has been accessed 14,155 times.