WoanArm API 用户版

本目录提供OneRobotics A1 机械臂的预编译 SDK 与安装包，面向用户可直接安装使用。

目录结构

woanarm_api_for_user/
├── README.md                 # 本文件（安装与 API 说明）
├── C_API/                    # C/C++ 预编译 SDK
│   ├── Linux-x86_64/         # Linux 平台 SDK
│   └──  Windows-x86_64/       # Windows 平台 SDK
└── Python_conda_channel/     # Python conda channel
    ├── linux-64/             # Linux 平台 conda 包
    └── win-64/               # Windows 平台 conda 包

安装方式

一、C/C++ SDK 安装

适用于需要 C/C++ 接口进行二次开发的场景。

支持环境

Linux: Ubuntu 20.04+ (x86_64)
Windows: Windows 10/11 (x86_64)
C++ 标准: C++17 及以上
依赖管理: 推荐使用 Conda 或 Micromamba

1. 准备依赖环境

# 创建环境并安装依赖 (Linux/Windows 通用)
conda create -n woanarm_cpp -c conda-forge cmake ninja compilers eigen boost pinocchio hpp-fcl urdfdom pkg-config -y
conda activate woanarm_cpp

2. 安装 SDK

将 C_API/Linux-x86_64/ 或 C_API/Windows-x86_64/ 下的压缩包解压后，SDK 根目录结构为 include/、lib/ 等。按以下方式之一使用：

方法 A：安装到 Conda 环境（推荐）

进入解压后的 SDK 根目录（如 woanarm_api_c-1.0.0-Linux）：

Linux:

cp -r include/* $CONDA_PREFIX/include/
cp -r lib/* $CONDA_PREFIX/lib/

Windows (PowerShell):

Copy-Item -Path "include\*" -Destination "$env:CONDA_PREFIX\Library\include" -Recurse
Copy-Item -Path "lib\*" -Destination "$env:CONDA_PREFIX\Library\lib" -Recurse
Copy-Item -Path "bin\*" -Destination "$env:CONDA_PREFIX\Library\bin" -Recurse

方法 B：手动指定路径

解压到任意位置，CMake 配置时指定 woanarm_DIR：

# Linux 示例（解压后目录含 include/lib/cmake）
cmake .. -Dwoanarm_DIR=/path/to/woanarm_api_c-1.0.0-Linux/lib/cmake/woanarm

# 若在本仓库内测试，可使用：
cmake .. -Dwoanarm_DIR=$PWD/../Linux-x86_64/woanarm_api_c-Linux-x86_64/woanarm_api_c-1.0.0-Linux/lib/cmake/woanarm

3. 验证安装

使用 C_API/test/ 下的验证程序测试 SDK 是否能正确编译、链接：

cd C_API/test
mkdir -p build && cd build
# 需在 conda 环境内，确保依赖一致（避免与系统 ROS/Boost 冲突）
conda activate woanarm_cpp   # 或 woanarm（若已安装 pinocchio/eigen/boost/hpp-fcl）
cmake .. -Dwoanarm_DIR=../Linux-x86_64/woanarm_api_c-Linux-x86_64/woanarm_api_c-1.0.0-Linux/lib/cmake/woanarm
make -j
./sdk_test

输出 [SUCCESS] SDK 头文件与库链接正常 即表示安装成功。无机械臂连接时 create_robot 返回 nullptr 属正常情况。

二、Python 安装

适用于使用 Python 进行快速开发的场景。

支持环境

Linux: Ubuntu 20.04+ (x86_64)
Windows: Windows 10/11 (x86_64)
Python: 3.12 (推荐)

1. 准备环境

推荐使用全新环境，避免与已有包（如 mamba）产生依赖冲突：

conda create -n woanarm python=3.12 -y
conda activate woanarm

2. 使用本地 conda channel 安装

在 woanarm_api_for_user 目录下执行：

# 使用 conda
conda install -c conda-forge -c ./Python_conda_channel woanarm_api_py -y

# 或使用 micromamba
micromamba install -c conda-forge -c ./Python_conda_channel woanarm_api_py -y

3. 验证安装

python -c "import woanarm_api_py; print('安装成功！模块路径:', woanarm_api_py.__file__)"

C/C++ API 说明

CMake 集成

在 CMakeLists.txt 中添加：

cmake_minimum_required(VERSION 3.15)
project(my_robot_app)

find_package(woanarm REQUIRED)

add_executable(main main.cpp)
target_link_libraries(main PRIVATE woanarm::core)

C++ 接口

接口位于 woan_api 命名空间，通过 WoanAPI 类的静态方法调用。

机器人生命周期管理

#include "woan_api/woan_interface.h"

// 1. 配置
woan_api::woan_config_t cfg;
std::strcpy(cfg.device, "/dev/ttyACM0");
std::strcpy(cfg.robot_model, "a1_r");
std::strcpy(cfg.version, "A1");
std::strcpy(cfg.model_description_path, "/path/to/woan_description");

// 2. 创建对象
woan_api::woan_robot_handle* arm = woan_api::WoanAPI::create_robot(cfg);

// 3. 使能 (返回 0 成功)
if (woan_api::WoanAPI::enable_motors(arm) == 0) {
    std::cout << "电机已使能" << std::endl;
}

// 4. 销毁
woan_api::WoanAPI::destroy_robot(arm);

关节空间运动 movej()

static int movej(woan_robot_handle* handle, const JointArray& target, uint8_t trajectory_connect = 0);

target: 目标关节角度 (std::vector<double>)
trajectory_connect: 1 加入缓冲区，0 立即执行

笛卡尔空间直线运动 movel()

static int movel(woan_robot_handle* handle, const Pose& pose, double speed_scale = 1.0, uint8_t control_mode = 0, uint8_t trajectory_connect = 0);

pose: 目标位姿 (x, y, z, qw, qx, qy, qz)
control_mode: 0 位置控制，1 MIT 柔顺力控

笛卡尔空间点到点运动 movep()

static int movep(woan_robot_handle* handle, const Pose& pose, double speed_scale = 1.0, uint8_t trajectory_connect = 0);

高精度到达目标位姿，运动更平滑，但不保证中间路径为直线

纯 C 接口

位于 woan_api_c/woan_interface_c.h。

生命周期管理 (C)

#include "woan_api_c/woan_interface_c.h"

woan_c_config_t cfg = {0};
strcpy(cfg.device, "/dev/ttyACM0");
cfg.dof = 7;

woan_c_handle arm = woan_c_create_robot(&cfg);
woan_c_enable_motors(arm);

// ... 执行任务 ...

woan_c_destroy_robot(arm);

运动控制 (C)

movej: woan_c_movej(handle, const woan_c_joint_array_t* target, ...)
movel: woan_c_movel(handle, const woan_c_pose_t* pose, ...)
movep: woan_c_movep(handle, const woan_c_pose_t* pose, ...)

核心结构体:

typedef struct {
    double data[WOAN_MAX_JOINT_COUNT];
    int count;
} woan_c_joint_array_t;

typedef struct {
    double x, y, z;
    double qw, qx, qy, qz;
} woan_c_pose_t;

Python API 说明

机器人生命周期管理

import woanarm_api_py as woan

# 1. 配置
config = woan.WoanConfig()
config.device = "/dev/ttyACM0"  # Linux: "/dev/ttyACM0", Windows: "COM3"
config.robot_model = "a1_r"
config.version = "A1"
config.model_description_path = "path/to/woan_description"

# 2. 实例化
arm = woan.WoanArm(config)

# 3. 使能 (返回 True 成功)
if arm.enable_motors():
    print("电机已使能")

# 4. 失能
arm.disable_motors()

关节空间运动 movej()

movej(self, target: list[float], speed_scale: float = 1.0, trajectory_connect: int = 0) -> int

target: 目标关节角度数组 (弧度)
speed_scale: 速度比例 (0.01 ~ 2.0)，默认 1.0
trajectory_connect: 0 立即执行，1 加入缓冲区

示例:

arm.movej([0.0] * 7, speed_scale=1.0)

笛卡尔空间直线运动 movel()

movel(self, pose: Pose, speed_scale: float = 1.0, control_mode: int = 0, trajectory_connect: int = 0) -> int

pose: 目标位姿 (x, y, z, qw, qx, qy, qz)
control_mode: 0 标准位置控制，1 MIT 柔顺力控

示例:

p = woan.Pose()
p.x, p.y, p.z = 0.3, 0.0, 0.4
p.qw, p.qx = 1.0, 0.0
arm.movel(p, speed_scale=0.5)

笛卡尔空间点到点运动 movep()

movep(self, pose: Pose, speed_scale: float = 1.0, trajectory_connect: int = 0) -> int

pose: 目标位姿，与 movel 不同，movep 仅保证平滑到达目标点，不保证轨迹为直线

示例:

p = woan.Pose()
p.x, p.y, p.z = -0.36, 0.38, 0.30
p.qw, p.qx, p.qy, p.qz = 0.1, 0.7, -0.2, 0.6
arm.movep(p, speed_scale=0.5)

常见问题排查

C/C++

Q: CMake 报错 Could not find a package configuration file provided by "woanarm"？

确认 SDK 已复制到 $CONDA_PREFIX，或在 cmake 中通过 -Dwoanarm_DIR=... 指定正确路径。

Q: 报错找不到 pinocchio、Eigen3、hpp-fcl？

使用 conda install -c conda-forge pinocchio eigen hpp-fcl 安装依赖，并确保已激活对应环境。

Q: 编译时出现 Boost mpl::vector 模板参数错误？

多为系统 Boost/Pinocchio（如 ROS）与 SDK 依赖版本不一致。必须在 conda 环境内使用 conda 安装的 pinocchio、boost、eigen、hpp-fcl 进行编译，不要混用系统库。

Q: Windows 下运行提示找不到 DLL？

确保 bin 目录下 DLL 在 PATH 中，或将 DLL 与可执行文件放在同一目录；使用 Conda 环境时，激活环境通常会自动配置 PATH。

Python

Q: 安装时提示 PackagesNotFoundError: woanarm_api_py？

使用实际路径，不要用 /path/to/... 占位符；确保 channel 根目录存在 noarch/repodata.json，且 linux-64/ 下直接包含 woanarm_api_py-*.conda（不能嵌套在 linux-64/linux-64/ 中）。

Q: 安装时提示 UnsatisfiableError 或 LibMambaUnsatisfiableError？

多为环境内已有包与 woanarm 依赖冲突。推荐使用全新环境：conda create -n woanarm python=3.12 -y && conda activate woanarm，再执行安装。
安装命令中需包含 -c conda-forge，本库依赖的 Pinocchio、Eigen 等托管在 conda-forge。

Q: Windows 下 import 报错 ImportError: DLL load failed？

确认已 conda activate woanarm，且 IDE 使用的是该 conda 环境的 Python 解释器。

Q: 提示 Serial device not found？

Linux: 检查 /dev/ttyACM* 是否存在，sudo chmod 666 /dev/ttyACM0 确保有权限。
Windows: 在设备管理器中确认 COM 端口号，并在代码中修改 config.device。

许可证

MIT License

维护者

OneRobotics 团队

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
C_API		C_API
Python_conda_channel		Python_conda_channel
woan_description		woan_description
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

WoanArm API 用户版

目录结构

安装方式

一、C/C++ SDK 安装

支持环境

1. 准备依赖环境

2. 安装 SDK

3. 验证安装

二、Python 安装

支持环境

1. 准备环境

2. 使用本地 conda channel 安装

3. 验证安装

C/C++ API 说明

CMake 集成

C++ 接口

机器人生命周期管理

关节空间运动 movej()

笛卡尔空间直线运动 movel()

笛卡尔空间点到点运动 movep()

纯 C 接口

生命周期管理 (C)

运动控制 (C)

Python API 说明

机器人生命周期管理

关节空间运动 movej()

笛卡尔空间直线运动 movel()

笛卡尔空间点到点运动 movep()

常见问题排查

C/C++

Python

许可证

维护者

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages