Events & Monitoring

The service pushes system events over a dedicated read-only WebSocket on port 10020. Events report safety triggers, device connections, battery warnings, session lifecycle changes, and control rate anomalies.

Default URL: ws://localhost:10020

Event JSON shape

{
  "name": "device-safety-triggered",
  "category": "device",
  "level": "warning",
  "data": { "device_family": "inverse", "device_id": "049D", … },
  "message": "FOD stage changed: guard -> hard"
}

Field	Type	Description
name	string	Stable event identifier (use for filtering / switching)
category	string	device, session, system
level	string	info, notice, warning, error, critical, panic
data	object	Event-specific payload
message	string	Human-readable description

Event types

Device events

Name	Level	When
device-connected	info	A new device is detected and ready
device-disconnected	warning	A device was lost (unplugged or timed out)
device-battery-low	warning	Wireless VerseGrip battery below threshold
device-battery-critical	error	Battery critically low
device-sleep	info	Wireless VerseGrip entered sleep mode
device-busy	warning	Device is in use by another session
device-connection-loop	warning	Repeated connect/disconnect cycles detected on a port

Safety events

Name	Level	When
device-safety-triggered	varies	Safety notification from firmware (see below)
device-calibration-failed	warning	Inkwell calibration triggered but pen not usable

device-safety-triggered sub-types

The safety_type field in the event data indicates what happened:

safety_type	Level	Meaning
ebrake_triggered	error	Emergency brake engaged — device locked
ebrake_released	notice	Emergency brake released
fod_stage_changed	warning / info	FOD safety stage crossed the low/high risk boundary
stall_detected	warning	Motor stall detected
stability_ceiling	warning	Stability ceiling reached

device-calibration-failed reasons

reason	Meaning
pen_not_connected	No verse grip is connected at all
pen_asleep	Wireless verse grip is paired but in sleep mode
pen_not_attached	Verse grip is ready but hall sensor is below threshold

Session events

Name	Level	When
session-started	notice	A WebSocket session was created
session-stopped	notice	A WebSocket session was destroyed
device-low-control-rate	warning	Session's control rate dropped below recommended threshold
device-critical-control-rate	error	Control rate dropped to a critical level

System events

Name	Level	When
system-rate-report	info	Periodic main-loop tick rate report

Listening to events

Use the Events tutorial for a ready-to-run Python listener with filtering by level, name patterns, and exclusions:

# All events
python 10-haply-inverse-events.py

# Only warnings and above
python 10-haply-inverse-events.py --level warning

# Only device events
python 10-haply-inverse-events.py --name "device-*"

# Exclude battery noise
python 10-haply-inverse-events.py --exclude "*battery*"