# 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**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 极客桥系留无人机控制 SDK

GBINetSDK 提供无人机发现、状态订阅、遥测获取、飞行控制、外部控制、配置读写和机巢控制等接口。

> 安全提示：起飞、降落、返航、解锁、手动控制、配置写入等接口会直接影响真实设备。示例程序默认只执行初始化、订阅和在线设备查询；需要控制无人机时必须显式传入控制参数，并在安全环境中操作。
>
> Linux 版本说明：`dll/linux` 与 `dll/linux-musl` 当前为实验版本，接口和库文件已随包提供，但尚未作为稳定发布版本承诺；生产环境请优先使用 Windows 版本，并在 Linux 目标设备上完成充分联调验证后再部署。

## 目录结构

```txt
sdk/
  include/
    GBINetSDK.h
  dll/
    windows/
      x64/
        GBINetSDK.dll
        GBINetSDK.lib
      x86/
        GBINetSDK.dll
        GBINetSDK.lib
    linux/
      x64/libGBINetSDK.so
      arm64/libGBINetSDK.so
      arm/libGBINetSDK.so
    linux-musl/
      x64/libGBINetSDK.so
      arm64/libGBINetSDK.so
      arm/libGBINetSDK.so
  demo/
    cpp/
    java/
    python/
    csharp/
  doc/
```

## 环境要求

- Windows：Windows 7/8/10/11，Visual Studio 2015 或更高版本。
- Linux：实验版本。按目标平台选择 `linux` 或 `linux-musl` 下对应架构的 `libGBINetSDK.so`，部署前需在目标设备上验证。
- C/C++：包含 `include/GBINetSDK.h`，Windows 链接对应架构的 `GBINetSDK.lib`，运行时放置同架构 `GBINetSDK.dll`。
- Java：JDK 17，JNA。
- Python：Python 3，使用标准库 `ctypes`。
- C#：.NET 6 或更高版本，使用 P/Invoke。

## 平台库选择

| 平台 | 架构 | 库目录 |
| --- | --- | --- |
| Windows | x64 | `dll/windows/x64` |
| Windows | x86 | `dll/windows/x86` |
| Linux glibc（实验） | x64 | `dll/linux/x64` |
| Linux glibc（实验） | arm64 | `dll/linux/arm64` |
| Linux glibc（实验） | arm | `dll/linux/arm` |
| Linux musl（实验） | x64 | `dll/linux-musl/x64` |
| Linux musl（实验） | arm64 | `dll/linux-musl/arm64` |
| Linux musl（实验） | arm | `dll/linux-musl/arm` |

## 错误码

| 错误码 | 数值 | 描述 |
| --- | ---: | --- |
| `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 | 读取配置失败 |

## 数据结构

### `NET_DRONEINFO`

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `SerialNumber` | `char[64]` | 无人机序列号 |
| `IpAddress` | `char[64]` | 无人机 IP 地址 |

### `NET_DRONE_TELEMETRY`

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `FlightMode` | `unsigned char` | 飞行模式 |
| `GpsNum` | `unsigned char` | 可见 GPS 卫星数 |
| `GpsFixType` | `unsigned char` | GPS 定位类型 |
| `Armed` | `unsigned char` | 是否解锁 |
| `InAir` | `unsigned char` | 是否在空中 |
| `Roll` / `Pitch` / `Yaw` | `float` | 姿态角，单位：度 |
| `Lat` / `Lon` | `double` | 经纬度 |
| `Alt` | `float` | 相对高度，单位：米 |
| `GyrometerCalibrationOk` | `unsigned char` | 陀螺仪是否已校准 |
| `AccelerometerCalibrationOk` | `unsigned char` | 加速度计是否已校准 |
| `MagnetometerCalibrationOk` | `unsigned char` | 磁力计是否已校准 |
| `LocalPositionOk` | `unsigned char` | 本地位置估计是否有效 |
| `GlobalPositionOk` | `unsigned char` | 全局位置估计是否有效 |
| `HomePositionOk` | `unsigned char` | 返航点是否已初始化 |
| `Armable` | `unsigned char` | 是否允许解锁 |
| `NorthMS` / `EastMS` / `DownMS` | `float` | NED 速度，单位：米/秒 |
| `LightMode` | `unsigned char` | 灯光模式 |
| `NorthM` / `EastM` / `DownM` | `float` | NED 位置，单位：米 |
| `NestStatus` | `unsigned char` | 机巢状态 |

## 接口概览

### 初始化

```c
NETSDK_API SDKError SdkInit();
NETSDK_API SDKError SdkUnInit();
```

使用任何 SDK 接口前应先调用 `SdkInit`，程序退出前调用 `SdkUnInit` 释放资源。

### 在线设备与订阅

```c
NETSDK_API SDKError GetAllOnlineDroneInfo(NET_DRONEINFO** items, int* length);
NETSDK_API SDKError ReleaseOnlineDroneInfo(NET_DRONEINFO* items);

typedef void(NETSDK_CALLBACK* OnlineCallback)(NET_DRONEINFO droneInfo);
typedef void(NETSDK_CALLBACK* OfflineCallback)(NET_DRONEINFO droneInfo);
typedef void(NETSDK_CALLBACK* TelemetryCallback)(NET_DRONEINFO droneInfo, NET_DRONE_TELEMETRY telemetryData);

NETSDK_API SDKError SubscribeDroneOnline(OnlineCallback onlineCallback);
NETSDK_API SDKError UnsubscribeDroneOnline();
NETSDK_API SDKError SubscribeDroneOffline(OfflineCallback offlineCallback);
NETSDK_API SDKError UnsubscribeDroneOffline();
NETSDK_API SDKError SubscribeDroneTelemetry(TelemetryCallback telemetryCallback);
NETSDK_API SDKError UnsubscribeDroneTelemetry();
```

`GetAllOnlineDroneInfo` 返回的数组由 SDK 分配，使用后必须调用 `ReleaseOnlineDroneInfo`。

### 飞行与控制

```c
NETSDK_API SDKError ActionArm(const char* serialNumber);
NETSDK_API SDKError ActionDisarm(const char* serialNumber);
NETSDK_API SDKError ActionTakeoff(const char* serialNumber);
NETSDK_API SDKError ActionLand(const char* serialNumber);
NETSDK_API SDKError ActionReturnToLaunch(const char* serialNumber);
NETSDK_API SDKError ActionChangeAltitude(const char* serialNumber, float altitude);
NETSDK_API SDKError ActionChangeYaw(const char* serialNumber, float yawDeg);
NETSDK_API SDKError ActionSwitchLight(const char* serialNumber, int mode);
NETSDK_API SDKError SetManualControlInput(const char* serialNumber, int x, int y, int z, int r, int s, int t);
```

### 外部控制模式

```c
NETSDK_API SDKError ActionStartOffboard(const char* serialNumber);
NETSDK_API SDKError ActionStopOffboard(const char* serialNumber);
NETSDK_API SDKError OffboardSetVelocityNed(const char* serialNumber, float north_ms, float east_ms, float down_ms, float yaw_deg);
NETSDK_API SDKError OffboardSetPositionNed(const char* serialNumber, float north_m, float east_m, float down_m, float yaw_deg);
```

进入 Offboard 后需要按飞控要求持续发送控制指令，否则设备可能进入保护或安全模式。

### 配置读写

```c
NETSDK_API SDKError SetConfig(const char* serialNumber, const char* json);
NETSDK_API SDKError GetConfig(const char* serialNumber, const char* configName, char* outJson);
NETSDK_API SDKError GetConfigLength(const char* serialNumber, const char* configName, int* length);
NETSDK_API SDKError GetConfigWithLength(const char* serialNumber, const char* configName, char* outJson, int outJsonLength);
```

推荐使用 `GetConfigLength` 查询缓冲区长度，再调用 `GetConfigWithLength` 读取配置，避免固定缓冲区过小。

配置写入 JSON 示例：

```json
{"Name":"FlashingFrequency","Value":10}
```

### 机巢控制

```c
NETSDK_API SDKError ActionOpenNest(const char* serialNumber);
NETSDK_API SDKError ActionCloseNest(const char* serialNumber);
```

## Demo

### C++

```powershell
cd demo/cpp/GBINetSDK.Demo
cmake --preset x64-release
cmake --build --preset x64-release
.\out\build\x64-release\GBINetSDK.Demo\GBINetSDK.Demo.exe
```

默认运行只初始化 SDK、订阅事件、等待 3 秒并打印在线无人机。

显式读取某台无人机配置：

```powershell
.\out\build\x64-release\GBINetSDK.Demo\GBINetSDK.Demo.exe --config <serial-number> MaxActuatorDriftProtection
```

显式执行控制动作：

```powershell
.\out\build\x64-release\GBINetSDK.Demo\GBINetSDK.Demo.exe --takeoff <serial-number>
.\out\build\x64-release\GBINetSDK.Demo\GBINetSDK.Demo.exe --land <serial-number>
.\out\build\x64-release\GBINetSDK.Demo\GBINetSDK.Demo.exe --rtl <serial-number>
```

### Java

```powershell
cd demo/java
mvn package
java -jar target/GBINetSDK.Demo-1.0-SNAPSHOT-jar-with-dependencies.jar
```

可通过系统属性指定库路径：

```powershell
java -Dgbi.sdk.library=D:\work\protect\hangyi\src\UAV2024\sdk\dll\windows\x64\GBINetSDK.dll -jar target\GBINetSDK.Demo-1.0-SNAPSHOT-jar-with-dependencies.jar
```

### Python

```powershell
cd demo/python
python gbinetsdk_demo.py
```

可通过环境变量指定库路径：

```powershell
$env:GBI_SDK_LIBRARY="D:\work\protect\hangyi\src\UAV2024\sdk\dll\windows\x64\GBINetSDK.dll"
python gbinetsdk_demo.py
```

### C#

```powershell
cd demo/csharp
dotnet run --project GBINetSDK.Demo.csproj
```

示例会在 Windows x64 下自动从 `dll/windows/x64` 复制运行库到输出目录。

## 使用注意事项

1. 所有控制类接口都应在确认设备在线、位置安全、人员撤离、机体状态允许后调用。
2. 订阅回调由 SDK 线程触发，业务代码中应避免长时间阻塞回调。
3. `NET_DRONEINFO*` 数组必须由 `ReleaseOnlineDroneInfo` 释放。
4. Windows 下回调调用约定为 `__stdcall`；跨语言绑定时需要匹配调用约定。
5. 32 位应用必须加载 `dll/windows/x86`，64 位应用必须加载 `dll/windows/x64`。
6. Linux 库当前为实验版本，建议仅用于适配验证、功能联调和内部测试。

## 版本

- SDK 版本：1.0.1
- 文档更新：2026-06-29