聚桥手套软件：驱动程序、Python API、ROS2

第 1 步 — 安装

安装 juqiao-glove 包

该手套通过 USB CDC 串行通信 — 无内核模块，无自定义驱动程序。 Python 包包装 pyserial 并处理二进制帧协议。

支持任何操作系统 该手套显示为标准 CDC-ACM 串行设备。 Windows、macOS 和 Linux 都会使用内置驱动程序自动枚举它。无需供应商驱动程序安装程序。

# Python 3.10+ recommended
pip 安装 juqiao-glove

# Or with optional visualization extras (matplotlib, numpy)
pip install "juqiao-glove[viz]"

# Or with ROS2 bridge extras (requires ROS2 Humble or later)
pip install "juqiao-glove[ros2]"

验证安装：

python -c“导入juqiao_glove;打印（juqiao_glove.__version__）”
# Expected: 0.4.x or later

第 2 步 — 端口检测

检测USB端口

通过 1.5 m USB-C 电缆插入手套。该设备枚举为 CDC-ACM 串行端口。

OS	典型端口名称	笔记
Linux	/dev/ttyACM0	将用户添加到拨出如果权限被拒绝则分组
macOS	/dev/tty.usbmodem*	使用 ls /dev/tty.usb* 找到确切的名字
视窗	COM3 （各不相同）	检查设备管理器 → 端口（COM 和 LPT）

从 Python 自动检测手套：

从 juqiao_glove 导入 JuqiaoGlove

# Auto-scan all serial ports and return the first Juqiao device found
手套 = JuqiaoGlove.find() 打印（手套.端口）   # → '/dev/ttyACM0' or 'COM3' etc.
打印（手套.info（）） # → firmware version, node count, sample rate

或者明确指定端口：

手套 = JuqiaoGlove(port="/dev/ttyACM0", 波特率=3000000)

Linux权限错误？ 跑步 sudo usermod -aG 拨出 $USER 然后注销并重新登录。或者，使用须藤 chmod 666 /dev/ttyACM0 以获得单会话解决方法。

第 3 步 — 流媒体 API

Python 流 API

手套的传输频率为 200 Hz。每个帧包含一个 64 元素压力数组（16 位 ADC，标准化 0.0–1.0）以及时间戳。

从 juqiao_glove 导入 JuqiaoGlove 导入时间 手套 = JuqiaoGlove.find() 手套.connect()

# Single-frame read
框架=手套.read_frame() print(帧.时间戳)          # float, seconds since epoch
print(帧.压力)          # np.ndarray shape (64,), float32, range 0.0-1.0
打印(框架.压力.重塑(8, 8)) # 8×8 spatial grid

# Continuous callback stream
def on_frame(帧): max_node =框架.压力.argmax() print(f"t={frame.timestamp:.4f} Peak_node={max_node} val={frame.Pressures[max_node]:.3f}") glove.stream（回调=on_frame，持续时间=5.0）  # stream for 5 seconds

# Or use as an iterator
以 glove.stream() 作为框架： 对于帧中的帧： 流程（框架） 如果完成： 打破 手套.disconnect()

框架对象参考

属性	类型	描述
帧.时间戳	漂浮	主机端接收时间（秒，Unix 纪元）
框架压力	np.ndarray (64,)	每个节点的归一化压力，0.0（无）到 1.0（最大）
框架.压力_原始	np.ndarray (64,)	原始 16 位 ADC 计数 (0–65535)
框架.contact_mask	np.ndarray(64,) 布尔值	当压力超过阈值时为真（默认 0.05）
框架.contact_nodes	列表[整数]	当前联系的节点索引
框架.grasp_region	字符串或无	启发式区域： “棕榈”, “拇指”, “指数”, “中间”, “戒指”, “小指”, 没有任何
帧序列	整数	帧计数器（在 65535 处换行）；用于检测丢帧

参考 — 传感器布局

64 节点传感器布局

64 个紫杉素排列成编织纤维矩阵，覆盖手掌和所有五个手指节段。节点索引遵循一致的背视行主顺序。

0–12

手掌（中央垫）

13–23

拇指（3节）

24–34

食指

35–45

中指

46–54

无名指

55–63

小指

# Access region slices by name
从 juqiao_glove.layout 导入 REGION_SLICES palm_nodes =框架.压力[REGION_SLICES[“手掌”]] 拇指节点=框架.压力[REGION_SLICES[“拇指”]] index_nodes =框架.压力[REGION_SLICES[“索引”]]

# Reshape to 8×8 spatial grid (dorsal view, row-major)
网格 =frame.Pressures.reshape(8, 8)

可选 — 可视化

压力热图可视化

这 [即] extra 安装了一个实时 matplotlib 热图渲染器，可用于校准和调试。

# Requires: pip install "juqiao-glove[viz]"
从 juqiao_glove 导入 JuqiaoGlove 从 juqiao_glove.viz 导入PressureHeatmap 手套 = JuqiaoGlove.find() 手套.connect() viz =PressureHeatmap(title="聚桥手套 — 实时压力") 即.show(手套)  # Opens a matplotlib window; press Q to quit

对于无头环境或数据查看，将帧保存为视频：

从 juqiao_glove.viz 导入 record_heatmap_video 记录热图视频（ input_npy =“会话压力.npy”，  # shape (N, 64) saved during recording
    output_mp4="热图.mp4", 帧率=30， 颜色图=“地狱”， ）

可选 — ROS2

ROS2接口

这 juqiao_glove_ros2 包发布自定义触觉阵列消息频率为 200 Hz。与 ROS2 Humble 和 Iron 兼容。

# Install the package (requires ROS2 to be sourced)
pip install "juqiao-glove[ros2]"

# Or build from source in your workspace
cd ~/ros2_ws/src git 克隆 https://github.com/roboticscenter/juqiao_glove_ros2 cd ~/ros2_ws && colcon build --packages-select juqiao_glove_ros2

启动驱动节点：

源/opt/ros/humble/setup.bash 源~/ros2_ws/install/setup.bash

# Auto-detect port
ros2启动 juqiao_glove_ros2 glove.launch.py

# Specify port explicitly
ros2启动 juqiao_glove_ros2 glove.launch.py​​​​​​​​​​ 端口：=/dev/ttyACM0

发表主题：

话题	消息类型	速度	描述
/juqiao_glove/tactile_array	juqiao_glove_ros2/TactileArray	200赫兹	全64节点压力阵列
/juqiao_glove/contact_mask	std_msgs/UInt8MultiArray	200赫兹	每个节点的二进制接触（0 或 1）
/juqiao_glove/grasp_region	std_msgs/字符串	200赫兹	活动区域启发式或空字符串
/juqiao_glove/status	诊断消息/诊断状态	1赫兹	固件版本、丢帧率

Orca 手部 + 手套组合发射

将手套与 Orca Hand 一起使用进行同步录音时：

# Launch Orca Hand driver
ros2启动orca_ros2 orca_hand.launch.py​​​​​​​​​​端口：=/dev/ttyUSB0

# In a second terminal, launch Juqiao Glove driver
ros2启动 juqiao_glove_ros2 glove.launch.py​​​​​​​​​​ 端口：=/dev/ttyACM0

# Verify synchronized topics
ros2 主题列表 | grep -E "逆戟鲸|巨桥" ros2 主题 hz /juqiao_glove/tactile_array ros2 主题 hz /orca_hand/joint_states

第 4 步 — 校准

基线校准

手套出厂时已进行校准。如果您发现基线漂移（节点在静止时读数非零）或在延长存储后，请重新校准。

校准前摘下手套 校准捕获零压力基线。在校准过程中请勿佩戴或触摸手套 - 将其平放在表面上。

# CLI calibration — lay glove flat, do not touch
python -m juqiao_glove.calibrate --port /dev/ttyACM0

# Or from Python
从 juqiao_glove 导入 JuqiaoGlove 手套 = JuqiaoGlove.find() 手套.connect() glove.calibrate_baseline(持续时间=3.0)   # averages 3 seconds of idle frames
glove.save_calibration("~/.juqiao_glove_cal.json") 手套.disconnect()

运行时负载校准：

手套 = JuqiaoGlove.find() 手套.connect() glove.load_calibration("~/.juqiao_glove_cal.json")

# Now frame.pressures reflects calibrated values
框架=手套.read_frame() 打印(帧.压力.max())  # Should be ~0.0 at rest

阈值调整

默认接触阈值为 0.05（满量程的 5%）。按任务调整：

# For delicate objects (lower threshold detects light touch)
手套.set_contact_threshold(0.02)

# For heavy manipulation tasks (reduce false positives)
手套.set_contact_threshold(0.10)

# Per-region thresholds
glove.set_contact_threshold({"手掌": 0.08, "拇指": 0.03, "食指": 0.03})

故障排除

常见问题

SerialException: [Errno 13] 权限被拒绝: '/dev/ttyACM0'

跑步 sudo usermod -aG dialout $USER 然后注销并重新登录。或者： sudo chmod 666 /dev/ttyACM0 （拔掉插头后重置）。

JuqiaoGlove.find() 返回 None — 未找到设备

检查 USB 连接。跑步 dmesg | tail -20 （Linux）或 ls /dev/tty.usb* (macOS) 以验证操作系统枚举了设备。尝试使用不同的 USB 端口或电缆（连接器为 USB-C，但必须是数据线，而不是仅用于充电）。

所有 64 个节点读取 0.0 — 无压力数据

称呼 glove.info() 确认固件响应。如果是这样，请检查校准文件是否过度减去。删除 ~/.juqiao_glove_cal.json 并在手套平放的情况下重新校准。

基线漂移 — 节点静止时读数为 0.1–0.2

重新校准：将手套平放，无压力并运行 glove.calibrate_baseline()。温度变化或长期存放后可能会发生。如果手套平放时漂移 > 0.4，则可能需要更换传感织物（联系聚桥支持）。

帧丢失 — 序列号跳过

检查 USB 电缆质量和端口。使用 USB 3.0 端口。在 Linux 上，避免将 USB 集线器与其他高带宽设备一起使用。确保您的 on_frame 回调快速返回——在单独的线程中进行繁重的处理。

ROS2节点启动但/juqiao_glove/tactile_array上没有消息

验证端口参数： ros2 launch juqiao_glove_ros2 glove.launch.py port:=/dev/ttyACM0。检查节点日志： ros2 node info /juqiao_glove_driver。确保 dialout 组修复已应用于运行 ROS2 节点的用户。

软件和驱动程序设置