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:
Schematic API, and
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