BFY运动控制板API手册

版本: 1.0.5 日期: 2026-06-07

---

1. 概述#

BFYCore 是从 BFYCore 工程核心功能封装的 C++ 动态链接库，提供BFY控制器的完整通信与控制能力。所有导出函数使用 extern "C" 约定，确保 C#、Python 等外部语言可通过 FFI 直接调用。

核心能力#

---

2. 快速开始#

2.1 创建项目#

在 Visual Studio 中创建一个新的 C# 项目，复制"BFYCore.dll"到项目目录。

2.2 C# 调用示例#

using System;
using System.Runtime.InteropServices;

class Program
{
    // ---- 导入 DLL 函数 ----
    [DllImport("BFYCore.dll")] public static extern IntPtr bfy_create();
    [DllImport("BFYCore.dll")] public static extern void bfy_destroy(IntPtr handle);
    [DllImport("BFYCore.dll")] public static extern int bfy_configure(IntPtr handle, int type, string param1, int param2);
    [DllImport("BFYCore.dll")] public static extern int bfy_open(IntPtr handle);
    [DllImport("BFYCore.dll")] public static extern void bfy_close(IntPtr handle, bool user);
    [DllImport("BFYCore.dll")] public static extern bool bfy_is_connected(IntPtr handle);
    [DllImport("BFYCore.dll")] public static extern int bfy_get_status(IntPtr handle);
    [DllImport("BFYCore.dll")] public static extern int bfy_send_command(IntPtr handle, string command);
    [DllImport("BFYCore.dll")] public static extern int bfy_load_file(IntPtr handle, string filename, bool append);
    [DllImport("BFYCore.dll")] public static extern int bfy_run_program(IntPtr handle, bool homing);
    [DllImport("BFYCore.dll")] public static extern void bfy_abort_program(IntPtr handle);
    [DllImport("BFYCore.dll")] public static extern void bfy_pause(IntPtr handle, bool cooling);
    [DllImport("BFYCore.dll")] public static extern void bfy_resume(IntPtr handle);
    [DllImport("BFYCore.dll")] public static extern void bfy_reset(IntPtr handle);
    [DllImport("BFYCore.dll")] public static extern void bfy_set_override_feed(IntPtr handle, int percent);
    [DllImport("BFYCore.dll")] public static extern int bfy_jog(IntPtr handle, int dir, float speed, float step);
    [DllImport("BFYCore.dll")] public static extern void bfy_jog_abort(IntPtr handle);

    // 回调委托
    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
    delegate void OnStatusChanged(int newStatus, IntPtr userData);

    [DllImport("BFYCore.dll")] public static extern void bfy_on_status_changed(
        IntPtr handle, OnStatusChanged callback, IntPtr userData);

    static void Main()
    {
        // 1. 创建实例
        IntPtr core = bfy_create();

        // 2. 注册状态回调
        OnStatusChanged onStatus = (status, _) =>
            Console.WriteLine($"状态变化: {status}");
        bfy_on_status_changed(core, onStatus, IntPtr.Zero);

        // 3. 配置并连接（USB 串口）
        bfy_configure(core, 0, "COM3", 115200);
        if (bfy_open(core) != 0)
        {
            Console.WriteLine("连接失败！");
            bfy_destroy(core);
            return;
        }

        // 4. 发送 G 代码命令
        bfy_send_command(core, "G0 X0 Y0");
        bfy_send_command(core, "G1 X100 Y100 F1000");

        // 5. 加载并执行文件
        bfy_load_file(core, "test.nc", false);
        bfy_run_program(core, homing: false);

        // 6. 暂停/恢复
        bfy_pause(core, false);   // 暂停
        bfy_resume(core); // 恢复

        // 7. 点动控制
        bfy_jog(core, 5, 1000f, 10f); // E 方向，1000mm/min，10mm步长
        bfy_jog_abort(core);           // 中止点动

        // 8. 倍率调整
        bfy_set_override_feed(core, 150); // 150% 进给倍率

        // 9. 断开并销毁
        bfy_close(core, true);
        bfy_destroy(core);
    }
}

2.3 Python 调用示例#

import ctypes
from ctypes import c_int, c_float, c_bool, c_char_p, c_void_p, POINTER

# 加载 DLL
dll = ctypes.CDLL("BFYCore.dll")

# ---- 函数签名声明 ----
dll.bfy_create.restype = c_void_p
dll.bfy_destroy.argtypes = [c_void_p]
dll.bfy_configure.argtypes = [c_void_p, c_int, c_char_p, c_int]
dll.bfy_configure.restype = c_int
dll.bfy_open.argtypes = [c_void_p]
dll.bfy_open.restype = c_int
dll.bfy_close.argtypes = [c_void_p, c_bool]
dll.bfy_is_connected.argtypes = [c_void_p]
dll.bfy_is_connected.restype = c_bool
dll.bfy_get_status.argtypes = [c_void_p]
dll.bfy_get_status.restype = c_int
dll.bfy_send_command.argtypes = [c_void_p, c_char_p]
dll.bfy_send_command.restype = c_int
dll.bfy_load_file.argtypes = [c_void_p, c_char_p, c_bool]
dll.bfy_load_file.restype = c_int
dll.bfy_run_program.argtypes = [c_void_p, c_bool]
dll.bfy_run_program.restype = c_int
dll.bfy_abort_program.argtypes = [c_void_p]
dll.bfy_pause.argtypes = [c_void_p, c_bool]
dll.bfy_resume.argtypes = [c_void_p]
dll.bfy_reset.argtypes = [c_void_p]
dll.bfy_set_override_feed.argtypes = [c_void_p, c_int]
dll.bfy_jog.argtypes = [c_void_p, c_int, c_float, c_float]
dll.bfy_jog.restype = c_int
dll.bfy_jog_abort.argtypes = [c_void_p]

# 状态枚举
STATUS = {
    0: "Disconnected", 1: "Connecting", 2: "Idle", 3: "Run",
    4: "Hold", 5: "Door", 6: "Home", 7: "Alarm",
    8: "Check", 9: "Jog", 10: "Queue", 11: "Cooling",
    12: "AutoHold", 13: "Tool"
}

# ---- 使用示例 ----

# 1. 创建实例
core = dll.bfy_create()

# 2. 配置并连接（USB 串口 COM3, 115200）
ret = dll.bfy_configure(core, 0, b"COM3", 115200)
ret = dll.bfy_open(core)
if ret != 0:
    print("连接失败！")
    dll.bfy_destroy(core)
    exit(1)

print(f"已连接，当前状态: {STATUS.get(dll.bfy_get_status(core), 'Unknown')}")

# 3. 发送 G 代码命令
dll.bfy_send_command(core, b"G0 X0 Y0")
dll.bfy_send_command(core, b"G1 X100 Y100 F1000")

# 4. 加载并执行文件
dll.bfy_load_file(core, b"test.nc", False)
dll.bfy_run_program(core, False)

# 5. 暂停/恢复
dll.bfy_pause(core, False)   # 暂停
dll.bfy_resume(core) # 恢复

# 6. 点动控制
dll.bfy_jog(core, 5, 1000.0, 10.0)  # E 方向
dll.bfy_jog_abort(core)

# 7. 倍率调整
dll.bfy_set_override_feed(core, 150)  # 150%

# 8. 断开并销毁
dll.bfy_close(core, True)
dll.bfy_destroy(core)

---

3. API 参考#

3.1 数据类型#

句柄类型#

枚举#

BfyMacStatus — 机器运行状态

BfyWrapperType — 通信后端类型

BfyJogDirection — 点动方向

BfyStreamingMode — 流传输模式

BfyDetectedIssue — 检测到的问题

结构体#

BfyGPoint — 三维坐标点

typedef struct {
    float x;  // X 轴坐标
    float y;  // Y 轴坐标
    float z;  // Z 轴坐标
} BfyGPoint;

BfyVersionInfo — 固件版本信息

typedef struct {
    char  version_info[256]; // 固件版本信息（完整字符串）
} BfyVersionInfo;

BfyIoPinState — IO端口状态

typedef struct {
    char  type[8];       // 端口类型: "DIN"/"DOUT"/"AIN"/"AOUT"
    char  name[64];      // 端口描述
    int   pin;           // 端口号
    int   value;         // 当前值(数字0/1，或模拟量)
} BfyIoPinState;

BfyConfigParam — 配置参数项

typedef struct {
    int   number;          // 参数编号
    char  value[64];       // 参数值字符串
    char  name[128];       // 参数名称
    char  unit[32];        // 参数单位
    char  description[256]; // 参数描述
} BfyConfigParam;

BfyProgramStats — 程序执行统计

typedef struct {
    int    target;         // 总行数目标
    int    sent;           // 已发送行数
    int    executed;       // 已执行行数
    double total_time_ms;  // 当前作业已用时间(ms)
    double global_time_ms; // 全局总时间(ms)
    double projected_ms;   // 预估剩余时间(ms)
} BfyProgramStats;

BfyFileRange — G代码文件范围信息

typedef struct {
    bool  valid;           // 范围是否有效
    float draw_x_min;      // 绘制范围 X 最小值
    float draw_x_max;      // 绘制范围 X 最大值
    float draw_y_min;      // 绘制范围 Y 最小值
    float draw_y_max;      // 绘制范围 Y 最大值
    float move_x_min;      // 移动范围 X 最小值
    float move_x_max;      // 移动范围 X 最大值
    float move_y_min;      // 移动范围 Y 最小值
    float move_y_max;      // 移动范围 Y 最大值
    double estimated_time_ms; // 预估执行时间(ms)
} BfyFileRange;

回调函数类型#

// 核心回调
typedef void (*BfyOnStatusChanged)(BfyMacStatus new_status, void* user_data);
typedef void (*BfyOnOverrideChanged)(int feed, int rapid, int spindle, void* user_data);
typedef void (*BfyOnIssueDetected)(BfyDetectedIssue issue, void* user_data);
typedef void (*BfyOnLogMessage)(const char* message, void* user_data);
typedef void (*BfyOnFileLoaded)(long elapsed_ms, const char* filename, void* user_data);
typedef void (*BfyOnProgramEnded)(void* user_data);
typedef void (*BfyOnCommandSent)(const char* command, void* user_data);

// NGC 宏程序解析回调
typedef void (*BfyOnNgcOutput)(const char* line, int line_number, void* user_data);
typedef void (*BfyOnNgcAlarm)(int alarm_code, void* user_data);
typedef void (*BfyOnNgcLog)(const char* message, int type, void* user_data);
// type: 0=Info, 1=Warning, 2=Error, 3=Plain

// YMODEM 文件上传回调
typedef void (*BfyOnYmodemProgress)(int progress, void* user_data); // progress: 0-100
typedef void (*BfyOnYmodemResult)(int success, void* user_data);   // success: 1=成功, 0=失败
typedef void (*BfyOnYmodemLog)(const char* message, void* user_data);

---

3.2 函数参考#

核心生命周期#

连接管理#

配置示例：

// USB 串口连接
bfy_configure(handle, BFY_WRAPPER_USB_SERIAL, "COM3", 115200);

// TCP 网络连接
bfy_configure(handle, BFY_WRAPPER_TCP_CLIENT, "192.168.1.152:12121", 0);

状态查询#

实时指令#

命令发送#

命令示例：

bfy_send_command(handle, "G0 X0 Y0");        // 快速移动
bfy_send_command(handle, "G1 X100 F1000");   // 线性插补
bfy_send_command(handle, "M3 S1000");         // 开启激光
bfy_send_command(handle, "$H");               // 回零
bfy_send_command(handle, "$X");               // 解锁

程序执行#

倍率控制#

点动控制#

点动示例：

// X+ 方向，1000mm/min 速度，10mm 步长
bfy_jog(handle, BFY_JOG_E, 1000.0f, 10.0f);

// 中止点动
bfy_jog_abort(handle);

// 多轴绝对位置点动：X=50, Y=30, Z=10，进给 2000mm/min
// axis_mask: bit0=X, bit1=Y, bit2=Z, bit3=A, bit4=B, bit5=C
// 此处 mask=0b000111 = 7，仅 X/Y/Z 轴参与运动
bfy_jog_to(handle, 50.0f, 30.0f, 10.0f, 0, 0, 0, 2000.0f, true, 7);

G代码文件操作#

配置管理#

配置示例：

// 读取 $30 参数
char value[64];
bfy_get_config_value(handle, 30, value, sizeof(value));

// 设置 $32=1 (启用激光模式)
bfy_set_config_value(handle, 32, "1");

自动上报#

线程模式#

回调注册#

工具函数#

---

3.3 NGC 流程控制解析#

NGC 宏程序解析器，支持条件判断、循环、子程序、表达式求值等。

支持的 NGC 语法：

• 条件判断：IF / ELSEIF / ELSE / ENDIF
• 循环结构：WHILE / ENDWHILE, DO / WHILE, REPEAT / ENDREPEAT
• 循环控制：BREAK, CONTINUE
• 子程序：SUB / ENDSUB / CALL / RETURN
• 异常触发：RAISE ALARM / RAISE ERROR
• 表达式求值和参数引用（#1, #<_param>）

---

3.4 IO 控制#

---

3.5 YMODEM 文件上传#

通过 YMODEM 协议上传文件到 W25Q128 存储芯片。使用独立串口连接，调用前需确保主连接已断开（串口未被占用）。此函数为阻塞调用，建议在后台线程执行。

---

4. 典型工作流程#

4.1 基本连接与控制#

创建实例 → 配置通信 → 打开连接 → 发送命令 → 关闭连接 → 销毁实例

4.2 文件执行流程#

创建实例 → 配置通信 → 打开连接
  → 加载G代码文件 → 获取范围/时间预估
  → 执行程序 → (暂停/恢复/倍率调整)
  → 程序结束 → 关闭连接 → 销毁实例

4.3 手动点动流程#

连接后 → 设置点动参数 → 按方向点动 → 释放/中止点动

---

5. 注意事项#

1. 线程安全：所有 API 函数内部使用互斥锁保护，可从多线程调用
2. 回调线程：回调函数在内部工作线程中触发，回调内不应执行耗时操作
3. 字符串生命周期：bfy_get_last_error 返回的指针在下次调用前失效
4. 多实例：支持创建多个 BfyCore 实例，每个实例独立管理连接
5. 资源释放：使用完毕后必须调用 bfy_destroy 释放资源
6. 串口独占：同一串口同时只能被一个实例打开
7. 协议兼容：部分功能（如 Jog）的行为取决于 BFY控制器固件版本

---

6. 错误处理#

大多数函数返回 0 表示成功，-1 表示失败。失败时可通过 bfy_get_last_error 获取详细错误信息。

int ret = bfy_open(handle);
if (ret != 0) {
    const char* err = bfy_get_last_error(handle);
    printf("连接失败: %s\n", err);
}

---

8. 版本更新记录#