1 准备设备和文件

需要：已经完成装配的 MIDAS Hand，Ubuntu 桌面环境。

2 安装源码和 Python 环境

sudo apt update

sudo apt install python3-venv python3-pip git unzip fonts-dejavu-core

mkdir ~/midas_ws

cd ~/midas_ws

git clone https://github.com/midas-hand-org/midas_hand_api.git

git clone https://github.com/midas-hand-org/midas_hand_mujoco.git

git clone https://github.com/midas-hand-org/midas_hand_retargeter.git

git clone https://github.com/midas-hand-org/midas_hand_teleop.git

首次创建并激活虚拟环境：

cd ~/midas_ws/midas_hand_api

python3 -m venv .venv

source .venv/bin/activate

安装项目依赖：

cd ~/midas_ws

python -m pip install -e "./midas_hand_api[qt]"

python -m pip install -e ./midas_hand_retargeter

python -m pip install -e "./midas_hand_teleop[mujoco]"

3 确认设备并检查通信

lsusb

python -m serial.tools.list_ports -v

ls -l /dev/serial/by-id/

ls -l /dev/v4l/by-id/

本文示例端口如下，请以自己的输出为准：(设备重插后编号可能变化)

运行官方通信测试：

cd ~/midas_ws/midas_hand_api 
python examples/smoke_test.py \
--port /dev/ttyUSB0 \
--baudrate 4000000

成功标准：ID 0～12 全部响应，型号均为 1710，Unexpected model numbers: {}，没有非零硬件错误。

4 首次归零与基础动作

归零会主动驱动关节寻找机械限位。确保运动范围没有物体或手指阻挡

拇指归零

cd ~/midas_ws/midas_hand_api

python -m midas_hand_api --port /dev/ttyUSB0 --home-thumb

三指归零

python -m midas_hand_api --port /dev/ttyUSB0 --home-fingers

成功标准：每个关节输出 hard stop ... -> home_offset ...，最后回软件零位并打印 Config saved，没有超时或异常干涉。中指外展前先屈曲是预设避让动作。

校准文件位于 `~/.midas_hand/config.yaml`，保存在主机，不在手上。正常重启无需重复归零；重新装配、更换舵盘或零点关系改变后需重新归零。换主机要按官方流程处理校准，不能套用别人的偏移值。

cat ~/.midas_hand/config.yaml

官方指尖触碰实验

python examples/finger_touch.py --hand-port /dev/ttyUSB0

成功标准：依次输出 pointer touch、middle touch、ring touch，最后回零并关闭输出；实物动作顺畅。

若出现 target not reached 或明显干涉，停止，不继续加力（强行阻止灵巧手运动会导致关节保护，关节部位闪红灯，电源重启才可以解除）。