JSON-RPC interface#

Besides the SCPI interface, Measmatic offers a JSON-RPC 2.0 interface. It is meant for automation clients that need typed parameters and results, and that want to be notified when a measurement starts or finishes.

The interface must be enabled in the program settings (Enable JSON RPC remote control interface). The default TCP port is 35001 and can be changed in the same settings. In runner mode the interface is always enabled and the port can be overridden with the /jsonrpc-port command-line option.

Measmatic serves one JSON-RPC client at a time. A second client that connects while another one is still connected is accepted only after the first one has disconnected.

Messages#

Messages are exchanged over a plain TCP connection. Every message, in both directions, consists of a header and a JSON-RPC 2.0 body encoded in UTF-8:

Content-Length: <number of bytes of the body>\r\n
\r\n
<body>

Requests from the client to Measmatic use the method names listed below. Parameters are passed either positionally as an array, in the order given in the method description, or by name as an object with the parameter names given in the method description. Methods without parameters take an empty array or omit params.

{"jsonrpc": "2.0", "id": 1, "method": "GetProjects", "params": ["C:\\Measmatic\\Projects"]}

{"jsonrpc": "2.0", "id": 1, "method": "GetProjects", "params": {"projectDirectory": "C:\\Measmatic\\Projects"}}

Every request is answered with a response carrying the same id. Methods without a return value answer with "result": null.

{"jsonrpc": "2.0", "id": 1, "result": ["DiodeTest", "Diodes\\DiodeTest2"]}

If the method fails, the response contains an error object instead of result. The message describes the problem, data contains the exception details.

{"jsonrpc": "2.0", "id": 1, "error": {"code": -32000, "message": "Invalid project file path (Parameter 'projectFile')", "data": {"type": "System.ArgumentException", "message": "...", "stack": "...", "code": -2147024809, "inner": null}}}

Error code	Meaning
-32601	Unknown method name
-32602	Invalid parameters, e.g. missing parameter or a value that cannot be converted
-32000	The method was executed and failed; see `message`

Table: JSON-RPC error codes

Property names of the objects described on this page are case-sensitive and must be written exactly as shown (e.g. TestName, not testName). Enumeration values are transferred as numbers.

Info

Measmatic sends notifications to the connected client on its own. They can arrive at any time, also between a request and its response. A client must therefore read messages until it receives the response with its request id and must not assume that the next message is the response.

With the program setting Log JSON RPC communication (developer mode only) every sent and received message is written to the Measmatic log, which helps when developing a client.

Methods#

Method	Description
Identify	Identification string
GetProjects	List the projects of a directory
LoadProject	Load a project
GetLoadedProject	Loaded project in the form `GetProjects` lists it
GetProjectName	Name of the loaded project
GetProjectFilePath	Absolute file path of the loaded project
GetProjectInputParameters	Input parameters (test UI values) of all tests
SetProjectInputParameter	Set an input parameter of a test
GetProjectOutputParameters	Output parameters with limits of all tests
SetMeasurementDescription	Set a measurement description value
SetSiteInfo	Set the site coordinates for the measured data
Start	Start the execution of the loaded project
Stop	Stop the running execution
GetBin	Last determined sorting bin
RaiseEvent	Call the `on_event` function of the Python tests
ClearPythonStorage	Clear the persistent storage of the Python tests

Table: JSON-RPC methods

Identify#

Description:

Returns a string that identifies the application, including its name and version.

Return value:

Identification string

Example:

{"jsonrpc": "2.0", "id": 1, "method": "Identify"}

Return value example:

{"jsonrpc": "2.0", "id": 1, "result": "ATV,Measmatic,26.1.0.0"}

GetProjects#

Description:

Returns all projects in the given directory, including its subdirectories. The returned paths are relative to the directory and have no file extension, so they can be passed to LoadProject directly when the default project directory is used. A directory that does not exist yields an empty list.

Parameters:

projectDirectory: string. The directory to search. An empty string selects the default project directory. The parameter must be given.

Return value:

Array of project paths

Example:

{"jsonrpc": "2.0", "id": 2, "method": "GetProjects", "params": [""]}

Return value example:

{"jsonrpc": "2.0", "id": 2, "result": ["DiodeTest", "Diodes\\DiodeTest2"]}

LoadProject#

Description:

Loads the given project. The path may be relative to the default project directory or absolute, and may be given with or without the .mmprj extension. The method returns after the project has been loaded. An empty path or a project that cannot be loaded results in an error response.

Parameters:

projectFile: string, e.g. Diodes\DiodeTest2 or C:\Measmatic\Projects\DiodeTest.mmprj

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 3, "method": "LoadProject", "params": ["Diodes\\DiodeTest2"]}

Return value example:

{"jsonrpc": "2.0", "id": 3, "result": null}

GetLoadedProject#

Description:

Returns the currently loaded project in the form GetProjects lists it: relative to the default project directory and without file extension. A project outside the project directory is returned as absolute path.

Return value:

Project path, or null if no project file is loaded

Example:

{"jsonrpc": "2.0", "id": 4, "method": "GetLoadedProject"}

Return value example:

{"jsonrpc": "2.0", "id": 4, "result": "Diodes\\DiodeTest2"}

GetProjectName#

Description:

Returns the name of the currently loaded project, i.e. its file name without extension.

Return value:

Project name, or null if no project file is loaded

Example:

{"jsonrpc": "2.0", "id": 5, "method": "GetProjectName"}

Return value example:

{"jsonrpc": "2.0", "id": 5, "result": "DiodeTest2"}

GetProjectFilePath#

Description:

Returns the absolute file path of the currently loaded project.

Return value:

File path, or null if no project file is loaded

Example:

{"jsonrpc": "2.0", "id": 6, "method": "GetProjectFilePath"}

Return value example:

{"jsonrpc": "2.0", "id": 6, "result": "C:\\Measmatic\\Projects\\Diodes\\DiodeTest2.mmprj"}

GetProjectInputParameters#

Description:

Returns the input parameters of all tests in the currently loaded project. An input parameter is a control of the test UI, identified by the control id and the name of the test. The value is given as a typed value.

Return value:

Array of input parameters

Example:

{"jsonrpc": "2.0", "id": 7, "method": "GetProjectInputParameters"}

Return value example:

{"jsonrpc": "2.0", "id": 7, "result": [{"Identification": "start_voltage", "TestName": "Diode IV", "Value": {"ValueBool": false, "ValueDouble": -1, "ValueDoubleArray": null, "ValueInt": 0, "ValueString": null, "ValueType": 3}}, {"Identification": "points", "TestName": "Diode IV", "Value": {"ValueBool": false, "ValueDouble": 0, "ValueDoubleArray": null, "ValueInt": 101, "ValueString": null, "ValueType": 2}}]}

SetProjectInputParameter#

Description:

Sets the value of a test UI control in the currently loaded project. The test is addressed by its name, the control by its id (see GetProjectInputParameters). The change is applied to the project in memory and is not saved to the project file. An unknown test or a value the control does not accept results in an error response.

Parameters:

parameter: input parameter object. Only ValueType and the value property matching it need to be set in Value.

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 8, "method": "SetProjectInputParameter", "params": [{"TestName": "Diode IV", "Identification": "start_voltage", "Value": {"ValueType": 3, "ValueDouble": -1.5}}]}

Return value example:

{"jsonrpc": "2.0", "id": 8, "result": null}

GetProjectOutputParameters#

Description:

Returns the output parameters of all tests in the currently loaded project together with their units and limits.

Return value:

Array of output parameters

Example:

{"jsonrpc": "2.0", "id": 9, "method": "GetProjectOutputParameters"}

Return value example:

{"jsonrpc": "2.0", "id": 9, "result": [{"Caption": null, "LimitMax": 0.8, "LimitMin": 0.6, "Name": "Vf", "TestName": "Diode IV", "Unit": "V"}, {"Caption": null, "LimitMax": 1E-06, "LimitMin": null, "Name": "Ir", "TestName": "Diode IV", "Unit": "A"}]}

SetMeasurementDescription#

Description:

Sets the value of a measurement description of the currently loaded project. The key is matched case-insensitively. A key that does not exist in the project results in an error response.

Parameters:

descriptionKey: string, e.g. WaferID
value: string, e.g. W-0815

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 10, "method": "SetMeasurementDescription", "params": ["WaferID", "W-0815"]}

Return value example:

{"jsonrpc": "2.0", "id": 10, "result": null}

SetSiteInfo#

Description:

Sets the site coordinates that are stored with the measured data of the following runs. Properties that are not needed can be omitted or set to null.

Parameters:

siteInfo: site info object

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 11, "method": "SetSiteInfo", "params": [{"SiteRow": 2, "SiteColumn": 5, "SubSiteIdx": 0, "SubSiteLabel": "A"}]}

Return value example:

{"jsonrpc": "2.0", "id": 11, "result": null}

Start#

Description:

Starts the execution of the currently loaded project. Existing measurement data is overwritten. The method returns as soon as the execution has been triggered; it does not wait for the execution to complete. The progress is reported through the notifications: wait for OnExecutionFinished or OnExecutionError to detect the end of the execution.

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 12, "method": "Start"}

Return value example:

{"jsonrpc": "2.0", "id": 12, "result": null}

Stop#

Description:

Stops the running execution. The method returns as soon as the stop has been triggered; the OnExecutionFinished notification with WasExecutionStopped set to true signals that the execution has ended.

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 13, "method": "Stop"}

Return value example:

{"jsonrpc": "2.0", "id": 13, "result": null}

GetBin#

Description:

Returns the sorting bin that was determined last. If no bin has been determined yet, the no bin number of the project settings is returned with status Unknown.

Return value:

Bin object

Example:

{"jsonrpc": "2.0", "id": 14, "method": "GetBin"}

Return value example:

{"jsonrpc": "2.0", "id": 14, "result": {"Code": 1, "Description": "Pass", "Status": 1}}

RaiseEvent#

Description:

Calls the on_event function of every Python test in the currently loaded project that defines one, in test plan order from top to bottom. Event names are case-insensitive and are passed to the scripts in lower case. The predefined names are listed in the Events class; any other name may be raised as well. The method returns after all on_event functions have been executed. Not available in runner mode.

Parameters:

eventName: string, e.g. wafer_test_started

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 15, "method": "RaiseEvent", "params": ["wafer_test_started"]}

Return value example:

{"jsonrpc": "2.0", "id": 15, "result": null}

ClearPythonStorage#

Description:

Clears the persistent key-value storage that Python tests access through measmatic.storage.

Return value:

None

Example:

{"jsonrpc": "2.0", "id": 16, "method": "ClearPythonStorage"}

Return value example:

{"jsonrpc": "2.0", "id": 16, "result": null}

Notifications#

Measmatic informs the connected client about the test execution with JSON-RPC notifications. A notification is a message with method and params, but without id, and must not be answered. The params array always contains a single object. Notifications are sent for every execution, no matter whether it was started by the client, from the user interface or by the SCPI interface.

Method	Sent when	Parameter object
`OnExecutionStarted`	The execution of the project or of a single test has started	`IsSingleTestRun`: boolean
`OnTestExecutionStarted`	The execution of a test has started	`TestName`: string
`OnTestExecutionFinished`	The execution of a test has finished	`TestName`: string, `DataTable`: data table of the test
`OnPostprocessingStarted`	All tests were executed and the post-processing has started	empty object
`OnExecutionFinished`	The execution has finished or was stopped	`WasExecutionStopped`: boolean
`OnExecutionError`	The execution was aborted by an error	`ErrorMessage`: string

Table: JSON-RPC notifications

Examples:

{"jsonrpc": "2.0", "method": "OnExecutionStarted", "params": [{"IsSingleTestRun": false}]}

{"jsonrpc": "2.0", "method": "OnTestExecutionStarted", "params": [{"TestName": "Diode IV"}]}

{"jsonrpc": "2.0", "method": "OnTestExecutionFinished", "params": [{"DataTable": {"ColumnList": [], "RowList": [{"Columns": [{"Info": {"ColumnInfo": {"FailBin": 3, "Guid": "8f1c2a40-5b3e-4d2f-9a6b-1c2d3e4f5a6b", "LimitMax": 0.8, "LimitMin": 0.6, "Name": "Vf", "Unit": "V"}, "Label": "Vf", "RowInfo": {"MeasurementChannel": null, "MeasurementIndex": 0, "Result": 1, "RunCount": 1}}, "Result": 1, "Value": {"ValueBool": false, "ValueDouble": 0.71, "ValueDoubleArray": null, "ValueInt": 0, "ValueString": null, "ValueType": 3}}], "RowInfo": {"MeasurementChannel": null, "MeasurementIndex": 0, "Result": 1, "RunCount": 1}}]}, "TestName": "Diode IV"}]}

{"jsonrpc": "2.0", "method": "OnPostprocessingStarted", "params": [{}]}

{"jsonrpc": "2.0", "method": "OnExecutionFinished", "params": [{"WasExecutionStopped": false}]}

{"jsonrpc": "2.0", "method": "OnExecutionError", "params": [{"ErrorMessage": "Device 'SMU1' is not connected"}]}

Data types#

Typed value#

A value whose type is given by ValueType. Only the property matching the type carries the value; the other value properties contain defaults and can be ignored. When sending a typed value, the other value properties may be omitted.

Property	Type	Description
`ValueType`	number	0 = Undefined, 1 = Bool, 2 = Integer, 3 = Double, 4 = String, 5 = DoubleArray
`ValueBool`	boolean	Value if `ValueType` is 1
`ValueInt`	number	Value if `ValueType` is 2
`ValueDouble`	number	Value if `ValueType` is 3
`ValueString`	string	Value if `ValueType` is 4
`ValueDoubleArray`	array of number	Value if `ValueType` is 5

Table: Typed value

Input parameter#

Property	Type	Description
`TestName`	string	Name of the test
`Identification`	string	Id of the test UI control
`Value`	typed value	Value of the control

Table: Input parameter

Output parameter#

Property	Type	Description
`TestName`	string	Name of the test
`Name`	string	Name of the parameter
`Caption`	string or null	Not used, always `null`
`Unit`	string	Unit of the parameter
`LimitMin`	number or null	Lower limit, `null` if none is defined
`LimitMax`	number or null	Upper limit, `null` if none is defined

Table: Output parameter

Site info#

Property	Type	Description
`SiteRow`	number or null	Row of the site
`SiteColumn`	number or null	Column of the site
`SubSiteIdx`	number or null	Index of the subsite
`SubSiteLabel`	string or null	Label of the subsite

Table: Site info

Bin#

Property	Type	Description
`Code`	number	Bin number
`Description`	string or null	Description of the bin
`Status`	number	0 = Unknown, 1 = Pass, 2 = Fail

Table: Bin

Data table#

The data table of a test, as sent with OnTestExecutionFinished. It contains one row per measurement and one value per output parameter in each row. ColumnList is always empty; the column information is part of every value.

Property	Type	Description
`ColumnList`	array	Always empty
`RowList`	array of row	Rows of the table

Table: Data table

Property	Type	Description
`RowInfo`	row info	Information about the row
`Columns`	array of data value	Values of the row, one per output parameter

Table: Data table row

Property	Type	Description
`MeasurementIndex`	number	Index of the measurement
`MeasurementChannel`	number or null	Measurement channel, `null` if not used
`RunCount`	number	Number of the run
`Result`	number	Evaluation result of the row: 0 = Undefined, 1 = Pass, 2 = Fail

Table: Row info

Property	Type	Description
`Value`	typed value	Measured value
`Result`	number	Evaluation result of the value: 0 = Undefined, 1 = Pass, 2 = Fail
`Info`	object	`Label` (string), `ColumnInfo` (column info) and `RowInfo` (row info) of the value

Table: Data value

Property	Type	Description
`Name`	string	Name of the output parameter
`Unit`	string	Unit of the output parameter
`LimitMin`	number or null	Lower limit, `null` if none is defined
`LimitMax`	number or null	Upper limit, `null` if none is defined
`FailBin`	number or null	Fail bin of the output parameter, if defined
`Guid`	string	Unique id of the output parameter

Table: Column info

Python example#

The following script connects to Measmatic, loads a project, starts it and waits for the end of the execution. It needs only the Python standard library.

import json
import socket


class MeasmaticJsonRpcClient:
    def __init__(self, host="localhost", port=35001):
        self._sock = socket.create_connection((host, port))
        self._buffer = b""
        self._next_id = 1
        self.notifications = []

    def close(self):
        self._sock.close()

    def call(self, method, *params):
        """Invokes a method and returns its result. Raises on an error response."""
        request_id = self._next_id
        self._next_id += 1

        request = {"jsonrpc": "2.0", "id": request_id, "method": method, "params": list(params)}
        self._send(request)

        # Notifications may arrive before the response
        while True:
            message = self.read_message()
            if message.get("id") == request_id:
                if "error" in message:
                    raise RuntimeError(message["error"]["message"])
                return message.get("result")

    def wait_for_notification(self, *methods):
        """Reads messages until a notification with one of the given method names arrives."""
        while True:
            message = self.read_message()
            if message.get("method") in methods:
                return message

    def read_message(self):
        while b"\r\n\r\n" not in self._buffer:
            self._buffer += self._recv()
        header, self._buffer = self._buffer.split(b"\r\n\r\n", 1)
        content_length = int(header.split(b"Content-Length:")[1].split(b"\r\n")[0])

        while len(self._buffer) < content_length:
            self._buffer += self._recv()
        body, self._buffer = self._buffer[:content_length], self._buffer[content_length:]

        message = json.loads(body)
        if "id" not in message:
            self.notifications.append(message)
        return message

    def _send(self, message):
        body = json.dumps(message).encode("utf-8")
        self._sock.sendall(f"Content-Length: {len(body)}\r\n\r\n".encode("ascii") + body)

    def _recv(self):
        chunk = self._sock.recv(4096)
        if not chunk:
            raise ConnectionError("Connection closed by Measmatic")
        return chunk


client = MeasmaticJsonRpcClient()
print(client.call("Identify"))

client.call("LoadProject", "Diodes\\DiodeTest2")
client.call("SetMeasurementDescription", "WaferID", "W-0815")
client.call("SetProjectInputParameter",
            {"TestName": "Diode IV", "Identification": "start_voltage", "Value": {"ValueType": 3, "ValueDouble": -1.5}})

client.call("Start")
finished = client.wait_for_notification("OnExecutionFinished", "OnExecutionError")
print(finished["method"], finished["params"][0])

print(client.call("GetBin"))
client.close()