ViTai UMI 用户手册

VT-TacUMI-85	VT-TacUMI-90

快速开始

# 1. 绑定设备（只接一个 UMI）
vitai-umi-bonding

# 2. 启动（自动打开浏览器）
vitai-umi-launcher

# 3. 在 Web 页面 http://127.0.0.1:8766 操作
# 4. Ctrl+C 退出

一个 UMI 设备只有一个 Type-C 口，一次只能绑定一个设备。多设备场景见下方说明。

1. 安装

1.1 系统要求

Ubuntu 22.04
ROS 2 Humble（官方安装教程）
当前用户需加入 dialout 组（串口权限）

sudo apt install -y python3-pip python3-serial ffmpeg libv4l-dev
sudo usermod -a -G dialout $USER   # 重新登录生效

VIO 相机驱动另需安装 xvisio SDK：https://www.xvisiotech.com/Ubuntusdk/255

1.2 装 UMI

sudo dpkg -i vitai-umi_*.deb
sudo apt --fix-broken install   # 如有依赖缺失

2. 设备绑定

UMI 设备只有一个 Type-C 口，一次只接一个设备进行绑定。插上后运行：

vitai-umi-bonding

按提示输入实例名称（如 map、left_hand 等），脚本自动检测 MCU、VIO 相机、触觉传感器、Realsense 等设备，生成配置文件。

多个 UMI 场景：每个设备分别接上电脑运行一次绑定，使用不同实例名（如 umi_1、umi_2）。所有设备绑定到同一台电脑后，只有一个 sensors.yaml。

3. 配置文件说明

3.1 sensors.yaml（设备配置）

位置：~/.config/umi/sensors.yaml

配置项	说明	如何修改
`tactile_global_config`	触觉传感器全局参数（帧大小、类型等）	通常不需要改
`cslam.enabled`	多设备共享坐标系开关	`true`/`false`
`cslam.map_path`	建图生成的地图文件路径	建图后自动填入
`{实例名}.enabled`	是否启用该设备实例	`true`/`false`
`{实例名}.mcu.sn`	MCU 序列号（自动检测）	自动填入，无需手动改
`{实例名}.vio.enabled`	VIO 相机开关	`true`/`false`
`{实例名}.vio.device_serial`	VIO 相机序列号	自动填入
`{实例名}.vio.sensors.*.publish_frequency`	各传感器发布频率	按需调整
`{实例名}.tactile.enabled`	触觉传感器开关	`true`/`false`
`{实例名}.tactile.left/right.sn`	左右手指触觉传感器序列号	自动填入
`{实例名}.realsense.enabled`	Realsense 深度相机开关	`true`/`false`
`{实例名}.realsense.device_serial`	Realsense 序列号	自动填入
`{实例名}.fisheye.enabled`	鱼眼相机开关	`true`/`false`
`{实例名}.fisheye.camera_controls`	鱼眼相机曝光、白平衡等	见下方说明
`{实例名}.gripper.enabled`	夹爪/编码器开关	`true`/`false`
`{实例名}.ik.enabled`	在线逆运动学开关	`true`/`false`（默认关闭）

鱼眼相机曝光调节：

fisheye:
  camera_controls:
    auto_exposure: 3          # 1=手动, 3=自动(默认)
    exposure_time_absolute: 800  # 手动曝光时间(1-10000)，越大越亮
    gain: 0                   # 增益(0-1023)
    brightness: 0             # 亮度(-64~64)
    contrast: 0               # 对比度(0-95)
    gamma: 100                # 伽马(64-300)
    white_balance_automatic: true

3.2 data_collector.yaml（采集配置）

位置：~/.config/umi/data_collector.yaml

配置项	说明	可选值 / 默认值
`enabled`	是否启用数据采集	`true` / `false`（默认 `false`）
`save_format`	存储格式	`npy`（mp4+npz）/ `hdf5`（单文件）
`save_mode`	采集模式	`sync`（同步，默认）/ `raw`（独立时间轴）
`target_fps`	目标帧率	默认 `30`
`save_dir`	数据保存目录	默认 `~/umi_data`
`task_name`	任务名称（写入 meta.json）	任意字符串

4. 启动 & 采集

# 一键启动（推荐）
vitai-umi-launcher

# 或命令行启动
ros2 launch umi_bringup umi_system.launch.py

浏览器打开 http://127.0.0.1:8766，等所有设备状态变绿（OK）后，点录制按钮开始采集。

双持场景：启动前执行（否则可能 USB 带宽不足）：

echo 512 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb

5. 多设备建图（可选）

让多个 UMI 共享同一个坐标系：

# 1. 手持设备缓慢走动建图，Ctrl+C 保存
vitai-umi-slam-mapping save ~/.config/umi/cslam_map.bin

# 2. 把地图拷贝到所有设备
scp ~/.config/umi/cslam_map.bin user@other-device:~/.config/umi/

# 3. 编辑 sensors.yaml 启用
#   cslam:
#     enabled: true
#     map_path: "~/.config/umi/cslam_map.bin"

6. 常见问题

6.1 设备检测不到 / 显示 UNKNOWN

ls /dev/ttyUSB* /dev/ttyACM*   # 检查 USB
groups $USER                     # 确认在 dialout 组
vitai-umi-bonding               # 重新绑定

6.2 相机掉帧 / 初始化失败

echo 512 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb
lsusb -t   # 确保相机不共用 USB 控制器

6.3 上次进程残留

pkill -9 -f umi

6.4 sensors.yaml 丢了

vitai-umi-bonding

6.5 鱼眼画面太暗/太亮

编辑 ~/.config/umi/sensors.yaml，改动 fisheye.camera_controls.auto_exposure 和 exposure_time_absolute 的值。

7. 数据在哪

保存在 ~/umi_data/（可在 data_collector.yaml 中修改），每个 episode 一个文件夹，包含视频（mp4）、位姿（npy）、时间戳和 meta.json。

鱼眼相机曝光调节

编辑 ~/.config/umi/sensors.yaml 中对应实例的 fisheye.camera_controls：

fisheye:
  camera_controls:
    auto_exposure: 3          # 1=手动模式, 3=自动(默认)
    exposure_time_absolute: 800  # 手动曝光时间(1-10000)
    gain: 0                   # 增益(0-1023)
    brightness: 0             # 亮度(-64~64)
    contrast: 0               # 对比度(0-95)
    gamma: 100                # 伽马(64-300)
    white_balance_automatic: true

8. 配置文件说明

8.1 sensors.yaml

路径：~/.config/umi/sensors.yaml

这是系统最核心的配置文件，由 vitai-umi-bonding 自动生成。

# 全局配置
tactile_global_config:
  frame_size: [240, 240]
  type: 'GF225'

cslam:
  enabled: false           # 是否启用共享坐标系
  map_path: "~/.config/umi/cslam_map.bin"

# 实例配置（每个 UMI 设备一个实例）
umi_1:
  enabled: true
  mcu:
    enabled: true
    sn: "SN-75715063-123456"
  vio:
    enabled: true
    device_serial: "20855020002524000368"
    sensors:
      stereo:
        enabled: true
        publish_frequency: 30.0
      pose:
        enabled: true
        publish_frequency: 120.0
  tactile:
    enabled: true
    left:
      sn: 'GF22514064A05'
    right:
      sn: 'GF2251402ECC5'
  realsense:
    enabled: true
    device_serial: "230322274571"
  fisheye:
    enabled: true
    camera_controls:
      auto_exposure: 3
  gripper:
    enabled: true
  ik:
    enabled: false          # 在线 IK

8.2 data_collector.yaml

路径：~/.config/umi/data_collector.yaml

数据采集配置：

enabled: true
save_format: "npy"          # "npy" 或 "hdf5"
save_mode: "sync"           # "sync"(同步) 或 "raw"(原始)
target_fps: 30
save_dir: "~/umi_data"
task_name: "default_task"

快速上手总结

# 1. 安装后绑定设备
vitai-umi-bonding

# 2. (可选) 多设备场景建图
vitai-umi-slam-mapping save ~/.config/umi/cslam_map.bin
# 编辑 sensors.yaml 启用 cslam

# 3. 设置 USB 带宽（双持场景）
echo 512 | sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb

# 4. 启动
vitai-umi-launcher

# 5. 打开浏览器 http://127.0.0.1:8766 开始采集

# 6. Ctrl+C 退出

快速开始​

1. 安装​

1.1 系统要求​

1.2 装 UMI​

2. 设备绑定​

3. 配置文件说明​

3.1 sensors.yaml（设备配置）​

3.2 data_collector.yaml（采集配置）​

4. 启动 & 采集​

5. 多设备建图（可选）​

6. 常见问题​

6.1 设备检测不到 / 显示 UNKNOWN​

6.2 相机掉帧 / 初始化失败​

6.3 上次进程残留​

6.4 sensors.yaml 丢了​

6.5 鱼眼画面太暗/太亮​

7. 数据在哪​

鱼眼相机曝光调节​

8. 配置文件说明​

8.1 sensors.yaml​

8.2 data_collector.yaml​

快速上手总结​