Paxini Gen3 软件：SDK、Python API、ROS2

第 1 步 — 安装

安装 Paxini SDK

Paxini Gen3 通过 USB HID 进行通信 — 无需内核模块或供应商驱动程序。 Python SDK 封装了低级 HID 协议并公开了干净的流 API。

支持任何操作系统 Gen3 枚举为标准 USB HID 设备。 Windows、macOS 和 Linux 都通过内置驱动程序支持它。需要 Python 3.10 或更高版本。

# Python 3.10+ required
pip 安装 paxini-sdk

# With visualization extras (matplotlib, numpy)
pip install“paxini-sdk[viz]”

# With ROS2 bridge (requires ROS2 Humble or Jazzy)
pip install “paxini-sdk[ros2]”

验证安装：

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

第 2 步 — USB 检测

检测传感器

通过 USB-C 将 Gen3 传感器插入计算机。使用 SDK 的设备发现实用程序确认其已被识别：

python -m paxini.discover
# Example output:
# Found 1 Paxini device(s):
#   [0] PX-6AX-GEN3  serial=PX3A0042  firmware=1.2.4  variant=fingertip

对于多传感器设置（例如 USB 集线器上的五个手指）：

python -m paxini.discover --all
# Found 5 Paxini device(s):
#   [0] PX-6AX-GEN3  serial=PX3A0042  variant=fingertip  (index 0)
#   [1] PX-6AX-GEN3  serial=PX3A0043  variant=fingertip  (index 1)
#   ...

Linux USB 权限 在 Linux 上，您可能需要添加 udev 规则才能在无需 root 的情况下访问 HID 设备。跑步 sudo python -m paxini.install_udev 安装规则一次，然后拔下并重新插入传感器。

第 3 步 — 流媒体 API

Python 流 API

核心 API 是基于回调的流。每个帧提供一个触觉框架包含完整压力数组和元数据的对象。

# Minimal streaming example — 5 lines
导入帕克西尼 传感器 = paxini.Sensor()          # connects to first detected device
传感器.start() 对于sensor.stream()中的帧： 打印（帧.压力图）     # 2D numpy array, shape (rows, cols)
    print(frame.total_force_n)    # float, total normal force in Newtons

所有公共API方法：

方法/属性	描述	退货
传感器.start()	开始串流；非阻塞	没有任何
传感器.stop()	干净地停止流	没有任何
传感器.stream()	生成器以配置的 Hz 生成 TactileFrame 对象	发电机[触觉框架]
传感器.最新()	无阻塞地返回最新的帧	触觉框架
传感器.set_rate(hz)	设置采样率（USB-C 为 50–500 Hz，BLE 为 50–200 Hz）	没有任何
传感器.校准()	针对当前静载负载的零偏移校准	没有任何
传感器.串行	设备序列号字符串	斯特
传感器变体	“指尖”\| “指垫”\| “棕榈”	斯特

第 4 步 — 数据格式

触觉数据格式

每个触觉框架包含：

场地	类型	描述
帧.timestamp_ns	整数	纳秒时间戳（单调，主机时钟）
框架.压力图	np.ndarray(H,W)float32	每个紫杉醇的压力（以 kPa 为单位）。形状因型号而异：指尖为 8×8，手掌为 16×12。
框架.contact_mask	np.ndarray (H, W) 布尔值	当压力超过接触阈值时为真（默认值：5 kPa）
框架.接触面积_mm2	漂浮	活性紫杉醇面积总和（mm²）
框架.total_force_n	漂浮	所有税元的综合法向力（以牛顿为单位）
框架.contact_centroid	（浮动，浮动）	(row, col) 紫杉醇坐标中接触区域的质心
接触框架	布尔值	如果total_force_n超过接触阈值，则为真（默认值：0.05 N）
帧序列	整数	单调递增的帧序列号

空间分辨率 指尖变体：8×8紫杉醇阵列，覆盖14×14毫米，1.75毫米紫杉醇间距。手掌变体：16×12 阵列，覆盖 48×36 毫米，3 毫米间距。每个紫杉醇的测量值为 0–600 kPa。

第 5 步 — 可视化

实时热图可视化

SDK 提供了一个可立即运行的实时可视化工具。直接从命令行运行它：

# Launch live heatmap — press Q to quit
python -m paxini.visualize

# Multi-sensor visualization (e.g., 5-finger setup)
python -m paxini.visualize --all

或者使用以下命令嵌入到您自己的脚本中帕克西尼维兹模块：

导入帕克西尼 从 paxini.viz 导入 HeatmapWindow 传感器 = paxini.Sensor() 传感器.start() window = HeatmapWindow(title="Paxini Gen3 — 指尖") 对于sensor.stream()中的帧： window.update(frame.Pressure_map) 如果window.should_close()： 打破 传感器.stop()

第 6 步（可选）——ROS2

ROS2接口

ROS2桥发布了传感器消息/图像（压力图）和自定义 paxini_msgs/TactileFrame 每个传感器的主题。需要 ROS2 Humble 或 Jazzy。

# Install the ROS2 extras and launch the node
pip install “paxini-sdk[ros2]” ros2运行paxini_ros2sensor_node

# Published topics (per sensor):
#   /paxini/PX3A0042/pressure_image   sensor_msgs/Image
#   /paxini/PX3A0042/tactile_frame    paxini_msgs/TactileFrame
#   /paxini/PX3A0042/contact_event    std_msgs/Bool

对于多传感器设置，每个设备都以其序列号发布。您可以使用标准 ROS2 重新映射来重新映射启动文件中的主题。

第 7 步 — Arm 集成

机械臂集成

要将 Paxini 数据与机器人手臂关节状态同步，请使用帕西尼同步模块。它根据共享时钟对所有传感器帧进行时间戳记，并提供一个阻塞 API，可生成同步的（arm_state、tactile_frame）对：

导入帕克西尼 从 paxini.sync 导入 MultiSourceSync

# Initialize sensor and arm interface
传感器 = paxini.Sensor() 手臂 = YourArmInterface()           # any arm with a get_joint_state() method

同步 = 多源同步( 传感器=传感器， 手臂=手臂， 最大dt_ms=5.0                  # reject pairs with >5ms timestamp gap
） 对于arm_state，sync.stream()中的触觉： 打印（手臂状态.关节位置） 打印（触觉.total_force_n） 打印（触觉.压力图）

时间戳对齐 Gen3 在 USB 中断时间使用主机时钟以纳秒分辨率对帧添加时间戳。抖动通常<0.5 ms。这 MultiSourceSync 当手臂和传感器速率不同时，该类处理插值。

故障排除

三大问题

paxini.discover() 返回空列表

未检测到传感器。按顺序检查：(1) 尝试使用不同的 USB-C 电缆 — 有些电缆只能充电，不传输数据。 (2) 在Linux上，运行 sudo python -m paxini.install_udev 然后拔下/重新插入传感器。 (3) 确认传感器 LED 常亮（不闪烁）——闪烁表示处于固件更新模式；按住重置按钮 5 秒即可退出。

按下时压力图全为零

传感器需要校准或阈值设置得太高。跑步 sensor.calibrate() 传感器卸载（无接触）。如果问题仍然存在，请检查传感器型号是否与您的安装座匹配 - 由于紫杉醇面积较大，安装在指尖上的手掌传感器将显示非常低的压力值。另请确认固件版本 1.2+ python -m paxini.discover.

MultiSourceSync 引发 TimestampDriftError

ARM 接口时钟和传感器时间戳相差超过 max_dt_ms。这通常是由于arm SDK返回过时的联合状态（例如，以较低速率缓冲）引起的。增加 max_dt_ms 到 10.0 作为第一次测试，然后调查为什么 ARM 状态刷新率低于预期。对于 USB 臂，确认 USB 轮询速率没有受到电源管理的限制（sudo powertop 在 Linux 上）。

还卡住了吗？发表在论坛提问帖与您的操作系统、SDK 版本（paxini.__version__），以及准确的错误输出。

软件和驱动程序设置