ForceEase A1 开发文档

Overview

用程序控制机械臂

ForceEase A1 SDK 可连接设备、读取状态、同步控制关节、开合夹爪、拖动示教、 复位、紧急停止和安全停机。按项目选择 Python、C++ 或 ROS。

Quickstart

一分钟选择合适的 SDK

脚本和教学选 Python；Linux 工程选 C++；ROS2、MoveIt 或 ros2_control 项目选 ROS SDK。

Python SDK

安装与快速开始

Python SDK 用于实验、课程演示和自动化脚本。需要 Python 3.8 或更高版本， 支持 Windows、macOS 和 Linux。建议安装在虚拟环境中。

pip install zeroArm-sdk

安装完成后可以检查版本：

python3 -c "import zeroArm_sdk; print(zeroArm_sdk.__version__)"

推荐控制流程

import asyncio
from zeroArm_sdk import RobotArm

async def main():
    arm = RobotArm()

    success = await arm.auto_discover_and_connect(timeout=3.0)
    if not success:
        print("未发现 ForceEase A1 设备或连接失败")
        return

    print(f"已成功连接机械臂：{arm.sn[:6]}...")

    def state_handler(state):
        if state.eef_pose:
            print(
                f"末端位姿: x={state.eef_pose.x:.3f}m, "
                f"y={state.eef_pose.y:.3f}m, z={state.eef_pose.z:.3f}m"
            )

    arm.on_state_update(state_handler)
    await arm.back_to_initial()

    ok = await arm.set_joints_batch(
        joint_targets=[
            (1, 0.52), (2, -0.35), (3, 1.57),
            (4, 0.0), (5, 0.0), (6, 0.0),
        ],
        wait_for_completion=True,
        timeout=10.0,
        tolerance=0.015,
    )
    print("到达目标" if ok else "运动超时或未完全到达目标")

    await arm.set_gripper(target_pos=0.08)
    await arm.gracefully_shutdown(wait_before_shutdown=5.0)

if __name__ == "__main__":
    asyncio.run(main())

多臂环境中可以使用序列号前缀连接，建议至少使用前 8 位，例如 await arm.connect_with_short_sn("<SN-PREFIX>")。

C++ SDK

工程集成与快速示例

C++ SDK 用于 Linux 工程和高频控制。按安装包说明准备编译工具和依赖库。

curl -L -O https://robotic.forceease.tech/cpp-sdk/current/zeroArm_sdk-linux-x86_64.tar.gz
tar -xzf zeroArm_sdk-linux-x86_64.tar.gz
cd zeroArm_sdk
sudo bash install_zeroarm_sdk.sh

ForceEase 服务器下载入口：

安装完成后可以验证版本和 CMake 示例：

pkg-config --modversion zeroArm_sdk
cmake -S examples -B /tmp/zeroarm_sdk_example_build -DCMAKE_PREFIX_PATH=/usr/local
cmake --build /tmp/zeroarm_sdk_example_build

手动集成时，可在项目的 CMake 配置中链接 SDK：

find_package(zeroArm_sdk 0.2 REQUIRED CONFIG)
target_link_libraries(your_target PRIVATE zeroArm_sdk::zeroArm_sdk)

快速示例

#include <zero_arm_sdk/zero_arm_sdk.h>
#include <chrono>
#include <cstdint>
#include <iostream>
#include <thread>
#include <utility>
#include <vector>

int main() {
    using namespace zeroArm_sdk;
    using namespace std::chrono_literals;

    RobotArm arm;
    if (!arm.auto_discover_and_connect(3s, 5s)) {
        std::cerr << "连接失败\n";
        return 1;
    }

    arm.on_state_update([](const FullArmState& state) {
        if (state.eef_pose) {
            std::cout << "末端 z = " << state.eef_pose->z << "m\n";
        }
    });

    arm.back_to_initial();
    std::this_thread::sleep_for(1s);

    const std::vector<std::pair<int32_t, float>> targets = {
        {1, 0.52f}, {2, -0.35f}, {3, 1.57f},
        {4, 0.0f}, {5, 0.0f}, {6, 0.0f},
    };

    const bool reached = arm.set_joints_batch(
        targets, 0.0f, 0.0f, 0, true, false,
        10.0f, 30.0f, 50.0f, true, 10s, 0.015f);

    std::cout << (reached ? "到位\n" : "超时\n");
    arm.gracefully_shutdown(5s);
    return reached ? 0 : 2;
}

ROS SDK

安装并构建 ROS2 workspace

在 ROS2 workspace 内运行安装脚本，完成 C++ SDK 安装、rosdep 依赖解析和 colcon build。

1. 在 ROS workspace 内运行

cd rosSDK/ROS2
curl -L -O https://robotic.forceease.tech/ros-sdk/install_zeroarm_ros2_sdk.sh
bash install_zeroarm_ros2_sdk.sh

如果使用仓内源码，脚本已经在 workspace 内：

cd rosSDK/ROS2
bash scripts/install_zeroarm_ros2_sdk.sh

2. 常用参数

bash install_zeroarm_ros2_sdk.sh --dry-run
bash install_zeroarm_ros2_sdk.sh --prefix /opt/zeroarm-sdk
bash install_zeroarm_ros2_sdk.sh --skip-cpp-sdk --skip-rosdep

默认 ROS distro 为 humble，默认 C++ SDK prefix 为 /usr/local。

3. 验证 ROS SDK

source install/setup.bash
ros2 pkg list | grep robot_arm_hardware
grep '^zeroArm_sdk_DIR:PATH=' build/robot_arm_hardware/CMakeCache.txt
ros2 launch robot_arm_moveit real_moveit.launch.py

API Reference

常用接口速查

Safety

安全建议与连接排查

• 机械臂上电后等待 5-10 秒，再进行连接和控制。
• 连接成功后建议先调用 back_to_initial()，让机械臂进入可预期姿态。
• 批量关节控制优先使用等待到达目标的模式，并设置合理超时和容差。
• 调试阶段优先使用保守速度，确保工作空间内没有人员或障碍物。
• 连接失败时，请先确认电脑和机械臂连接在同一个网络中。
• 如果公司、学校或实验室网络限制较多，请确认防火墙没有阻止机械臂通信。
• 多臂环境中不要使用过短序列号前缀，建议至少使用前 8 位。
• ROS 构建如果仍解析到 /tmp/zeroarm_cpp_sdk_ros_install，请从 CMAKE_PREFIX_PATH 中移除该旧测试路径后重新构建。
• C++ SDK 安装后先用 pkg-config --modversion zeroArm_sdk 确认版本，再接入自己的工程。