7. Typhoon HIL RPC API

RPC (Remote Procedure Call) is an interprocess communication technique that allows two independent processes to communicate. RPC is most commonly used to create distributed client/server programs where:

  • client is a process (program or task) that requests the service provided by another program, and
  • server is a process (program or task) that provides the service (responds to the requests from a client).

Typhoon HIL’s RPC API allows you to write custom APIs in any language you want as long as it is supported by ZMQ [1] library.

7.1. Message format

Messages exchanged between the client and the server side are compatible with the JSON-RPC protocol [2].

Request message contains following members:

  • api - a string specifying the version of the Typhoon HIL RPC API.
  • jsonrpc - a string specifying the version of the JSON-RPC protocol. MUST be exactly “2.0”.
  • method - a string containing the name of the method to be invoked.
  • params - a list or dictionary of parameter values to be used during the invocation of the method. This member is optional.
  • id - an identifier established by the client. It can be either a string or an integer.

Response message contains following members:

  • jsonrpc - a string specifying the version of the JSON-RPC protocol. MUST be exactly “2.0”.
  • result - this member exists only if method is invoked and finished successfully.
  • error - this member exists only if error occurred during the method invocation or execution.
  • warnings - this member exists only if warnings occurred during the method execution.
  • id - an identifier that must be the same as the value of the id member in the request.

For more detailed information about message formats, check JSON-RPC specification [3].

7.2. Examples

Following examples illustrate how you can use Typhoon HIL RPC API.

7.2.1. Example 1

This example shows how load method can be invoked.

import zmq

context = zmq.Context()
req_socket = context.socket(zmq.REQ)
# Connect with the server
# In this example we assume that the server listens on the port 51357.
# To always get the correct port value, read settings.conf file that is located
# at the c:\ProgramData\typhoon.
req_socket.connect("tcp://localhost:51357")

# Request message
message = {
    "api": "1.0",
    "jsonrpc": "2.0",
    "method": "load",
    "params": {"filename": "abs_path_to_the_model"},
    "id": 1
}

req_socket.send_json(message)
response = req_socket.recv_json()

7.2.2. Example 2

This example shows how compile method can be invoked.

import zmq

context = zmq.Context()
req_socket = context.socket(zmq.REQ)
# Connect with the server
# In this example we assume that the server listens on the port 51357.
# To always get the correct port value, read settings.conf file that is located
# at the c:\ProgramData\typhoon.
req_socket.connect("tcp://localhost:51357")

# Request message
message = {
    "api": "1.0",
    "jsonrpc": "2.0",
    "method": "compile",
    "params": {},
    "id": 1
}

req_socket.send_json(message)
response = req_socket.recv_json()

7.2.3. Example 3

This example shows how to send multiple requests at once.

import zmq

context = zmq.Context()
req_socket = context.socket(zmq.REQ)
# Connect with the server
# In this example we assume that the server listens on the port 51357.
# To always get the correct port value, read settings.conf file that is located
# at the c:\ProgramData\typhoon.
req_socket.connect("tcp://localhost:51357")

# Request message
message = [
    {
        "api": "1.0",
        "jsonrpc": "2.0",
        "method": "load",
        "params": {"filename": "abs_path_to_the_model"},
        "id": 1
    },
    {
        "api": "1.0",
        "jsonrpc": "2.0",
        "method": "compile",
        "params": {},
        "id": 1
    }
]

req_socket.send_json(message)
response = req_socket.recv_json()
print("Great success!")
[1]ZMQ: http://zeromq.org/
[2]JSON RPC: http://www.jsonrpc.org/
[3]JSON RPC: http://www.jsonrpc.org/specification