事件与监控

服务通过专用的只读 WebSocket 在端口 10020 上推送系统事件。事件涵盖安全触发、设备连接、电池警告、会话生命周期变化和控制速率异常。

默认 URL： ws://localhost:10020

事件 JSON 格式

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

字段	类型	说明
name	string	稳定的事件标识符（用于筛选／切换）
category	string	device、session、system
level	string	info、notice、warning、error、critical、panic
data	object	事件专用的负载数据
message	string	可读的事件描述

事件类型

设备事件

名称	级别	触发时机
device-connected	info	检测到新设备并已就绪
device-disconnected	warning	设备丢失（被拔出或超时）
device-battery-low	warning	无线 VerseGrip 电量低于阈值
device-battery-critical	error	无线 VerseGrip 电量严重不足
device-sleep	info	无线 VerseGrip 进入休眠模式
device-busy	warning	设备正被其他会话占用
device-connection-loop	warning	在某个端口上检测到重复的连接／断开循环

安全事件

名称	级别	触发时机
device-safety-triggered	视情况而定	来自固件的安全通知（见下文）
device-calibration-failed	warning	已触发 Inkwell 校准，但笔不可用

device-safety-triggered 子类型

事件数据中的 safety_type 字段表示发生了什么：

safety_type	级别	含义
ebrake_triggered	error	紧急制动已触发——设备已锁定
ebrake_released	notice	紧急制动已解除
fod_stage_changed	warning / info	FOD 安全阶段跨越了低风险／高风险边界
stall_detected	warning	检测到电机堵转
stability_ceiling	warning	已达到稳定性上限

device-calibration-failed 原因

reason	含义
pen_not_connected	完全没有连接 verse grip
pen_asleep	无线 verse grip 已配对但处于休眠模式
pen_not_attached	verse grip 已就绪，但霍尔传感器低于阈值

会话事件

名称	级别	触发时机
session-started	notice	已创建一个 WebSocket 会话
session-stopped	notice	已销毁一个 WebSocket 会话
device-low-control-rate	warning	会话的控制速率降到推荐阈值以下
device-critical-control-rate	error	控制速率降至临界水平

系统事件

名称	级别	触发时机
system-rate-report	info	主循环节拍速率的周期性报告

监听事件

使用事件教程获取可直接运行的 Python 监听器示例，其中包含按级别、名称模式和排除项进行过滤的方法：

# 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*"