Socket Interface

neoEBV provides the capability to open a socket and receive commands to manipulate neoEBV.

How to Execute

Socket is opened by specifying --json-rpc-server or --json-rpc-unix-server at neoEBV startup.

$ nebv --json-rpc-server=[<host|addr>:]<port>[-<port-max>]

$ nebv --json-rpc-unix-server=<unix-domain-socket-path>

When the user sends a command in JSON-RPC format to the open socket, neoEBV receives the command, process it accordingly, and sends the result to the user.

Request Format of Command

The commands are mapped one-to-one with methods of the pynebv module. The request formats differ between the methods of Section class and those of Item class, as shown below.

In Case of Section Class Method

{"jsonrpc":"2.0","method":"pynebv.<Class name>.<Method name>","id":<ID value>,"params":{"<key>":<value>, "<key>":<value>...}}

jsonrpc

The value is fixed at 2.0.

method

The value is specified in the format pynebv.<Class name>.<Method name>.

<Class name> is the name of derived Section class.
- Example: If you want to retrieve MarkList data, specify pynebv.MarkList.items instead of pynebv.EbvListSection.items.
<Method name> is the name of the method of the class.

id

The value can be specified arbitrarily by user.

params

Specify the argument name of each method as <key> and the value of the argument as <value>.

In Case of Item Class Method

{"jsonrpc":"2.0","method":"pynebv.<Class name>.<Method name>","id":<ID value>,"params":{"item":<value>, "<key>":<value>, "<key>":<value>...}}

jsonrpc

The value is fixed at 2.0.

method

The value is specified in the format pynebv.<Class name>.<Method name>.

<Class name> is one of the names of the Item classes in the class hierarchy from the class where the method is defined to the class specified by item.
- Example: If you want to retrieve the properties of Mark, specify either pynebv.Mark.props, pynebv.MarkListItem.props or pynebv.EbvItem.props.
- Example: If you want to close Jobdeck file, specify either pynebv.Jobdeck.close or pynebv.File.close.
- Example: If you want to retrieve the layer of Jobdeck file, specify pynebv.Jobdeck.layer.
<Method name> is the name of the method of the class.

id

The value can be specified arbitrarily by user.

params

Specify the data to which the method is applied as the value of item or itemList key.
Specify the argument name of each method as <key> and the value of the argument as <value>.

About handling values for item key, itemList key, EbvItem type, and EbvItemList type

Specify the Json object of EbvItem or EbvItemList received as the return value of another method.
The Json object of EbvItemList is an array of Json objects of EbvItem.

In Case of Module Method

{"jsonrpc":"2.0","method":"pynebv.<Method name>","id":<ID value>,"params":{"<key>":<value>, "<key>":<value>...}}

jsonrpc

The value is fixed at 2.0.

method

The value is specified in the format pynebv.<Method name>.

<Method name> is the name of the method of the Module class.

id

The value can be specified arbitrarily by user.

params

Specify the argument name of each method as <key> and the value of the argument as <value>.

Response Format of Command

The response format is as below.

On Method Success

{"jsonrpc":"2.0","id":<ID value of request>,"result":{"<key>":<value>, "<key>":<value>...}}

jsonrpc

The value is fixed at 2.0.

id

The value is the one specified in the corresponding request.

result

The value is the Json form of the value returned by the pynebv module method mapped with the corresponding request. If the method returns no value, an empty object is returned.

On Method Failure

{"jsonrpc":"2.0","id":<ID value of request>,"error":{"code":<error code>, "message":"<error message>"}}

jsonrpc

The value is fixed at 2.0.

id

The value is the one specified in the corresponding request.

error

The value contains error code and error message.

Example of JSON-RPC Commands

Some simple example commands are shown below.

Open File

Request

{"jsonrpc":"2.0","method":"pynebv.FileList.open","id":1001,"params":{"filePath":"/path/to/sample.oas","opts":{"cellline":"false","chipline":"false","dose-index":"false"}}}

Response

{"jsonrpc":"2.0","id":1001,"result":{"key":"sample.oas@1","klass":"File", "props":{"File/AU [um]":"0.0254", "File/Area [um]": "-88.9,-114.3,4770.12,4693.92", "File/Display Name":"sample"},"attrs": {"area":[-88.9, -114.3, 4770.12, 4693.92], "au":"0.0254", "bold":"False"}}

Close File

Request

{"jsonrpc":"2.0","method":"pynebv.File.close","id":1002,"params":{"item":{"key":"sample.oas@1","klass":"File", "props":{"File/AU [um]":"0.0254", "File/Area [um]": "-88.9,-114.3,4770.12,4693.92", "File/Display Name":"sample"},"attrs": {"area":[-88.9, -114.3, 4770.12, 4693.92], "au":"0.0254", "bold":"False"}}}}

Response

{"jsonrpc":"2.0","id":1002,"result":{}}

Add Mark

Request

{"jsonrpc":"2.0","method":"pynebv.MarkList.add","id":1010,"params":{"point":[10,0]}}

Response

{"jsonrpc":"2.0","id":1010,"result":{"key":"Marks@1|Mark 1@1","props":{"Color":"80000000","Location":"10.0,0.0","Name":"Mark 1","Shape":"Dot"},"attrs":{"cells":{"LineNo.":"1","mark_color":"","mark_group":"","mark_representative":"","mark_shape":"","name":"Mark 1","x":"10.0","y":"0.0"},"color":"80000000","display":"True","is_filter_hit":"True","name":"Mark 1","pos":[10,0],"thumbnail_image_size":"None"},"klass":"Mark"}}

Retrieve Mark Properties

Request

{"jsonrpc":"2.0","method":"pynebv.EbvItem.props","id":1011,"params":{"item": {"key":"Marks@1|Mark 1@1","props":{"Color":"80000000","Location":"10.0,0.0","Name":"Mark 1","Shape":"Dot"},"attrs":{"cells":{"LineNo.":"1","mark_color":"","mark_group":"","mark_representative":"","mark_shape":"","name":"Mark 1","x":"10.0","y":"0.0"},"color":"80000000","display":"True","is_filter_hit":"True","name":"Mark 1","pos":[10,0],"thumbnail_image_size":"None"},"klass":"Mark"}}}

Response

{"jsonrpc":"2.0","id":1011,"result":{"Color":"80000000","Location":"10.0,0.0","Name":"Mark 1","Shape":"Dot"}}

Quit neoEBV

Request

{"jsonrpc":"2.0","method":"pynebv.quit","id":1011,"params":{"exitCode":"1"}}

Response

{"jsonrpc":"2.0","id":1011,"result":{}}

Error Command (Method Name is Invalid)

Request

{"jsonrpc":"2.0","method":"pynebv.test","id":1001,"params":{"filePath":"/path/to/sample.oas"}}

Response

{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1001"}

Sample Code

Here is an example in python of connecting to neoEBV and sending and receiving commands in JSON-RPC format.

import socket
import json

def sendJsonRpcRequest(socket, method, params, id):
  # create request
  request = {
    "jsonrpc": "2.0",
    "method": method,
    "params": params,
    "id": id
  }

  # convert json string
  request_json = json.dumps(request)
  # send to neoEBV
  socket.sendall(request_json.encode('utf-8'))

def receiveJsonRpcResponse(socket):
  # receive first character from neoEBV
  first_char = socket.recv(1)
  # receive rest message from neoEBV
  socket.setblocking(False)
  response = first_char
  response += socket.recv(8192)
  socket.setblocking(True)
  return json.loads(response.decode('utf-8'))

# check if response has error
def responseHasError(response):
  if "error" in response:
    print("[ERROR] fail to send request: ", response.get("error").get("message"))
    return True
  else:
    return False

def main():
  sock = None
  try:
    # connect to neoEBV
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.connect(("<server ip>", <port>))

    # request file open command
    sendJsonRpcRequest(sock, "pynebv.FileList.open", {"filePath":"/path/to/sample.oas","opts":{"chipline":"true"}}, 1001)
    response = receiveJsonRpcResponse(sock)

    # get file object
    if responseHasError(response):
      return
    file = response.get("result")

    # request mark add command
    sendJsonRpcRequest(sock, "pynebv.MarkList.add", {"point":[10,10]}, 1002)
    response = receiveJsonRpcResponse(sock)

    # get mark object
    if responseHasError(response):
      return
    mark = response.get("result")

    # request mark delete command
    sendJsonRpcRequest(sock, "pynebv.Mark.delete", {"item": mark}, 1003)
    receiveJsonRpcResponse(sock)

    # request file close command
    sendJsonRpcRequest(sock, "pynebv.File.close", {"item": file}, 1002)
    receiveJsonRpcResponse(sock)

  finally:
    if sock:
      # disconnect from neoEBV
      sock.close()

main()

Restrictions

Only the methods listed under Methods that are defined in Section Classes or Item Classes can be used. Please refer to the pynebv Reference for Section Classes, Item Classes and available Methods.

Last modified March 24, 2025