选型指南
Y1
- 入门指南
- 二次开发
  - API(Python)
  - API(C++)
  - API(ROS2)
  - API(HTTP)
- 整机技术参数
- 操作说明
- 维护管理
- 售后保障
Y2
- 产品概述
- 入门指南
- 整机技术参数
- 二次开发
  - API(Python)
  - API(C++)
  - API(ROS2)
  - API(HTTP)
- 操作说明
- 维护管理
- 售后保障
Y3
- 产品概述
- 入门指南
- 二次开发
- 整机技术参数
- 操作说明
- 维护管理
- 售后保障
Y4
- 产品概述
- 入门指南
- 二次开发
  - API(C++)
  - API(Python)
- 整机技术参数
- 售后保障
遥操作
相关下载

升降机构

1.lift_up - 升降上升

方法： ctrl.lift_up(spd)

C++ 签名： bool lift_up(float spd);

参数：

spd：速度值，float 类型，单位：mm/s，正速度表示上升

返回值：

bool：操作结果
- true：指令发送成功
- false：指令发送失败

使用示例：

C++

#include "fd_api/control.h"
#include <cstdio>

int main() {
    fd_robot::Control ctrl;
    fd_robot::Control::Options opts;
    opts.node_name = "fd_api_control";
    if (!ctrl.Init(opts)) {
        return 1;
    }

    // 以速度 0.5 上升（单位 mm/s）
    bool ok = ctrl.lift_up(0.5f);
    if (ok) {
        printf("上升指令发送成功\n");
    } else {
        printf("上升指令发送失败\n");
    }
    return 0;
}

注意： 速度模式下，升降驱动在约 1s 内未再收到速度命令会自行停止；上位机须 周期性调用（建议间隔 小于 500ms），单次调用不足以维持连续升降。

2.lift_down - 升降下降

方法： ctrl.lift_down(spd)

C++ 签名： bool lift_down(float spd);

参数：

spd：速度值，float 类型，单位：mm/s，负速度表示下降

返回值：

bool：操作结果
- true：指令发送成功
- false：指令发送失败

使用示例：

C++

#include "fd_api/control.h"
#include <cstdio>

int main() {
    fd_robot::Control ctrl;
    fd_robot::Control::Options opts;
    opts.node_name = "fd_api_control";
    if (!ctrl.Init(opts)) {
        return 1;
    }

    // 以速度 0.3 下降（单位 mm/s）
    bool ok = ctrl.lift_down(-0.3f);
    if (ok) {
        printf("下降指令发送成功\n");
    } else {
        printf("下降指令发送失败\n");
    }
    return 0;
}

注意： 与 lift_up 相同，速度模式下需周期性调用以维持连续下降。

3.lift_set_pos - 升降位置控制

方法： ctrl.lift_set_pos(spd, pos_mm)

C++ 签名： bool lift_set_pos(float spd, float pos_mm);

参数：

spd：速度值，float 类型，单位：mm/s
pos_mm：目标位置，float 类型，单位：毫米 (mm)，为相对于原点的位置

返回值：

bool：操作结果
- true：指令发送成功
- false：指令发送失败

使用示例：

C++

#include "fd_api/control.h"
#include <cstdio>

int main() {
    fd_robot::Control ctrl;
    fd_robot::Control::Options opts;
    opts.node_name = "fd_api_control";
    if (!ctrl.Init(opts)) {
        return 1;
    }

    // 以速度 0.2 移动到 100mm 位置
    bool ok = ctrl.lift_set_pos(0.2f, 100.0f);
    if (ok) {
        printf("位置控制指令发送成功\n");
    } else {
        printf("位置控制指令发送失败\n");
    }
    return 0;
}

注意： 位置控制基于原点（可调用 lift_set_orig 设置）的相对位置，指定位置后电机在无中途打断的情况下移动到目标位置即停止。

4.lift_stop - 升降停止

方法： ctrl.lift_stop()

C++ 签名： bool lift_stop();

参数：

返回值：

bool：操作结果
- true：指令发送成功
- false：指令发送失败

使用示例：

C++

#include "fd_api/control.h"
#include <cstdio>

int main() {
    fd_robot::Control ctrl;
    fd_robot::Control::Options opts;
    opts.node_name = "fd_api_control";
    if (!ctrl.Init(opts)) {
        return 1;
    }

    // 停止升降运动
    ctrl.lift_stop();
    printf("升降已停止\n");
    return 0;
}

5.lift_set_orig - 升降设置原点

方法： ctrl.lift_set_orig(save_flash = false)

C++ 签名： bool lift_set_orig(bool save_flash = false);

说明： 将当前位置设置为原点（0 mm）。位置控制（lift_set_pos）基于该原点计算相对位置。

参数：

save_flash：是否保存到 Flash，bool 类型，默认 false。设为 true 时原点信息写入 Flash，断电重启后仍生效

返回值：

bool：操作结果
- true：指令发送成功
- false：指令发送失败

使用示例：

C++

#include "fd_api/control.h"
#include <cstdio>

int main() {
    fd_robot::Control ctrl;
    fd_robot::Control::Options opts;
    opts.node_name = "fd_api_control";
    if (!ctrl.Init(opts)) {
        return 1;
    }

    // 将当前位置设置为原点（0mm）
    bool ok = ctrl.lift_set_orig();
    if (ok) {
        printf("原点设置成功\n");
    } else {
        printf("原点设置失败\n");
    }

    // 设置原点并保存到 Flash，断电重启后仍生效
    ctrl.lift_set_orig(true);
    return 0;
}

注意： 设置原点后，后续 lift_set_pos 位置控制将基于新原点计算相对位置，请确保在合适的位置设置原点。

6.lift_status_cmd - 升降状态命令

方法： ctrl.lift_status_cmd(cmd)

C++ 签名： bool lift_status_cmd(const std::string &cmd);

说明： 向升降驱动发送状态字符串命令，如清除编码器故障等。具体支持的字符串命令请参见升降驱动文档。

参数：

cmd：状态命令字符串，std::string 类型。常用值："encoder_exception_clear"（清除编码器故障）

返回值：

bool：操作结果
- true：指令发送成功
- false：指令发送失败

使用示例：

C++

#include "fd_api/control.h"
#include <cstdio>

int main() {
    fd_robot::Control ctrl;
    fd_robot::Control::Options opts;
    opts.node_name = "fd_api_control";
    if (!ctrl.Init(opts)) {
        return 1;
    }

    // 清除编码器故障
    bool ok = ctrl.lift_status_cmd("encoder_exception_clear");
    if (ok) {
        printf("状态命令发送成功\n");
    } else {
        printf("状态命令发送失败\n");
    }
    return 0;
}

注意： 本接口仅 C++ 提供，Python Control 暂未封装。清除故障前请先停止升降运动（lift_stop）。

7.lift_get_current_pos - 获取升降当前位置（同步读取）

方法： state.lift_get_current_pos(pos_mm)

C++ 签名： bool lift_get_current_pos(float &pos_mm) const;

参数：

pos_mm：出参，float & 类型，返回当前升降位置高度，单位：毫米 (mm)

返回值：

bool：表示是否已有有效缓存数据
- true：已有数据，pos_mm 有效
- false：尚未收到数据，pos_mm 不可信

使用示例：

C++

#include "fd_api/state.h"
#include <cstdio>

int main() {
    fd_robot::State state;
    if (!state.Init()) {
        return 1;
    }

    // 读取当前升降高度
    float pos_mm = 0.0f;
    if (state.lift_get_current_pos(pos_mm)) {
        printf("当前升降高度：%.2f mm\n", pos_mm);
    } else {
        printf("尚未收到升降位置数据\n");
    }
    return 0;
}

注意： 返回 false 表示尚未收到状态数据，此时 pos_mm 出参不可信，建议先订阅或等待数据到达后再读取。

8.lift_sub_current_pos - 订阅升降位置（异步回调）

方法： state.lift_sub_current_pos(cb)

C++ 签名： SubscriptionId lift_sub_current_pos(LiftPosCallback cb); // cb: void(float pos_mm)

参数：

cb：回调函数，std::function<void(float)> 类型，pos_mm 为 float，单位：毫米 (mm)。回调在线程池中执行。

返回值：

SubscriptionId：订阅ID，类型为 uint64_t。可用于后续取消订阅；空回调返回 0（失败）

使用示例：

C++

#include "fd_api/state.h"
#include <cstdio>

int main() {
    fd_robot::State state;
    if (!state.Init()) {
        return 1;
    }

    // 订阅升降位置（回调在线程池中执行）
    fd_robot::SubscriptionId sid = state.lift_sub_current_pos(
        [](float pos_mm) {
            printf("升降位置更新：%.2f mm\n", pos_mm);
        });
    if (sid != 0) {
        printf("订阅成功，订阅ID：%llu\n", sid);
    }

    // 无需接收时取消订阅
    state.unsubscribe(sid);
    printf("已取消升降位置订阅\n");
    return 0;
}