MSDK 开发指南 — Alius Docs

概述

Alius RC 的开发体系建立在 DJI MSDK 5.x 和自主研发的 Alius RC SDK 之上。MSDK 5.x 提供与 DJI 硬件平台通信的基础能力（飞控、图传、云台、电池等），而 Alius RC SDK 在 MSDK 基础上封装了遥测数据获取、指令下发、状态同步、物理按键映射等高级功能，帮助开发者用更少的代码实现更完整的操控体验。

本文档面向有 Android 开发经验的工程师，假设读者已熟悉 Java/Kotlin、Android 开发基础以及 Gradle 构建工具。

架构概览

┌────────────────────────────────────────────┐
│              您的 Android 应用                 │
├────────────────────────────────────────────┤
│              Alius RC SDK                   │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ 遥测管理  │ │ 指令控制  │ │ 按键映射    │  │
│  ├──────────┤ ├──────────┤ ├────────────┤  │
│  │ 数据通道  │ │ 连接管理  │ │ UI 组件库   │  │
│  └──────────┘ └──────────┘ └────────────┘  │
├────────────────────────────────────────────┤
│              DJI MSDK 5.x                   │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ Flight   │ │ Camera   │ │ Gimbal      │  │
│  │ Control  │ │ Manager  │ │ Manager     │  │
│  ├──────────┤ ├──────────┤ ├────────────┤  │
│  │ Battery  │ │ RTK      │ │ Perception  │  │
│  └──────────┘ └──────────┘ └────────────┘  │
├────────────────────────────────────────────┤
│          Android HAL / Hardware             │
└────────────────────────────────────────────┘

DJI MSDK 5.x 集成步骤

1. 项目依赖配置

在 app/build.gradle 中添加依赖：

android {
    compileSdkVersion 34
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 34
    }
    packagingOptions {
        exclude 'META-INF/rxjava.properties'
    }
}

dependencies {
    // DJI MSDK 5.x
    implementation 'com.dji:dji-sdk-v5-aircraft:5.10.0'
    implementation 'com.dji:dji-sdk-v5-network:5.10.0'

    // Alius RC SDK
    implementation 'com.alius-tech:alius-rc-sdk:1.2.0'

    // 通用依赖
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'io.reactivex.rxjava3:rxjava:3.1.8'
    implementation 'io.reactivex.rxjava3:rxandroid:3.0.2'
}

2. Application 初始化

创建 Application 类完成 SDK 注册：

public class RcApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initDjiSdk();
    }

    private void initDjiSdk() {
        // 必须首先调用 Helper.install() 加载 so 库
        Helper.install(this);

        SDKManager.getInstance().init(this, new SDKManagerCallback() {
            @Override
            public void onRegister(DJIError error) {
                if (error == DJIError.COMMON_SUCCESS) {
                    // MSDK 注册成功，初始化 Alius RC SDK
                    AliusRCManager.getInstance().init(
                        RcApplication.this,
                        new AliusRCInitCallback() {
                            @Override
                            public void onSuccess() {
                                Log.i("AliusRC", "Alius RC SDK initialized");
                            }
                            @Override
                            public void onFailure(int errorCode, String msg) {
                                Log.e("AliusRC", "Init failed: " + msg);
                            }
                        }
                    );
                }
            }

            @Override
            public void onProductDisconnect(int productId) {
                // 处理断连
            }

            @Override
            public void onProductConnect(int productId) {
                // 处理连接恢复
            }

            @Override
            public void onComponentChange(int productId, 
                BaseComponent component, ComponentChangeType type) {
                // 处理组件变更
            }
        });
    }
}

3. AndroidManifest.xml 配置

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

    <application
        android:name=".RcApplication"
        ...>

        <meta-data
            android:name="com.dji.sdk.API_KEY"
            android:value="${DJI_APP_KEY}" />

    </application>
</manifest>

Alius RC SDK API 概览

核心管理器

Alius RC SDK 以单例管理器模式组织，主要类包括：

管理器	类名	功能
全局管理	`AliusRCManager`	SDK 初始化、版本管理、全局配置
遥测管理	`TelemetryManager`	实时遥测数据订阅和缓存
指令控制	`CommandManager`	运动控制指令下发
连接管理	`ConnectionManager`	多种通信链路的连接状态管理
按键映射	`KeyMappingManager`	物理按键和摇杆的功能映射
数据通道	`DataChannelManager`	自定义数据传输通道

获取遥测数据

// 订阅实时遥测数据
TelemetryManager tm = AliusRCManager.getInstance().getTelemetryManager();

// 订阅电池信息（每秒更新）
tm.subscribeBatteryInfo(batteryInfo -> {
    int percent = batteryInfo.getChargeRemainingInPercent();
    double voltage = batteryInfo.getVoltage();
    double temperature = batteryInfo.getTemperature();
    updateBatteryUI(percent, voltage, temperature);
});

// 订阅飞行/运动状态（200Hz 更新）
tm.subscribeAttitude(attitude -> {
    double roll = attitude.getRoll();     // 横滚角
    double pitch = attitude.getPitch();   // 俯仰角
    double yaw = attitude.getYaw();       // 偏航角
    updateAttitudeDisplay(roll, pitch, yaw);
});

// 订阅 GPS 位置
tm.subscribeGPSSignal(gpsData -> {
    double lat = gpsData.getLatitude();
    double lng = gpsData.getLongitude();
    int satellites = gpsData.getSatelliteCount();
    updateGPSDisplay(lat, lng, satellites);
});

// 订阅速度信息
tm.subscribeVelocity(velocity -> {
    double vx = velocity.getX();  // m/s
    double vy = velocity.getY();
    double vz = velocity.getZ();
    updateSpeedDisplay(vx, vy, vz);
});

下发控制指令

CommandManager cm = AliusRCManager.getInstance().getCommandManager();

// 基础移动控制（使用虚拟摇杆）
// x: 前后 (-1.0 到 1.0)
// y: 左右 (-1.0 到 1.0)
// z: 上下 (-1.0 到 1.0)
// yaw: 旋转 (-1.0 到 1.0)
cm.sendMovementCommand(0.5f, 0.0f, 0.0f, 0.0f, new CommandCallback() {
    @Override
    public void onResult(CommandError error) {
        if (error == null) {
            // 指令执行成功
        } else {
            Log.e("Command", "Error: " + error.getDescription());
        }
    }
});

// 紧急刹车
cm.emergencyBrake();

// 返航（如机器人支持）
cm.startGoHome(new CommandCallback() {
    @Override
    public void onResult(CommandError error) {
        // 处理结果
    }
});

// 设置飞行/运动模式
cm.setFlightMode(FlightMode.POSITION_HOLD, null);

物理按键映射

KeyMappingManager km = AliusRCManager.getInstance().getKeyMappingManager();

// 将 C1 按键映射为"拍照"
km.mapKey(PhysicalKey.C1, KeyAction.SINGLE_CLICK,
    () -> getCameraManager().capturePhoto(null));

// 将 C2 长按映射为"紧急刹车"
km.mapKey(PhysicalKey.C2, KeyAction.LONG_PRESS,
    () -> getCommandManager().emergencyBrake());

// 将波轮映射为云台俯仰控制
km.mapWheel(WheelDirection.CW, degrees -> {
    GimbalManager gm = getGimbalManager();
    gm.rotate(GimbalAxis.PITCH, -degrees * 0.5f, null);
});

km.mapWheel(WheelDirection.CCW, degrees -> {
    GimbalManager gm = getGimbalManager();
    gm.rotate(GimbalAxis.PITCH, degrees * 0.5f, null);
});

// 启用映射
km.enable();

自定义数据通道

Alius RC SDK 提供了独立于视频流的自定义数据传输通道，可用于机器人状态信息的上报和控制参数的下发。

DataChannelManager dcm = AliusRCManager.getInstance().getDataChannelManager();

// 注册自定义数据类型
dcm.registerDataType(1001, "CUSTOM_STATUS", CustomStatus.class);

// 发送数据到机器人端
SensorData data = new SensorData();
data.setTimestamp(System.currentTimeMillis());
data.setTemperature(25.6);
data.setPressure(1013.2);
dcm.sendData(1001, data, new DataCallback() {
    @Override
    public void onSuccess() {
        Log.d("DataChannel", "Data sent successfully");
    }
    @Override
    public void onFailure(int errorCode) {
        Log.e("DataChannel", "Send failed: " + errorCode);
    }
});

// 接收机器人端上报的数据
dcm.subscribeData(1001, customStatus -> {
    CustomStatus status = (CustomStatus) customStatus;
    updateRobotStatusUI(status);
});

UI 组件库

Alius RC SDK 提供了一套预制的 Android UI 组件，可快速搭建遥控器操控界面：

组件	类名	说明
虚拟摇杆	`RCJoystickView`	可自定义样式的双摇杆控件
姿态指示器	`AttitudeIndicatorView`	显示横滚、俯仰、偏航
地图控件	`RCMapView`	集成机器人位置和轨迹的地图
遥测面板	`TelemetryPanelView`	电池、速度、高度等数据面板
云台控制	`GimbalControlView`	云台角度调节滑块
图传画面	`FPVVideoView`	带 OSD 叠加的低延迟视频画面
信号指示	`SignalIndicatorView`	显示信号强度图标

使用示例：

<com.alius.rc.ui.RCJoystickView
    android:id="@+id/leftStick"
    android:layout_width="160dp"
    android:layout_height="160dp"
    app:stickMode="throttle_yaw"
    app:stickColor="#00D4FF"
    app:baseColor="#1A1A2E" />

<com.alius.rc.ui.FPVVideoView
    android:id="@+id/fpvView"
    android:layout_width="match_parent"
    android:layout_height="0dp"
    android:layout_weight="1"
    app:showOSD="true"
    app:osdPosition="top_right" />

多机器人支持

Alius RC SDK 支持一台遥控器同时管理多个机器人连接：

ConnectionManager connMgr = AliusRCManager.getInstance().getConnectionManager();

// 获取所有已连接的机器人
List<RobotInfo> robots = connMgr.getConnectedRobots();

// 切换到指定机器人（默认向其发送控制指令）
connMgr.setActiveRobot("robot_serial_001");

// 监听机器人连接变化
connMgr.addConnectionListener(new ConnectionListener() {
    @Override
    public void onRobotConnected(RobotInfo robotInfo) {
        Log.i("RC", "Robot connected: " + robotInfo.getName());
    }
    @Override
    public void onRobotDisconnected(RobotInfo robotInfo) {
        Log.i("RC", "Robot disconnected: " + robotInfo.getName());
    }
});

代码示例：完整的操控 Activity

以下示例展示了一个最小可运行的操控 Activity：

public class ControlActivity extends AppCompatActivity {

    private FPVVideoView fpvView;
    private RCJoystickView leftStick, rightStick;
    private TelemetryPanelView telemetryPanel;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_control);

        fpvView = findViewById(R.id.fpvView);
        leftStick = findViewById(R.id.leftStick);
        rightStick = findViewById(R.id.rightStick);
        telemetryPanel = findViewById(R.id.telemetryPanel);

        // 绑定摇杆输入到控制指令
        bindSticks();
        // 启动遥测数据订阅
        startTelemetry();
        // 启动图传画面
        fpvView.startVideoFeed();
    }

    private void bindSticks() {
        CommandManager cm = AliusRCManager.getInstance()
            .getCommandManager();

        leftStick.setOnStickListener((x, y) -> {
            // 左摇杆：油门 + 偏航
            cm.setThrottle(y);
            cm.setYaw(x);
        });

        rightStick.setOnStickListener((x, y) -> {
            // 右摇杆：俯仰 + 横滚
            cm.setPitch(y);
            cm.setRoll(x);
        });
    }

    private void startTelemetry() {
        TelemetryManager tm = AliusRCManager.getInstance()
            .getTelemetryManager();

        tm.subscribeBatteryInfo(battery ->
            telemetryPanel.updateBattery(battery));

        tm.subscribeAttitude(attitude ->
            telemetryPanel.updateAttitude(attitude));

        tm.subscribeGPSSignal(gps ->
            telemetryPanel.updateGPS(gps));
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        fpvView.stopVideoFeed();
    }
}

调试与日志

Alius RC SDK 提供分级日志系统：

// 设置日志级别（DEBUG, INFO, WARN, ERROR）
AliusRCManager.getInstance().setLogLevel(LogLevel.DEBUG);

// 添加自定义日志监听器
AliusRCManager.getInstance().addLogListener((level, tag, message) -> {
    if (level == LogLevel.ERROR) {
        // 处理错误日志
        uploadErrorLog(tag, message);
    }
});

// 导出完整日志
String logPath = AliusRCManager.getInstance().exportLogs();

调试时，可通过 ADB 连接遥控器查看实时日志：

adb logcat -s AliusRC:D DJISDK:D

版本兼容性

Alius RC SDK	DJI MSDK	Android API	发布日期
1.2.0	5.10.0	29+	2025 Q2
1.1.0	5.9.0	29+	2025 Q1
1.0.0	5.8.0	29+	2024 Q4

建议始终使用最新版本的 SDK，以获取最新的功能改进和问题修复。

下一步

集成指南 — 将 Alius RC 集成到完整机器人系统
技术规格 — 查看硬件参数
DJI MSDK 5.x 官方文档 — 访问 developer.dji.com