Files

150 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 环境配置
## 系统与连接
- Ubuntu 24.04 x86_64,Python 3.12 + venv;不使用 conda。
- ROS 2 Jazzy;需要 rclpy、sensor_msgs、geometry_msgs、control_msgs、trajectory_msgs、shape_msgs、std_srvs、rosidl_runtime_py 和 moveit_msgs。几何模块复用消息类型,不要求启动 MoveIt Servo。
- D405 使用 realsense2_camera,848×480、30 FPS、对齐深度;执行入口会复用或启动相机驱动。避免其他程序独占设备。
- 下位机地址 192.168.10.21,原生 ROSBridge 端口 9090,机械臂保留厂家桥服务及反馈接口。
- 左手 can0,1 Mbps,通过CAN返回的SN核对G20/LHT20型号和左手标识,不默认绑定单台设备SN。标定表随包提供;更换设备仍需确认角度标定,不能仅凭左右手相同直接套用。
- ROS_DOMAIN_ID 默认 29。主机和下位机网络、USB/CAN 权限由现场配置。
先按 [ROS 2 Jazzy 官方安装说明](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html) 配置 Ubuntu 24.04 的 ROS 软件源。已配置软件源的机器可补充系统组件:
~~~bash
sudo apt install python3.12-venv python3-pip iproute2 can-utils usbutils kmod libgl1 libglib2.0-0 \
ros-jazzy-ros-base ros-jazzy-realsense2-camera ros-jazzy-rosbridge-server \
ros-jazzy-control-msgs ros-jazzy-trajectory-msgs ros-jazzy-shape-msgs \
ros-jazzy-moveit-msgs ros-jazzy-rosidl-runtime-py
bash scripts/setup.sh
bash run.sh check
~~~
requirements.txt 锁定原工作环境中实际使用的直接依赖版本。setup.sh 创建独立 .venv,并允许访问系统 ROS Python 包;不复制旧 venv。SDK 动态库随包保留在 runtime/arm/vendor,Linux x86_64 使用,其他架构需厂家对应库。
## 官方 SDK 与驱动来源
| 组件 | 来源与使用方式 |
| --- | --- |
| A7 在线控制器 SDK 1.0.5 | [SDK 源码与下载入口](https://gitee.com/meng_fan_ji/lbot_arm_api),随包来源 commit 为 e1c4a4523a46e80e40c5dbe8cc651f2cf5fa4a51。原厂库、头文件及 SHA256 记录在 runtime/arm/vendor/lbot_sdk/provenance.json;无需再次下载相同平台的库。 |
| RealSense SDK / Linux 驱动 | [librealsense](https://github.com/realsenseai/librealsense)、[官方 Linux 安装说明](https://github.com/realsenseai/librealsense/blob/master/doc/distribution_linux.md)。 |
| RealSense ROS 2 驱动 | [realsense-ros 官方安装说明](https://github.com/realsenseai/realsense-ros#installation-on-ubuntu)。本项目用 Jazzy 的 realsense2_camera。 |
| Linux CAN 驱动层 | [内核 SocketCAN 文档](https://docs.kernel.org/networking/can.html)。具体 USB-CAN 设备还需要匹配的内核驱动/固件。 |
| CAN 命令行工具 | [linux-can/can-utils](https://github.com/linux-can/can-utils),Ubuntu 软件包为 can-utils。 |
| Python CAN 接口 | [python-can SocketCAN 文档](https://python-can.readthedocs.io/en/stable/interfaces/socketcan.html),requirements.txt 已固定 python-can==4.6.1。 |
机械臂通过以太网连接在线控制器;本流程的 can0 用于 G20 左手,不要求给机械臂安装直连 CAN SDK。pip 安装 python-can 不会安装 USB-CAN 内核驱动。ROSBridge 客户端 roslibpy 已在 requirements.txt 中;主机安装 rosbridge-server 不会替代下位机已有的厂家服务。
## D405 相机驱动与检查
默认使用 ROS 软件源提供的 librealsense 和 ROS Wrapper,避免同时混装源码版与其他来源的库:
~~~bash
sudo apt update
sudo apt install 'ros-jazzy-librealsense2*' ros-jazzy-realsense2-camera
source /opt/ros/jazzy/setup.bash
ros2 pkg prefix realsense2_camera
lsusb
lsusb -t
~~~
将 D405 接到可靠的 USB 3 数据接口。相机 USB 权限需要 RealSense 的 udev 规则;安装后重新插拔相机。若设备识别、权限或内核兼容性仍有问题,按上方官方 Linux 指南核对当前内核支持范围和 udev 配置。采用厂家 Debian 驱动路线时,依指南配置厂家软件源并安装 librealsense2-dkms、librealsense2-utils、librealsense2-dev;这是替代安装路线,不应无条件叠加到已有源码/ROS SDK 安装之上。DKMS 与当前内核及 Secure Boot 配置需兼容。
厂家工具路线可用 rs-enumerate-devices 查看设备与支持的流配置,或用 realsense-viewer 看图;ROS 软件包路线不保证附带这两个工具。检查完关闭 Viewer 和直接 USB 采集程序,再启动 ROS 相机,避免争用同一 D405。默认抓取通过 ROS 获取图像,不需要另外 pip 安装 pyrealsense2。
仅检查相机时,可在独立终端启动与项目一致的配置:
~~~bash
source /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=29
ros2 launch realsense2_camera rs_launch.py \
camera_namespace:=camera camera_name:=camera \
enable_color:=true enable_depth:=true \
rgb_camera.color_profile:=848x480x30 \
depth_module.depth_profile:=848x480x30 \
align_depth.enable:=true
~~~
在另一终端检查(观察后 Ctrl-C 退出 hz):
~~~bash
source /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=29
ros2 topic list
ros2 topic echo /camera/camera/color/camera_info --once --qos-reliability best_effort
ros2 topic hz /camera/camera/color/image_raw
ros2 topic hz /camera/camera/aligned_depth_to_color/image_raw
~~~
应能收到新的彩色图、对齐深度和有效相机内参,目标频率约 30 Hz;仅能列出话题不等于收到图像。主流程可以复用相同域/名称的驱动,不要重复启动。若报设备忙或 VIDIOC_S_FMT,先检查是否已有 ROS 相机、Viewer 或直连采集程序占用;不要用重新安装驱动代替占用排查。
## G20 左手 CAN 驱动与检查
通信链路为:G20 → USB-CAN 适配器 → 对应内核驱动 → SocketCAN can0 → python-can → 本项目 G20 协议代码。适配器需支持 Linux SocketCAN、经典 CAN 和 1 Mbps;仓库不绑定某个 USB-CAN 型号,也不包含所有厂家驱动。
先识别设备和已有驱动:
~~~bash
sudo apt install iproute2 can-utils usbutils kmod
lsusb
ip -details link show type can
# 已有 can0 时查看实际绑定驱动;部分虚拟/串口接口无此路径
readlink -f /sys/class/net/can0/device/driver
~~~
若未出现 CAN 网络接口,应根据适配器型号、USB VID/PID 和厂家说明安装对应驱动,而不是反复运行 ip link:
- gs_usb / candleLight 兼容设备使用内核 gs_usb 驱动;仅确认适配器兼容后运行 sudo modprobe gs_usb。
- 串口 SLCAN 设备需按厂家串口协议、速率和固件配置 slcan/slcand;普通 USB 串口不自动等于 CAN 接口。
- 专有 USB-CAN 设备按其厂家 Linux 文档安装,确认最终提供 SocketCAN 接口。仅有专有动态库、没有 SocketCAN 的设备不能直接替换本项目的 can0。
- 若当前内核缺少所需模块,安装匹配当前内核的 Ubuntu 模块包或厂家驱动;不要将 gs_usb 当成所有设备的通用驱动。
设备空闲且接口已确认对应左手后,加载 CAN 协议模块并配置接口。若已在 1 Mbps 正常运行,仅检查即可,不要在控制期间 down/up:
~~~bash
sudo modprobe can
sudo modprobe can_raw
sudo ip link set dev can0 down
sudo ip link set dev can0 type can bitrate 1000000
sudo ip link set dev can0 up
ip -details -statistics link show dev can0
~~~
配置网络接口需要管理员权限;Python 抓取程序使用项目 venv,不以 sudo 代替环境安装。确认 CAN_H/CAN_L、参考地、独立供电和总线两端终端电阻符合设备说明;USB 接入不代表手本体已经供电。多适配器情况下先确认接口与设备对应关系,不能假定枚举出的 can0 一定是左手。
被动查看总线接收帧(不发送位置指令):
~~~bash
timeout 5s candump can0
ip -details -statistics link show dev can0
.venv/bin/python -c "import can; print(can.__version__)"
~~~
candump 等待到时退出属于正常现象;查询应答型设备在没有查询时可能完全无帧,因此空输出不能单独判故障,接口 UP 也不能证明设备有应答。检查 RX/TX、错误计数及 BUS-OFF 状态,再由项目既有身份/反馈预检确认实际左手。不要用随机 cansend/cangen 帧测试接有真机的总线。上述安装和接口检查不会替代设备身份、标定及执行前检查。
## 配置
需要覆盖解释器、ROS 环境或域号时,将 config/local.env.example 复制为 config/local.env 后编辑。文件已排除出 Git。直接运行 Python 模块前,先 source scripts/environment.sh,再 source 对应 ROS setup.bash。
config/camera_extrinsics_current.json 为共同 base_link 外参,右臂标定的指尖偏移不用于左手。视觉主线使用每轮新 RGB-D 与实测局部运动映射;默认杯子模式使用已保存的 HUG 形状模板,再优化当前几何,不要求现场运行大模型。
## 可选新物体 HUG 模式
--object-mode pointcloud 不是默认杯子流程。额外需要 HUG 源码、hug_full.safetensors 权重和其独立推理环境,以及 retarget_l20_v2.py 所在 retargeting 目录、dex-retargeting / pinocchio / PyYAML 环境。通过 HUG_ROOT、RETARGETING_ROOT、RETARGET_PYTHON 配置;权重和这些独立环境不包含在本仓库。本次不宣称此可选模式完成独立安装验收。
## 可选通用轨迹回放
默认杯子观察位路线不需要此组依赖。使用 runtime/arm 的通用 follow 轨迹规划时,先安装并编译离线 MoveIt TOTG 辅助程序:
~~~bash
sudo apt install g++ libeigen3-dev ros-jazzy-moveit-core ros-jazzy-ruckig
.venv/bin/python -m pip install -r requirements-replay.txt
.venv/bin/python runtime/arm/build_totg.py
~~~
源文件为 runtime/arm/cpp/totg_offline.cpp,输出 runtime/arm/build/totg_offline。构建与离线定时均不连接机器人;实际执行仍受原控制检查约束。CUP_ROS_PREFIX 可覆盖 ROS 安装目录,默认从 CUP_ROS_SETUP 推导。
## 手眼标定教程
独立项目:[a7-handeye-calibration](https://gitea.robotquan.com/liyang/a7-handeye-calibration)。按[完整教程](https://gitea.robotquan.com/liyang/a7-handeye-calibration/src/branch/main/WORKFLOW.md)完成左右臂只读采点、求解和独立验证,再备份并替换本项目config/camera_extrinsics_current.json。默认抓取使用新RGB-D直接视觉伺服,不需要掌心Tag。