Home

PWng Application API (PWAA)

Planeworld Next Generation uses JSON-RPC 2.0 for communication via websocket. For details of the JSON-RPC communication protocol, have a look at

• a general description: JSON-RPC Wikipedia
• the specification: JSON-RPC 2.0 Specification

Server-Client Relationship

For this section it is important to understand the relationship between PWng Application API (PWAA) and JSON-RPC communication protocol.

• JSON-RPC is a client-server communication that is independent of the underlying protocol. The client may send requests or notifications to the server. The server will respond with a result when getting a request. In case of a simple notification, there is no response.
• PWAA is build as an application protocol on top of JSON-RCP. It is important to understand, that PWAA-server and PWAA-client may both act as JSON-RPC-server and JSON-RPC-client. This allows for peer-based communication and the implementation of a publish-subscribe model.

The following table shows JSON-RPC utilisation for subscriptions, publications, and commands on PWAA layer:

Act as	PWAA-client	PWAA-server
	subscribe / unsubscribe	acknowledge
JSON-RPC-client	request	-
JSON-RPC-server	-	result
	command	response
JSON-RPC-client	request	-
JSON-RPC-server	-	result
	-	publish
JSON-RPC-client	-	notification
JSON-RPC-server	-	-

Subscriptions and Commands

There are two different types of pwng-client-side JSON-RPC-requests, commands and subscriptions. Commands are single JSON-RPC-requests, that will lead to an answer (JSON-RPC-result/-error) from pwng-server. Subscriptions will also get a response, signaling if subscription succeeded, but trigger frequent updates from pwng-server. These updates are sent as JSON-RPC-notifications.

Commands and subscriptions as defined in the following paragraphs are specified in the method field of the JSON-RPC-request.

Commands always start with the prefix cmd_ while subscriptions are prefixed by sub_ / uns_.

Commands

For now, there are four commands:

• cmd_accelerate_simulation <factor>
• cmd_start_simulation
• cmd_stop_simulation
• cmd_shutdown

Subscriptions

Subscription topics are

• prefixed with sub_ and uns_
• suffixed with update frequency, which is
  • _evt: event-based
  • _s01: each 0.1s
  • _s05: each 0.5s
  • _s1: each 1s
  • _s5: each 5s
  • _s10: each 10s

Description of subscription topics are shown in the following table:

topic	description	evt	s01	s05	s1	s5	s10
sub_galaxy_data	subscribe to galaxy data, currently, the galaxy is only transmitted once and stays static	x	-	-	-	-	-

Galaxy Examples