# GBINetSDK.Release **Repository Path**: Jddl/gbinet-sdk.-release ## Basic Information - **Project Name**: GBINetSDK.Release - **Description**: 极客桥系留无人机控制SDK - **Primary Language**: Unknown - **License**: ISC - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2023-10-09 - **Last Updated**: 2025-06-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 极客桥系留无人机控制 SDK ## 目录结构 ```txt sdk readme.md include GBINetSDK.h # SDK 头文件 doc sdk说明文档.md dll x64 GBINetSDK.dll # SDK 动态链接库 GBINetSDK.lib demo # 各语言下的Demo python java cpp ``` ## SDK 说明文档 ## 概述 本文档介绍了 GBI Net SDK（极客桥系留无人机控制 SDK）的使用方法和功能。该 SDK 提供了一组用于与无人机进行通信和控制的函数和回调，支持无人机状态监控、飞行控制、模式切换等功能，适用于 Windows 平台的应用开发。 ## 环境要求 - 操作系统：Windows 7/8/10/11（64 位） - 开发环境：Visual Studio 2015 及以上版本 - 依赖库：无特殊依赖，直接引用动态链接库即可 ## 文件结构 - **GBINetSDK.h**：SDK 头文件，包含函数声明、数据结构定义和错误码枚举 - **GBINetSDK.dll**：SDK 动态链接库，用于应用程序的编译和运行时调用 - **GBINetSDK.lib**：导入库文件，用于 Visual Studio 项目链接 ## 核心功能模块 ### 1. SDK 初始化与反初始化 - 提供 SDK 的初始化和资源释放接口 - 初始化后才能进行后续的无人机操作 ### 2. 无人机状态监控 - 在线无人机信息获取 - 无人机上线 / 下线事件订阅 - 无人机遥测数据实时获取 ### 3. 飞行控制功能 - 基本飞行控制（起飞、降落、返航） - 高度和偏航角调整 - 灯光模式切换 - 手动遥控指令发送 ### 4. 控制模式管理 - 外部控制模式（Offboard）切换 - 外部控制模式下的速度和位置设置 ### 5. 机巢控制 - 机巢开启与关闭操作 ## 错误码说明 | 错误码 | 数值 | 描述 | | ----------------------- | ---- | ------------ | | SDK_ERROR_UNKNOWN | 0 | 未知错误 | | SDK_ERROR_SUCCESS | 1 | 操作成功 | | SDK_ERROR_NOT_INIT | 2 | SDK 未初始化 | | SDK_ERROR_IS_NULL | 3 | 参数为空 | | SDK_ERROR_IS_OFFLINE | 4 | 无人机不在线 | | SDK_ERROR_PARAM_INVALID | 5 | 参数无效 | | SDK_ERROR_PORT_OCCUPIED | 6 | 端口被占用 | | SDK_ERROR_SET_CONFIG | 7 | 设置配置失败 | | SDK_ERROR_GET_CONFIG | 8 | 读取配置失败 | ## 数据结构说明 ### 1. 无人机信息结构（NET_DRONEINFO） ```c typedef struct _tagDroneInfo { char SerialNumber[SDK_COMMON_NAME_LENGTH]; // 机箱序列号（最大64字符） char IpAddress[SDK_COMMON_NAME_LENGTH]; // IP地址（最大64字符） } NET_DRONEINFO, *LPPNET_DRONEINFO; ``` ### 2. 无人机遥测数据结构（NET_DRONE_TELEMETRY） | 字段名 | 类型 | 描述 | | -------------------------- | ------------- | ------------------------------------------------------ | | FlightMode | unsigned char | 飞行模式（0 - 未知，1 - 手动，2 - 自动等） | | GpsNum | unsigned char | GPS 可见卫星数 | | GpsFixType | unsigned char | GPS 定位类型（0 - 无定位，1-2D 定位，2-3D 定位） | | Armed | unsigned char | 是否解锁（1 - 已解锁，0 - 未解锁） | | InAir | unsigned char | 是否在空中（1 - 在空中，0 - 在地面） | | Roll | float | 横滚角（单位：度） | | Pitch | float | 俯仰角（单位：度） | | Yaw | float | 偏航角（单位：度） | | Lat | double | 纬度（十进制格式） | | Lon | double | 经度（十进制格式） | | Alt | float | 相对高度（单位：米） | | GyrometerCalibrationOk | unsigned char | 陀螺仪校准状态（1 - 已校准，0 - 未校准） | | AccelerometerCalibrationOk | unsigned char | 加速度计校准状态（1 - 已校准，0 - 未校准） | | MagnetometerCalibrationOk | unsigned char | 磁场校准状态（1 - 已校准，0 - 未校准） | | LocalPositionOk | unsigned char | 本地位置估计状态（1 - 有效，0 - 无效） | | GlobalPositionOk | unsigned char | 全局位置估计状态（1 - 有效，0 - 无效） | | HomePositionOk | unsigned char | 返航点初始化状态（1 - 已初始化，0 - 未初始化） | | Armable | unsigned char | 是否可以解锁（1 - 可以，0 - 不可以） | | NorthMS | float | 南向飞行速度（单位：米 / 秒，正值表示向南飞行） | | EastMS | float | 东向飞行速度（单位：米 / 秒，正值表示向东飞行） | | DownMS | float | 下降速度（单位：米 / 秒，正值表示向下运动） | | LightMode | unsigned char | 光照模式（0 - 自动，1 - 手动，2 - 关闭等） | | NorthM | float | 南向位置（单位：米，相对于起飞点） | | EastM | float | 东向位置（单位：米，相对于起飞点） | | DownM | float | 下降位置（单位：米，相对于起飞点，正值表示低于起飞点） | | NestStatus | unsigned char | 机巢状态（0 - 关闭，1 - 开启，2 - 故障等） | ## 函数接口详细说明 ### 1. SDK 初始化与资源管理 #### SdkInit - **函数原型**：`NETSDK_API SDKError SdkInit()` - **功能描述**：初始化 SDK 环境，建立与无人机系统的连接准备 - **返回值**：`SDKError`类型错误码，成功返回`SDK_ERROR_SUCCESS` #### SdkUnInit - **函数原型**：`NETSDK_API SDKError SdkUnInit()` - **功能描述**：反初始化 SDK，释放所有资源 - **返回值**：`SDKError`类型错误码，成功返回`SDK_ERROR_SUCCESS` ### 2. 无人机状态获取与事件订阅 #### GetAllOnlineDroneInfo - **函数原型**：`NETSDK_API SDKError GetAllOnlineDroneInfo(NET_DRONEINFO** items, int* length)` - **功能描述**：获取当前所有在线无人机的基本信息 - 参数说明： - `items`：输出参数，指向无人机信息数组的指针 - `length`：输出参数，指向无人机信息数组长度的指针 - **返回值**：`SDKError`类型错误码 - **注意事项**：使用后需调用`ReleaseOnlineDroneInfo`释放内存 #### ReleaseOnlineDroneInfo - **函数原型**：`NETSDK_API SDKError ReleaseOnlineDroneInfo(NET_DRONEINFO* items)` - **功能描述**：释放`GetAllOnlineDroneInfo`获取的无人机信息数组内存 - 参数说明： - `items`：需要释放的无人机信息数组 - **返回值**：`SDKError`类型错误码 #### SubscribeDroneOnline - **函数原型**：`NETSDK_API SDKError SubscribeDroneOnline(OnlineCallback onlineCallback)` - **功能描述**：订阅无人机上线事件 - 参数说明： - `onlineCallback`：上线事件回调函数，原型为`void(__stdcall* OnlineCallback)(NET_DRONEINFO droneInfo)` - **返回值**：`SDKError`类型错误码 #### UnsubscribeDroneOnline - **函数原型**：`NETSDK_API SDKError UnsubscribeDroneOnline()` - **功能描述**：取消订阅无人机上线事件 - **返回值**：`SDKError`类型错误码 #### SubscribeDroneOffline - **函数原型**：`NETSDK_API SDKError SubscribeDroneOffline(OfflineCallback offlineCallback)` - **功能描述**：订阅无人机下线事件 - 参数说明： - `offlineCallback`：下线事件回调函数，原型为`void(__stdcall* OfflineCallback)(NET_DRONEINFO droneInfo)` - **返回值**：`SDKError`类型错误码 #### UnsubscribeDroneOffline - **函数原型**：`NETSDK_API SDKError UnsubscribeDroneOffline()` - **功能描述**：取消订阅无人机下线事件 - **返回值**：`SDKError`类型错误码 #### SubscribeDroneTelemetry - **函数原型**：`NETSDK_API SDKError SubscribeDroneTelemetry(TelemetryCallback telemetryCallback)` - **功能描述**：订阅无人机遥测数据更新事件 - 参数说明： - `telemetryCallback`：遥测数据回调函数，原型为`void(__stdcall* TelemetryCallback)(NET_DRONEINFO droneInfo, NET_DRONE_TELEMETRY telemetryData)` - **返回值**：`SDKError`类型错误码 #### UnsubscribeDroneTelemetry - **函数原型**：`NETSDK_API SDKError UnsubscribeDroneTelemetry()` - **功能描述**：取消订阅无人机遥测数据更新事件 - **返回值**：`SDKError`类型错误码 ### 3. 基本飞行控制 #### ActionArm - **函数原型**：`NETSDK_API SDKError ActionArm(const char* serialNumber)` - **功能描述**：解锁无人机，准备起飞 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 - **注意事项**：无人机必须在地面且处于安全状态才能解锁 #### ActionDisarm - **函数原型**：`NETSDK_API SDKError ActionDisarm(const char* serialNumber)` - **功能描述**：锁定无人机，停止飞行准备 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 - **注意事项**：锁定后无人机将无法执行飞行操作 #### ActionTakeoff - **函数原型**：`NETSDK_API SDKError ActionTakeoff(const char* serialNumber)` - **功能描述**：命令无人机起飞 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 - **注意事项**：无人机必须先解锁才能起飞 #### ActionLand - **函数原型**：`NETSDK_API SDKError ActionLand(const char* serialNumber)` - **功能描述**：命令无人机降落 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 #### ActionReturnToLaunch - **函数原型**：`NETSDK_API SDKError ActionReturnToLaunch(const char* serialNumber)` - **功能描述**：命令无人机返回起飞点 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 #### ActionChangeAltitude - **函数原型**：`NETSDK_API SDKError ActionChangeAltitude(const char* serialNumber, float altitude)` - **功能描述**：修改无人机飞行高度 - 参数说明： - `serialNumber`：无人机序列号 - `altitude`：目标高度（单位：米） - **返回值**：`SDKError`类型错误码 #### ActionChangeYaw - **函数原型**：`NETSDK_API SDKError ActionChangeYaw(const char* serialNumber, float yawDeg)` - **功能描述**：修改无人机偏航角度 - 参数说明： - `serialNumber`：无人机序列号 - `yawDeg`：目标偏航角度（单位：度，0-360） - **返回值**：`SDKError`类型错误码 #### ActionSwitchLight - **函数原型**：`NETSDK_API SDKError ActionSwitchLight(const char* serialNumber, int mode)` - **功能描述**：切换无人机灯光模式 - 参数说明： - `serialNumber`：无人机序列号 - `mode`：灯光模式（具体值参考产品文档） - **返回值**：`SDKError`类型错误码 ### 5. 外部控制模式 #### ActionStartOffboard - **函数原型**：`NETSDK_API SDKError ActionStartOffboard(const char* serialNumber)` - **功能描述**：启动无人机外部控制模式（Offboard） - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 - **注意事项**：外部控制模式需要持续发送控制指令，否则无人机可能进入安全模式 #### ActionStopOffboard - **函数原型**：`NETSDK_API SDKError ActionStopOffboard(const char* serialNumber)` - **功能描述**：停止无人机外部控制模式 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 #### OffboardSetVelocityNed - **函数原型**：`NETSDK_API SDKError OffboardSetVelocityNed(const char* serialNumber, float north_ms, float east_ms, float down_ms, float yaw_deg)` - **功能描述**：在外部控制模式下设置无人机速度（NED 坐标系） - 参数说明： - `serialNumber`：无人机序列号 - `north_ms`：北向速度（单位：米 / 秒，正值向南） - `east_ms`：东向速度（单位：米 / 秒，正值向东） - `down_ms`：下降速度（单位：米 / 秒，正值向下） - `yaw_deg`：偏航角度（单位：度） - **返回值**：`SDKError`类型错误码 #### OffboardSetPositionNed - **函数原型**：`NETSDK_API SDKError OffboardSetPositionNed(const char* serialNumber, float north_m, float east_m, float down_m, float yaw_deg)` - **功能描述**：在外部控制模式下设置无人机位置（NED 坐标系） - 参数说明： - `serialNumber`：无人机序列号 - `north_m`：北向位置（单位：米，相对于原点） - `east_m`：东向位置（单位：米，相对于原点） - `down_m`：下降位置（单位：米，相对于原点，正值向下） - `yaw_deg`：偏航角度（单位：度） - **返回值**：`SDKError`类型错误码 ### 6. 手动遥控与配置 #### SetManualControlInput - **函数原型**：`NETSDK_API SDKError SetManualControlInput(const char* serialNumber, int x, int y, int z, int r, int s, int t)` - **功能描述**：发送手动遥控指令 - 参数说明： - `serialNumber`：无人机序列号 - `x`：X 轴控制输入（通常为左右移动） - `y`：Y 轴控制输入（通常为前后移动） - `z`：Z 轴控制输入（通常为升降） - `r`：R 轴控制输入（通常为偏航） - `s`：S 轴控制输入（备用功能） - `t`：T 轴控制输入（备用功能） - **返回值**：`SDKError`类型错误码 #### SetConfig - **函数原型**：`NETSDK_API SDKError SetConfig(const char* serialNumber, const char* json)` - **功能描述**：设置无人机配置参数 - 参数说明： - `serialNumber`：无人机序列号 - `json`：配置参数的 JSON 字符串 - **返回值**：`SDKError`类型错误码 #### GetConfig - **函数原型**：`NETSDK_API SDKError GetConfig(const char* serialNumber, const char* configName, char* outJson)` - **功能描述**：获取无人机配置参数 - 参数说明： - `serialNumber`：无人机序列号 - `configName`：需要获取的配置名称 - `outJson`：输出参数，存储配置数据的 JSON 字符串 - **返回值**：`SDKError`类型错误码 ### 7. 机巢控制 #### ActionOpenNest - **函数原型**：`NETSDK_API SDKError ActionOpenNest(const char* serialNumber)` - **功能描述**：打开无人机机巢 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 #### ActionCloseNest - **函数原型**：`NETSDK_API SDKError ActionCloseNest(const char* serialNumber)` - **功能描述**：关闭无人机机巢 - 参数说明： - `serialNumber`：无人机序列号 - **返回值**：`SDKError`类型错误码 ## 使用示例（C++） ```cpp #include "GBINetSDK.h" #include #include // 无人机上线回调函数 void __stdcall OnDroneOnline(NET_DRONEINFO droneInfo) { std::cout << "Drone Online: " << droneInfo.SerialNumber << " - " << droneInfo.IpAddress << std::endl; } // 无人机遥测数据回调函数 void __stdcall OnDroneTelemetry(NET_DRONEINFO droneInfo, NET_DRONE_TELEMETRY telemetryData) { std::cout << "Telemetry from " << droneInfo.SerialNumber << ": "; std::cout << "Altitude: " << telemetryData.Alt << "m, Position: (" << telemetryData.Lon << ", " << telemetryData.Lat << ")" << std::endl; } int main() { // 1. 初始化SDK SDKError err = SdkInit(); if (err != SDK_ERROR_SUCCESS) { std::cout << "SDK Init failed, error code: " << err << std::endl; return -1; } // 2. 订阅无人机上线事件和遥测数据 err = SubscribeDroneOnline(OnDroneOnline); err = SubscribeDroneTelemetry(OnDroneTelemetry); // 3. 获取在线无人机 NET_DRONEINFO* drones = nullptr; int count = 0; err = GetAllOnlineDroneInfo(&drones, &count); if (err == SDK_ERROR_SUCCESS && count > 0) { std::cout << "Found " << count << " online drones:" << std::endl; for (int i = 0; i < count; i++) { std::cout << " " << i+1 << ". " << drones[i].SerialNumber << " - " << drones[i].IpAddress << std::endl; // 示例：控制第一架无人机起飞 if (i == 0) { err = ActionTakeoff(drones[i].SerialNumber); if (err == SDK_ERROR_SUCCESS) { std::cout << "Commanded drone to take off" << std::endl; } else { std::cout << "Takeoff failed, error code: " << err << std::endl; } } } } // 4. 释放资源 if (drones) { ReleaseOnlineDroneInfo(drones); } // 5. 反初始化SDK SdkUnInit(); return 0; } ``` ## 注意事项 1. 使用 SDK 前必须先调用`SdkInit`进行初始化，使用完毕后调用`SdkUnInit`释放资源 2. 所有涉及内存分配的函数（如`GetAllOnlineDroneInfo`）必须调用对应的释放函数 3. 无人机控制操作（如起飞、降落）有严格的前提条件，需参考错误码处理异常情况 4. 外部控制模式（Offboard）需要定期发送控制指令，否则可能导致无人机进入安全模式 5. 机巢控制功能仅在无人机处于特定状态时有效，具体请参考产品文档 6. 建议在使用回调函数时考虑线程安全问题，尤其是在多线程环境下 ## 版本说明 当前 SDK 版本：1.0.0 更新日期：2025 年 6 月 20 日 ## 联系方式 如需技术支持或反馈问题，请联系极客桥无人机技术团队