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. Usage¶
Typhoon HIL RPC API can be used for following APIs:
- HIL API,
- Schematic API, and
- PV generator API.
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 by default is located at: C:\ProgramData\typhoon.
7.3. Examples¶
Following examples illustrate how you can use Typhoon HIL RPC API.
7.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, 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.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, 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.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, 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 |