Events Channel

The default event websocket URL is ws://localhost:10020.

The port can be changed in the configuration.

This is low-frequency uni-directional communication channel where you can expect to receive all the system events. There is no input message supported.

This channel guaranty to send one message for each event.

Canonical Format

All events follow a standard structure as shown below:

{
  "name": "device-connected",
  "category": "device",
  "level": "notice",
  "data": {},
  "message": ""
}

Field Descriptions

Field	Type	Description
name	string	Unique identifier for the event.
category	string	Grouping label used for filtering and organization (see valid categories).
level	string	Severity or importance of the event (see valid levels).
data	object	Payload containing event-specific details.
message	string	Optional human-readable description or context for the event.

Event Category

The category field organizes events into the following groups:

Value	Description
system	Core or central systems, global settings, etc.
input	External input handling (e.g., commands or others).
session	Events related to a specific user session.
device	Device management, controller interactions, SerialPort communication.
module	Subsystem or modular component events.
feature	Events tied to specific service features or capabilities.

Event Level

The event level field indicates the severity or importance of an event:

Value	Description
info	Informational only — logs, metrics, or non-critical notices.
notice	State changes or notable events.
warning	Something went wrong or seems off, but the system can continue safely.
error	An issue occurred that may impact system behavior or stability.
critical	Severe error that significantly disrupts system functionality.
panic	Catastrophic failure — may lead to a crash or an unrecoverable state.

Events

info

This list is the current list of events currently reported by the system. We are actively designing and expanding event types and reporting.

Input

invalid-io-channel

Triggered when an I/O channel is used in an unsupported or unintended way.

Data

Field	Type	Description
received_data	string	The raw data that was received.

{
  "name": "invalid-io-channel",
  "category": "input",
  "level": "warning",
  "data": {
    "received_data": "<raw_input_here>"
  }
}

http-route-deprecated

Issued when a HTTP route is deprecated and will be removed in a future version.

Data

Field	Type	Description
route	string	The deprecated route.
substitute	string	The recommended substitute.

{
  "name": "http-route-deprecated",
  "category": "input",
  "level": "warning",
  "data": {
    "route": "/the/old/way",
    "substitute": "/the/new/way"
  }
}

settings-invalid-key

Issued when a settings key is invalid.

Data

Field	Type	Description
key	string	The key that was not found.

{
  "name": "settings-invalid-key",
  "category": "input",
  "level": "warning",
  "data": {
    "key": "devices/none-existent/key"
  }
}

command-deprecated

Issued when an incoming command is deprecated and will be removed in a future version.

Field	Type	Description
command	string	The received deprecated command

{
  "name": "command-deprecated",
  "category": "input",
  "level": "warning",
  "data": {
    "command": "example_cmd"
  },
  "message": "The command `example_cmd` is deprecated and is replaced by `this_one`."
}

Device

device-connected

Indicates that a device has connected and is now fully operational.

Field	Type	Description
device_family	string	Type of device: inverse or verse_grip.
device_id	string	The device's unique identifier.

{
  "name": "device-connected",
  "category": "device",
  "level": "notice",
  "data": {
    "device_family": "inverse",
    "device_id": "04BA"
  }
}

device-disconnected

Signifies that a previously connected device has been disconnected.

Field	Type	Description
device_family	string	Type of device: inverse or verse_grip.
device_id	string	The device's unique identifier.

{
  "name": "device-disconnected",
  "category": "device",
  "level": "notice",
  "data": {
    "device_family": "verse_grip",
    "device_id": "61548"
  }
}

Session

device-low-control-rate

Issued when an incoming direct control command for a device hit too low of a rate and hit the safety limits. This one is a warning that the rate is approaching the cutoff rate.

Field	Type	Description
session_id	int	Target simulation session ID.
device_family	string	Type of device: inverse or verse_grip.
device_id	string	The device's unique identifier.
frequency	int	Your current control rate in Hertz.

{
  "name": "device-low-control-rate",
  "category": "session",
  "level": "warning",
  "data": {
    "session_id": 3,
    "device_family": "inverse",
    "device_id": "1A2B",
    "frequency": 260
  },
  "message": ""
}

device-critical-control-rate

Issued when an incoming direct control command for a device hit too low of a rate and hit the safety limits.

Field	Type	Description
session_id	int	Target simulation session ID.
device_family	string	Type of device: inverse or verse_grip.
device_id	string	The device's unique identifier.
frequency	int	Your current control rate in Hertz.

{
  "name": "device-critical-control-rate",
  "category": "session",
  "level": "error",
  "data": {
    "session_id": 3,
    "device_family": "inverse",
    "device_id": "1A2B",
    "frequency": 82
  },
  "message": ""
}

Features

sdf-sdf_hfx-created

Issued when an SDF entity FX is created.

Field	Type	Description
session_id	int	Target simulation session ID.
device_id	string	The device's unique identifier.
hfx_id	string	The FX ID with which it was created.

{
  "name": "sdf-sdf_hfx-created",
  "category": "feature",
  "level": "notice",
  "data": {
    "session_id": 3,
    "device_id": "1A2B",
    "hfx_id": "my_fx_name"
  },
  "message": ""
}

sdf-sdf_hfx-deleted

Issued when an SDF entity FX is deleted.

Field	Type	Description
session_id	int	Target simulation session ID.
device_id	string	The device's unique identifier.
hfx_id	string	The deleted FX ID.

{
  "name": "sdf-sdf_hfx-deleted",
  "category": "feature",
  "level": "notice",
  "data": {
    "session_id": 3,
    "device_id": "1A2B",
    "hfx_id": "my_fx_name"
  },
  "message": ""
}

sdf-sdf_hfx-updated

Issued when an SDF entity FX is updated.

Field	Type	Description
session_id	int	Target simulation session ID.
device_id	string	The device's unique identifier.
hfx_id	string	The updated FX ID.

{
  "name": "sdf-sdf_hfx-updated",
  "category": "feature",
  "level": "notice",
  "data": {
    "session_id": 3,
    "device_id": "1A2B",
    "hfx_id": "my_fx_name"
  },
  "message": ""
}

sdf-sdf_hfx-range-entered

Issued when the cursor of the given device enters the SDF entity range.

Field	Type	Description
session_id	int	Target simulation session ID.
device_id	string	The device's unique identifier.
hfx_id	string	The FX ID.

{
  "name": "sdf-sdf_hfx-range-entered",
  "category": "feature",
  "level": "notice",
  "data": {
    "session_id": 3,
    "device_id": "1A2B",
    "hfx_id": "my_fx_name"
  },
  "message": ""
}

sdf-sdf_hfx-range-exited

Issued when the cursor of the given device exits the SDF entity range.

Field	Type	Description
session_id	int	Target simulation session ID.
device_id	string	The device's unique identifier.
hfx_id	string	The FX ID.

{
  "name": "sdf-sdf_hfx-range-exited",
  "category": "feature",
  "level": "notice",
  "data": {
    "session_id": 3,
    "device_id": "1A2B",
    "hfx_id": "my_fx_name"
  },
  "message": ""
}