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

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

8.2. Usage

Typhoon HIL RPC API can be used for following APIs:

For the full list of available methods, check the documentation of before-mentioned APIs. Each API is using different port number. Port numbers are defined in the settings.conf file, which is located at the API version-specific folder at %APPDATA%\typhoon-api (i.e. for API version 1.6.0, that folder is %APPDATA%\typhoon-api\1.6.0).

8.3. Examples

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

8.3.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, follow instructions from `Usage`
# section.
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()

8.3.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, follow instructions from `Usage`
# section.
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()

8.3.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, follow instructions from `Usage`
# section.
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