Socket.IO API

This section documents the Socket.IO API. The document is intended for developers building client applications communicating with the server. If you are looking for information on how to set up and run the server, see the installation guide!

Data Types

All messages on Socket.IO are passed as strings. Complex data structures are JSON encoded, converted to strings, and then sent. These structures have their JSON schemas documented on VBL Aquarium.

This documentation will reference the Pydantic versions of these models as they are extensively documented. For most functions, their functions and responses are documented by these models. Follow the links to the VBL Aquarium documentation for a model to learn more. These models have a .to_json_string() method that will convert the model object to a string that can be sent over Socket.IO.

Events

Client applications should send messages to these events to interact with the server. The server will respond using Socket.IO acknowledgments.

Get Ephys Link Version

Event	Input	Response
`get_version`	None	`string`

Semantically Versioned number.

Examples:

Input: None

Response:

"2.0.0"
"2.0.0b2

Get Pinpoint ID

Event	Input	Response
`get_pinpoint_id`	None	`string`

Proxy connection ID (first 8 characters of a UUID v4).

Example:

Input: None

Response: "81f8de08"

Get Platform Info

Event	Input	Return
`get_platform_info`	None	`PlatformInfo`

Example:

Input: N/A

Response:

{
  "Name": "Sensapex uMp-4",
  "CliName": "ump-4",
  "AxesCount": 4,
  "Dimensions": {
    "x": 20.0,
    "y": 20.0,
    "z": 20.0,
    "w": 20.0
  }
}

List Available Manipulators

Event	Input	Return
`get_manipulators`	None	`GetManipulatorResponse`

Examples:

Input: N/A

Response:

Normal:

{
  "Manipulators": [
    "1",
    "2",
    "3"
  ],
  "Error": ""
}

Error:

{
  "Manipulators": [],
  "Error": "No manipulators found"
}

Get Manipulator Position

Event	Input	Return
`get_position`	Manipulator ID (`string`)	`PositionalResponse`

Examples:

Input:

"1"
"A"

Response:

Normal:

{
  "Position": {
    "x": 12.45,
    "y": 7.89,
    "z": 0.81,
    "w": 8.12
  },
  "Error": ""
}

Error:

{
  "Position": {
    "x": 0.0,
    "y": 0.0,
    "z": 0.0,
    "w": 0.0
  },
  "Error": "Unable to Read Manipulator Position"
}

Get Manipulator Angles

Event	Input	Return
`get_angles`	Manipulator ID (`string`)	`AngularResponse`

Examples:

Input:

"1"
"A"

Response:

Normal:

    {
  "Angles": {
    "x": 45.0,
    "y": 0.0,
    "z": 90.0
  },
  "Error": ""
}

Error:

  {
  "Angles": {
    "x": 0.0,
    "y": 0.0,
    "z": 0.0
  },
  "Error": "Unable to Read Manipulator Angles"
}

Get Probe Shank Count

Event	Input	Return
`get_shank_count`	Manipulator ID (`string`)	`ShankCountResponse`

Examples:

Input:

"1"
"A"

Response:

Normal:

{
  "ShankCount": 3,
  "Error": ""
}

Error:

{
  "ShankCount": 1,
  "Error": "Unable to Read Probe Shank Count"
}

Set Manipulator Position

Event	Input	Return
`set_position`	`SetPositionRequest`	`PositionalResponse`

Examples:

Input:

{
  "ManipulatorId": "1",
  "Position": {
    "x": 1.5,
    "y": 2.0,
    "z": 0.0,
    "w": 0.84
  },
  "Speed": 0.05
}

Response:

Normal:

{
  "Position": {
    "x": 1.5,
    "y": 2.0,
    "z": 0.0,
    "w": 0.84
  },
  "Error": ""
}

Manipulator is set to be inside the brain (position setting is disallowed):

{
  "Position": {
    "x": 0.0,
    "y": 0.0,
    "z": 0.0,
    "w": 0.0
  },
  "Error": "Can not move manipulator while inside the brain. Set the depth (\"set_depth\") instead."
}

The manipulator did not make it to the final destination. This is not necessarily unintentional. This response is produced if a movement is stopped.

{
  "Position": {
    "x": 0.0,
    "y": 0.0,
    "z": 0.0,
    "w": 0.0
  },
  "Error": "Manipulator 1 did not reach target position on axis x. Requests: 1.5, got: 0.82."
}

Set Manipulator Depth

Event	Input	Return
`set_depth`	`SetDepthRequest`	`SetDepthResponse`

Examples:

Input:

{
  "ManipulatorId": "1",
  "Depth": 1.7,
  "Speed": 0.005
}

Response:

Normal:

{
  "Depth": 1.7,
  "Error": ""
}

The manipulator did not make it to the final destination. This is not necessarily unintentional. This response is produced if a drive is stopped.

{
  "Depth": 0,
  "Error": "Manipulator 1 did not reach target depth. Requested: 1.7, got: 0.6."
}

Set Manipulator to be Inside the Brain

Event	Input	Return
`set_inside_brain`	`SetInsideBrainRequest`	`BooleanStateResponse`

Examples:

Input:

{
  "ManipulatorId": "1",
  "Inside": true
}

Response:

Normal:

{
  "State": true,
  "Error": ""
}

Error

{
  "State": false,
  "Error": "Unable to complete operation."
}

Stop a Manipulator's movement

Event	Input	Return
`stop`	Manipulator ID (`string`)	Error Message (`string`)

Examples:

Input:

"1"
"A"

Response:

Normal: ""
Error: "Unable to stop manipulator."

Stop All Manipulators

Event	Input	Return
`stop_all`	None	Error Message (`string`)

Examples:

Input: None

Response:

Normal: ""
Error: "Unable to stop manipulator."

Unknown Event (Error)

Response: {"error", "Unknown event."}

Notes

In the examples, the error response messages are generic examples. The actual error strings you see will be driven by what exceptions are raised by the binding.