星海图A1Z

开机顺序（重要）

1. 插USB-CANFD适配器。
2. 初始化 CAN 总线。
3. 从臂上电（打开电源开关，等待1~2秒自检）。
4. 数采场景最后给主臂（Star-Arm-102）上电。

安装Miniforge

1. 执行如下命令，检查系统信息。

   uname -r        # 应 ≥ 6.8.0-124；低于此版本可能导致 CAN 通信异常（电机使能无反馈）
   python3 --version

2. 执行如下命令，安装Miniforge。

   wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
   bash Miniforge3-$(uname)-$(uname -m).sh          # 默认安装到 ~/miniforge3
   
   # 安装脚本最后选择 yes 执行 conda init，然后重新打开终端
   conda --version

3. 执行以下命令，创建conda环境lerobot061（Python 3.12）。

   conda create -y -n lerobot061 python=3.12
   conda activate lerobot061 
   python -V            # 应为 Python 3.12.x

   conda activate lerobot061  
   
   # 视频解码依赖（TorchCodec 需要 ffmpeg）
   conda install ffmpeg -c conda-forge  
   
   # LeRobot 0.6.1（PyPI Linux wheel 自动携带 CUDA 12.x 版 torch）
   pip install lerobot==0.6.1  
   
   # 验证版本（务必是 0.6.x）
   python -c "import lerobot; print(lerobot.__version__)"   # 应输出 0.6.1

   • 如果GPU驱动较旧（仅支持CUDA 11.x），执行以下命令先安装匹配的torch再安装lerobot。

     pip install torch --index-url https://download.pytorch.org/whl/cu118。

   • 编译报错时，执行以下命令补安装。

     sudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev。

安装A1Z SDK与LeRobot 插件（来自 a1z-teleop 工程）

a1z-teleop数采工程（GitHub：git@github.com:xxxxxx/a1z-teleop.git）同时提供从臂插件lerobot_robot_galaxea_a1z（注册名 galaxea_a1z_follower）与主臂插件lerobot_teleoperator_stararm102。

1. 执行以下命令，云端接入只使用从臂插件，执行setup.sh脚本会一并安装，无需额外操作。

   cd ~/project 
   git clone git@github.com:xxxxxx/a1z-teleop.git 
   cd a1z-teleop  
   
   # 自动激活 lerobot061，安装 A1Z SDK + 主/从臂插件，并运行安装校验
   # A1Z SDK 路径按实际指定（官方 GALAXEA-A1Z 仓库，包名 a1z）
   A1Z_SDK=/path/to/GALAXEA-A1Z bash setup.sh 

2. 执行setup.sh脚本，完成以下步骤（可重复执行）。
   1. 校验当前环境为lerobot061且LeRobot版本为0.6.x。
   2. pip install -e $A1Z_SDK：A1Z SDK（包名a1z，提供CAN 驱动/运动学/动力学）。
   3. pip install fashionstar_uart_sdk pyserial：主臂UART伺服SDK（数采用）。
   4. pip install -e plugins/teleoperator-stararm102：主臂插件（数采用）。
   5. pip install -e plugins/robot-galaxea-a1z ：从臂插件（云端接入用）。
   6. 自动运行 scripts/verify_install.py 校验导入、ChoiceRegistry注册与CLI实例化路径。
   7. 插件不修改lerobot源码树：pip包名以lerobot_robot_ 开头即会被LeRobot 0.6.1的register_third_party_plugins() 自动发现，通过@RobotConfig.register_subclass("galaxea_a1z_follower") 注册robot.type。

安装r2c_sdk到lerobot061环境

机器人侧必须让r2c_sdk与LeRobot运行在同一个Python 环境里，hardware.type: lerobot的适配器在运行时需要 import lerobot、draccus并加载第三方插件。因此将r2c_sdk以editable方式装入lerobot061。

conda activate lerobot061 
cd /path/to/r2c_sdk_python 
pip install -e .

# 依赖自动安装：eclipse-zenoh==1.9.0、protobuf==7.35.1、opencv-python-headless 等
# lerobot / draccus 由 lerobot061 环境已提供，无需重复安装
python -c "from r2c_sdk import ClientConfig, SyncRobotClient; print('r2c_sdk OK')"

r2c_sdk要求Python ≥3.12（requires-python = ">=3.12"），这是必须用Python 3.12创建环境的原因，不要放宽。

交互式标定（首次使用必须）

conda activate lerobot061 
cd ~/project/a1z-teleop  

# 只标定从臂（云端接入只需从臂；主臂联标见 §10.2）
lerobot-calibrate \    
    --robot.type=galaxea_a1z_follower \    
    --robot.can_channel=can0 \    
    --robot.id=follower_a1z 

标定文件位置

~/.cache/huggingface/lerobot/calibration/robots/galaxea_a1z_follower/follower_a1z.json 

文件包含home_rad、range_min_rad、range_max_rad、grip_min_norm、grip_max_norm五个字段。机器人配置中robot.id: follower_a1z与robot.calibration_dir: null（默认 HF 缓存目录）即指向此文件。

云端无人值守运行要点

• 云端/无人值守部署必须提前标定好，且配置中显式runtime.robot_connect.calibrate: false，否则robot.connect() 检测到缺标定文件时会进入交互式input()标定流程并卡死。
• 采集与推理同机时标定文件天然共享，无需重复标定；换臂或零位漂移后需重标。
• teleop_input: rad（云端推理模式）下数学上不依赖home_rad，仅钳到硬件限位，但return_to_zero_on_exit回零仍依赖标定，建议始终保留标定文件。

runtime运行参数

runtime:
  publish_hz: 15.0                  # 观测发布/动作执行频率 (Hz)，建议 10–30
  max_duration_s: 0.0               # 0 = 一直运行，Ctrl+C 停止
  dry_run: false                    # true = 只发观测不执行动作（安全调试）
  action_response_timeout_s: 5.0    # 发布观测后等待 action 超时 (秒)
  max_enqueue_actions_per_chunk: -1 # 每次 chunk 最多入队步数，-1 = 全部
  enable_action_chunk_alignment: false
  publish_trigger_threshold: 0
  skip_initial_observations: 1      # 启动时跳过首帧观测，让动作队列预填充
  async_request: {enabled: false}   # 异步请求融合（默认关闭）
  keyboard_control: {enabled: true} # 键盘控制（空格/暂停, h/回home, e/退出）

• 未写 heartbeat 段时心跳默认开启（每 5 s 上报 status: ONLINE, mode: AUTO到 .../state/heartbeats），CloudRobo 平台据此判断设备在线；可按需显式配置heartbeat: {enabled: true, interval_ms: 1000, status: "ONLINE", mode: "AUTO"}。
• 首次接入务必先 dry_run: true 验证数据流，确认无误后再改回 false。

hardware：通用LeRobot适配器

hardware:
  type: "lerobot"              # r2c_sdk 内置通用适配器 (entry_point 名)
  config:
    runtime:
      robot_connect:
        calibrate: false       # 无人值守必须 false（需已提前标定，见 §6.3）
    robot:
      type: galaxea_a1z_follower   # 插件注册名
      id: follower_a1z             # 标定文件名 = calibration_dir/{id}.json
      calibration_dir: null        # null = 默认 HF 缓存目录
      can_channel: can0            # 按 setup_follower_can.sh 实际输出修改
      gravity_comp_factor: 1.0     # 重力补偿 (0=关, 1=全补偿)
      control_freq_hz: 150         # 150 而非 250：降低 gs_usb CAN 负载
      teleop_input: rad            # 云端动作 = 绝对弧度，钳到硬件限位
      joint_sign: [1,1,1,1,1,1]    # 仅 leader_deg 模式生效；rad 模式不使用
      scale: 1.0                   # 仅 leader_deg 模式生效
      max_step_rad: 0.06           # 每次 setpoint 变化硬上限 (rad)
      max_joint_vel_deg_s: 50.0    # 最大关节速度 (deg/s)
      max_joint_travel_deg: null   # 相对零位 ±N° 软限位；null = 仅标定范围
      return_to_zero_on_exit: true # 退出时平滑回零
      return_speed_deg_s: 25.0
      enable_gripper: true
      gripper_sign: 1              # ★ 必须 +1，见下方说明
      # 以下为独立 MotorB 夹爪驱动遗留参数，SDK 原生夹爪激活时不生效
      gripper_can_id: 7
      gripper_kp: 15.0
      gripper_kd: 0.4
      gripper_max_step_rad: 0.4
      gripper_margin: 0.10
      cameras:
        cam_wrist:            # 腕部相机（键名与 ACT 数据集 observation.images.* 一致）
          type: opencv
          index_or_path: 4    # 对应 /dev/video4，建议改用设备路径防漂移
          width: 640
          height: 480
          fps: 30
        cam_external:         # 头部/全局相机
          type: opencv
          index_or_path: 13   # 对应 /dev/video13（RealSense 515 RGB 最低原生档）
          width: 960
          height: 540
          fps: 30
    commands:
      go_home:
        type: go_home
        joint_names: [joint_1, joint_2, joint_3, joint_4, joint_5, joint_6]
        joints: [...]         # 6 个绝对关节角 (rad)，取自 follower_a1z.json 的 home_rad
        gripper: open

关键说明：

• gripper_sign: +1必须保持：SDK原生Gripper约定0=闭合，1=张开；插件配置默认 -1 是独立 MotorB 驱动时代的遗留值。若此处用 -1，云端推理的夹爪开合方向会与训练数据相反。
• 相机键名cam_wrist / cam_external必须与训练数据集的observation.images.cam_wrist / observation.images.cam_external完全一致，否则策略服务（config/cloud_a1z_act_config.yaml）的特征对齐会失败。
• /dev/videoN编号随重启漂移，推荐使用设备路径index_or_path: /dev/video13 或/dev/v4l/by-id/...稳定路径。
• go_home 只支持 joints（list + joint_names 或 dict），不支持pose_euler/pose_quat（LeRobot无IK）。

device_to_r2c：设备观测数据到R2C上行

A1Z get_observation() 输出键：joint_1..joint_6（rad）、gripper（归一化：0=闭合；1=张开）、相机名（RGB ndarray）。

device_to_r2c:
  task: A1Z arm teleoperation
  image_encoding: jpeg
  mappings:
    - target_key: "joint_states.names"
      default: ["arm_joint1", ..., "arm_joint6", "gripper"]
    - target_key: "joint_states.position"      # [j1..j6 (rad), gripper (0~1)]
      source_paths: ["joint_1", "joint_2", "joint_3", "joint_4", "joint_5", "joint_6", "gripper"]
    - target_key: "images.color.front"         # R2C 上行通道名
      source_path: "cam_external"
      transforms: [ndarray_to_jpeg]
    - target_key: "images.color.wrist"
      source_path: "cam_wrist"
      transforms: [ndarray_to_jpeg]

注意区分两层命名：设备键名cam_external/cam_wrist（对齐训练数据集特征），R2C上行通道名images.color.front/images.color.wrist。

r2c_to_device：云端动作到设备指令

r2c_to_device:
  mappings:
    - target: "joint_1"       # 6 个关节：source_index 0..5
      source: "joint_states.position"
      source_index: 0
      required: true
    # ... joint_2 .. joint_6 依次 source_index 1..5
    - target: "gripper"       # 夹爪：source_index 6
      source: "joint_states.position"
      source_index: 6
      required: false         # 云端只发 6 关节时夹爪保持当前位置

云端joint_states.position为7元素list：[j1..j6 (rad), gripper (0~1)]。teleop_input: rad模式下插件直接使用绝对弧度，与 gripper_sign: +1 配合，开合方向与训练数据一致。

dry_run冒烟测试（不执行动作）

conda activate lerobot061
cd /path/to/r2c_sdk_python
python -m r2c_sdk.cloudroboclient \
  --robot-config config/robot_a1z_lerobot_v2_config.yaml \
  --bundle config/配置文件名.zip \
  --log-level DEBUG \
  --duration 30

此时将robot_a1z_lerobot_v2_config.yaml 中的runtime.dry_run临时改为true。

预期日志：插件注册成功、RobotConfig 解码成功、观测正常发布、动作以[DRY_RUN]打印但不执行。

真实硬件启动

# 前置：CAN 已初始化（§5）、机械臂已上电、标定已完成（§6）
# 将 dry_run 改回 false 后：
python -m r2c_sdk.cloudroboclient \
  --robot-config config/robot_a1z_lerobot_v2_config.yaml \
  --bundle config/配置文件名.zip \
  --log-level INFO \
  --log-file /tmp/a1z_r2c.log

启动后预期日志：

Creating new robot instance from adapter config. Using robot config decoder: _default_robot_config_decoder Building robot instance via lerobot.robots.make_robot_from_config. Adapter connected successfully. Heartbeat auto publish started (interval_ms=5000, ...) 

此时机械臂进入位置保持模式（重力补偿 + PD），锁定在当前姿态。

（可选）观测录制

python -m r2c_sdk.cloudroboclient \
  --bundle config/配置文件名.zip \
  --robot-config config/robot_a1z_lerobot_v2_config.yaml \
  --record recordings/a1z_demo.r2cr

键盘控制

键盘控制在非TTY终端（部分IDE内嵌终端）可能不响应，请在真实终端运行。

连接配置（三种方式）

• 方式一：ClientConfig YAML（推荐，便于版本管理）

  config/client_config.yaml：

  project_id: "<CloudRobo 平台分配的项目 ID>"
  device_id: "<设备 ID，项目内唯一>"
  client_id: "a1z-001"
  endpoints: ["tcp/<平台 Zenoh Router 地址>:7447"]  # 由平台/管理员提供
  mode: "client"          # client = 仅经 Router 转发；peer = 支持 P2P 直连
  protocol: "zenoh"

  python -m r2c_sdk.cloudroboclient \
    --client-config config/client_config.yaml \
    --robot-config config/robot_a1z_lerobot_v2_config.yaml

平台侧验证

1. 设备在线：CloudRobo 平台控制台应能看到设备在线（依赖心跳.../state/heartbeats，默认 5 s 一次，可在 config 中调快）。
2. 观测上行：平台端能看到 .../inference/observations 的关节状态与两路图像。
3. 动作闭环：策略服务启动后，动作经 .../inference/actions 下发，机械臂开始执行推理轨迹（日志中每步动作 send_action 有 DEBUG 记录）。
4. 弱网/大模型场景：把 runtime.action_response_timeout_s 调到 ≥30 s，避免超时重发风暴。

数采硬件与权限

• 主臂Star-Arm-102：USB（CH340，/dev/ttyUSB0），12V 10A供电；
• 一次性安装串口udev规则（否则每次插拔后权限变回 root:dialout）：

sudo bash ~/project/a1z-teleop/setup_leader_uart.sh 

主从臂联合标定（首次使用必须）

cd ~/project/a1z-teleop 
bash calibrate.sh        # LEADER_PORT=/dev/ttyUSB1 CAN=can1 bash calibrate.sh 可覆盖端口

依次完成：

1. 从臂标定。
2. 主臂标定：握着主臂摆出与从臂零位相同的姿态扶稳按 Enter记录homing_offset_deg，再逐关节扫限位。

标定文件：

~/.cache/huggingface/lerobot/calibration/robots/galaxea_a1z_follower/follower_a1z.json   # 从臂 
~/.cache/huggingface/lerobot/calibration/teleoperators/stararm102_leader/leader1.json    # 主臂 

实时遥操作验证

bash scripts/teleop.sh
# 更保守速度: bash scripts/teleop.sh --robot.max_joint_vel_deg_s=20
# Ctrl-C 停止，从臂自动回零

先用python scripts/test_teleop.py --dry-run检查各关节方向（观察 "target" 列），

方向反了用--flip N反转并同步到采集命令的 joint_sign。

数据采集（推荐 absolute_rad 模式）

cd ~/project/a1z-teleop
REPO_ID=my_user/my_dataset TASK="pick and place" bash scripts/record.sh \
    --teleop.output_mode=absolute_rad \
    --teleop.joint_sign='[-1, 1, 1, 1, -1, -1]' \
    --teleop.gripper_sign=1 \
    --robot.teleop_input=rad \
    --robot.gripper_sign=1 \
    --robot.cameras='{cam_external: {type: opencv, index_or_path: /dev/video13, width: 960, height: 540, fps: 30},
                      cam_wrist:    {type: opencv, index_or_path: /dev/video4,  width: 640, height: 480, fps: 30}}' \
    --dataset.episode_time_s=300 --dataset.reset_time_s=5 --dataset.num_episodes=100

• 环境变量：REPO_ID（数据集名）、TASK（任务描述）、EPISODES（默认 10）。
• 操作键：→（右方向键） 结束当前 episode，←（左方向键） 重录上一个episode，Esc停止采集。
• 相机键名 cam_external/cam_wrist 与云端推理配置一致；/dev/video13（RealSense 515 RGB）最低原生档为 960×540（无 640×480 模式），比 1280×720 少约 44% 像素，降低 ACT 训练显存压力。
• 数据保存在本地 ~/.cache/huggingface/lerobot/<repo_id>/；加 --dataset.push_to_hub=true可上传Hub。
• 续录已有数据集：追加--resume=true。

为什么推荐absolute_rad：

1. action 与 observation.state同坐标系同单位（绝对弧度），策略可利用"恒等先验"（action ≈ 当前状态即保持不动），冷启动稳定、收敛快。
2. 推理侧 teleop_input="rad" 不依赖标定零位，换臂/零位漂移不破坏动作基准。
3. 数据自包含可移植，与主流开源数据集惯例一致。

前提（务必确认）：采集前必须完成从臂标定，主臂absolute_rad输出需要读follower_a1z.json的home_rad，文件缺失时只警告并静默退化为相对弧度，录出的数据坐标系错误。joint_sign也必须先用 test_teleop.py --dry-run验证。

数据集结构与训练

~/.cache/huggingface/lerobot/<repo_id>/
├── meta/        # info.json (v3.0, fps, 特征定义)、episodes/、tasks.jsonl、stats.json
├── data/        # parquet 帧数据
└── videos/      # 视频帧

特征：observation.state（7维：joint_1..joint_6弧度+gripper 归一化）、

action（absolute_rad模式下同为弧度）、observation.images.*。

ACT训练示例：

conda activate lerobot061
cd ~/project/a1z-teleop
lerobot-train \
    --policy.type=act \
    --policy.push_to_hub=false \
    --dataset.repo_id=<repo_id> \
    --output_dir=outputs/train \
    --job_name=act_a1z \
    --steps=100000 --batch_size=16 --num_workers=8 \
    --save_freq=20000 --eval_steps=10000 \
    --wandb.enable=false

数采到云端推理衔接要点

三者共用同一份插件实现与标定文件，是“数采 > 训练 > 云端推理”闭环一致性的保证。