简介面向Android开发者和无人机爱好者的官方大疆Mobile SDK示例DEMO旨在帮助零基础上手大疆无人机App开发。整个压缩包共829个文件大小约10.96MB文件类型涵盖550个HTML说明文档、80个Java源码、61个XML配置文件以及PNG图片、Gradle构建脚本、字体资源等既方便查阅API接口也能对照源码理解Android权限管理、蓝牙/WiFi通信、多线程异步、JNI/NDK集成、实时视频流处理等关键技术点。内容覆盖初始化SDK、连接无人机、接收状态、拍摄照片和录制视频等功能模块。目前已有228人学习适合希望快速搭建大疆SDK项目骨架、熟悉初始化与飞行控制流程的开发者。通过这份DEMO读者可以掌握Android Studio集成方式、无人机状态获取、飞行指令下发、拍照录像等完整调用链还能借鉴官方示例的UI设计、错误处理与日志记录写法并结合测试调试方法为后续二次开发与功能扩展打下扎实基础。1. 从Mobile-SDK-Android-DEMO看大疆Android开发的起点一个大疆Mobile-SDK-Android-master_DEMO_android_项目解压后能看到gradlew.bat和一堆doc-vendor.css、fontawesome.css之类的文档资源说明这套SDK示例把构建脚本和API说明都打包在一起了。对于想碰无人机控制的Android工程师这个DEMO的价值在于它不是玩具代码而是完整演示了从SDK注册、设备连接、状态回调到飞行控制的调用链。适合两类人一是刚接触大疆SDK、想在Android Studio里跑通第一个航点任务的开发者二是做二次集成的老手需要对照官方示例确认某个版本的API签名和回调时序。简单说看明白这个DEMO就等于拿到了大疆Android开发的通用钥匙后面切到其他机型SDK也只是参数层面的差别。2. Android Studio集成与Gradle依赖解析把SDK跑起来2.1 工程结构与构建脚本的识别拿到的项目根目录里有gradlew.bat说明这是一个标准的Gradle工程Windows下可以直接用命令行构建。常见做法是先用Android Studio打开项目根目录让它自己解析Gradle插件版本和依赖仓库。注意这个DEMO的目录里还有大量CSS文件例如doc-vendor.css、doc-app.css、search_panel.css这些是SDK文档站点的静态资源不是App运行资源编译时Gradle不会把它们打进APK但如果你用Android Studio打开整个目录可能会让IDE索引变慢我一般会在Project视图里把docs相关的文件夹标记为Excluded。开始之前还要确认一件事你手里的SDK版本对应的大疆机型范围。不同版本对Android系统版本和ARM架构有不同要求比如较新的SDK要求Android 5.0以上并且只支持arm64-v8a和armeabi-v7a。如果项目里没有配置ndk.abiFilters打包时可能把所有ABI都带进去APK体积会变大某些机型反而出现so库加载失败的问题。2.2 在AndroidManifest中声明权限与硬件特性大疆SDK依赖的权限比普通应用多至少需要网络、WiFi、蓝牙、定位、摄像头和外部存储。以Android 8.0及以上系统为例动态权限还要在代码里逐个申请。下面是一份在DEMO里常见的权限声明uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / uses-permission android:nameandroid.permission.CHANGE_WIFI_STATE / uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / uses-permission android:nameandroid.permission.BLUETOOTH / uses-permission android:nameandroid.permission.CAMERA / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE /这里解释一下每个权限的用途INTERNET用于和无人机之间的TCP/UDP通信大疆SDK的控制指令和视频流都走网络传输ACCESS_FINE_LOCATION在Android 6.0以上是WiFi扫描的必需权限否则你搜不到无人机热点BLUETOOTH用于连接遥控器或部分机型的辅助通信CAMERA给FPV镜头预览使用。注意从Android 6.0开始WRITE_EXTERNAL_STORAGE需要运行时申请单纯在Manifest里写上是不够的。2.3 Gradle依赖与Java 8兼容配置在build.gradle里大疆SDK的依赖通常写成这样dependencies { implementation com.dji:dji-sdk:4.16.1 implementation com.dji:dji-sdk-provided:4.16.1 compileOnly com.dji:dji-sdk-provided:4.16.1 }这个写法有个关键点dji-sdk-provided用compileOnly引入而dji-sdk用implementation。原因是SDK里部分系统API在Android系统里已经存在provided只参与编译不打包能避免类冲突。如果你在DEMO里看到的是compile那多半是老版本Gradle的写法需要同步改成implementation否则在Android Studio 4.0以上会直接报错。同时要在compileOptions里开启Java 8支持因为SDK内部用了Lambda表达式和java.time相关APIcompileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 }不开启的话编译时会报default methods或lambda相关的DexError这个报错在社区里出现频率很高。2.4 注册SDK与初始化时机在MainActivity的onCreate里需要先调用SDK注册再判断注册结果。大疆官方推荐的写法是在Application里做注册因为Activity的生命周期可能被系统回收导致重复注册。下面是一段在DEMO里常见的初始化代码public class DJIApplication extends Application { Override public void onCreate() { super.onCreate(); SDKManager.getInstance().init( this, new SDKManagerCallback() { Override public void onRegister(DJIError error) { if (error DJIError.NO_ERROR) { Log.d(SDK, register success); } else { Log.e(SDK, register failed: error.getDescription()); } } } ); } }这段代码的核心是SDKManager.getInstance().init第一个参数是Application上下文第二个参数是回调。onRegister里判断DJIError是否为NO_ERROR注册失败时错误描述会明确告诉你原因比如App Key未配置、网络不通或SDK版本不匹配。接着在MainActivity的onCreate里检查SDKManager.getInstance().isRegistered()只有返回true才允许进入无人机连接流程。2.5 常见集成报错排查我整理了一张排查表覆盖Android Studio集成阶段最常踩的坑报错或现象可能原因处理方式DexArchiveBuilderExceptionJava 8兼容未开启在compileOptions里配置Java 8ClassNotFoundException: com.dji.sdk.SDKManagerdji-sdk-provided被编译进APK确认依赖写法改成compileOnly注册返回INVALID_APP_KEYAndroidManifest里没配大疆App Key在application标签中加meta-data运行崩溃找不到libSDK.soSDK原生库未打包确认ndk.abiFilters包含arm64-v8a如果注册回调完全没有执行优先检查网络。大疆SDK首次注册需要访问大疆服务器校验App Key测试环境防火墙会直接断掉这个请求。另外注意模拟器上跑SDK会大概率失败因为大疆SDK检测到非真机环境会拒绝连接底层硬件服务。3. 初始化SDK与连接无人机的状态机回调顺序决定成败3.1 从Application到Activity的初始化链路DEMO里有一个很关键的顺序先Application里注册SDK再在Activity里启动连接。很多人直接把注册写在MainActivity里结果Activity重建后回调丢失无人机连接时好时坏。正确的链路是Application.onCreate完成SDKManager.init等onRegister回调返回成功再在MainActivity的onStart里执行startConnection。Override protected void onStart() { super.onStart(); if (SDKManager.getInstance().isRegistered()) { BaseProduct product SDKManager.getInstance().getProduct(); if (product null) { SDKManager.getInstance().startConnection(); } } }这里getProduct()返回当前连接的产品对象如果为null说明还没连上需要startConnection()。注意startConnection是异步的结果通过ProductConnectivityListener回调而不是立即返回。所以不要在调用后立刻读取型号和序列号否则拿到的是空对象。3.2 连接状态回调的注册时机DEMO中通常会在onCreate里注册ProductConnectivityListener但有一个细节注册动作要在registerCallback方法完成之后否则系统把SDK内部状态还没准备好的回调排队导致第一次连接事件丢失。大疆SDK提供了SDKManager.getInstance().addProductConnectivityListener(listener)一般在onResume中注册onPause中注销避免界面不可见时还处理飞行控制。Override protected void onResume() { super.onResume(); SDKManager.getInstance().addProductConnectivityListener(this); } Override protected void onPause() { SDKManager.getInstance().removeProductConnectivityListener(this); super.onPause(); }然后实现onProductConnectivityChanged方法Override public void onProductConnectivityChanged(Product product, boolean isConnected) { if (isConnected) { String model product.getModel().getDisplayName(); String serial product.getSerialNumber(); Log.d(CONNECT, connected: model sn serial); } else { Log.w(CONNECT, disconnected); } }回调里isConnected为true不代表可以立即发指令还需要等待FlightController的非空回调。大疆SDK的组件获取是异步的通常有三种方式getFlightController()直接获取、FlightControllerState.Callback监听状态、以及ComponentAvailabilityCallback处理组件失效。DEMO里最常见的写法是每次使用前判空FlightController flightController product.getFlightController(); if (flightController ! null) { flightController.getState().setStateCallback(state - { double altitude state.getAircraftLocation().getAltitude(); boolean isFlying state.isFlying(); Log.d(STATE, altitude altitude flying isFlying); }); }3.3 状态回调顺序与UI刷新策略这里有个容易忽视的顺序问题onProductConnectivityChanged先触发FlightControllerState.Callback后触发。因此你在产品连接回调里立刻去读取高度、电量大概率是旧数据。正确做法是连接回调里只记录isConnected状态然后等FlightControllerState回调把数据刷进ViewModel或UI字段。事件回调方法触发时机UI建议无人机连接onProductConnectivityChanged热连接或断开瞬间更新设备状态图标电池电量BatteryState.Callback电量变化周期上报刷新百分比文本飞行状态FlightControllerState.Callback姿态/位置/飞行模式变化更新地图与速度表GPS信号FlightControllerState.getSatelliteCount()卫星数变化显示信号强度另外FlightControllerState.Callback是回调在SDK的专用线程不能直接操作UI。DEMO里会写一个Handler(Looper.getMainLooper())转发或者用EventBus。我一般用runOnUiThread但频繁刷新的数据用runOnUiThread会有性能问题建议在回调里把数据放进ValueAnimator或LiveData做节流。3.4 状态机断连恢复的幂等处理无人机的WiFi信号不稳定连接断开会比手机App更频繁。如果你在onProductConnectivityChanged(false)里做清理工作比如清空地图标注那么重连成功后要确保这些数据能被重新拉取。一个常见坑是断连清理时把FlightController对象置空了重连后忘记重新获取导致后续getFlightController()返回null。我在DEMO基础上一般会增加一个recovery标记private boolean recovering false; Override public void onProductConnectivityChanged(Product product, boolean isConnected) { if (isConnected recovering) { recovering false; requestFlightState(); } else if (!isConnected) { recovering true; clearUIState(); } }这样断连后只需要恢复关键状态而不是把整个页面重新初始化。注意在requestFlightState()里要再次调用setStateCallback因为SDK在断连后可能清掉了旧回调。4. 飞行控制指令封装与相机动作别让UI线程背锅4.1 FlightController指令的异步调用方式飞行控制不是直接调takeOff()然后等返回而是通过CommonCallbacks.CompletionCallback异步回调结果。DEMO里的起飞按钮对应的代码大致如下flightController.startTakeoff(new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { if (error null) { Log.d(FLIGHT, takeoff success); } else { Log.e(FLIGHT, takeoff failed: error.getDescription()); } } });注意startTakeoff必须在地面状态下调用如果当前已经在空中回调会返回DJIError并给出描述。另外整个调用过程必须确保飞行控制器为非空且当前没有其他指令在执行。大疆SDK对并行的飞控指令是有限制的一个指令没结束前发新指令可能会被直接拒绝。4.2 编队飞行与速度控制的参数细节除了起飞降落DEMO里展示的更多是速度控制指令。FlightController.setVelocity需要传入VelocityX、VelocityY、VelocityZ和YawRate四个参数单位分别是米/秒和度/秒。注意坐标系是机体坐标系还是地面坐标系默认是地面坐标系。FlightControllerState.Velocity velocity new FlightControllerState.Velocity(2.0f, 0.0f, 0.0f, 30.0f); flightController.setVelocity(velocity, new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { if (error ! null) { Log.e(FLIGHT, velocity fail: error.getDescription()); } } });这里Velocity的构造函数四个参数通常对应x、y、z方向的速度和偏航角速度但不同机型SDK版本对速度上限有不同限制比如Mini系列最高平飞速度只有8m/s你传一个15m/s进去SDK会回调参数错误。所以我在封装指令前会先读取产品参数表用AircraftParameters里的最大值做clamp。4.3 相机拍照与录像的线程模型相机操作和飞控操作一样都是异步任务。拍照用Camera.startShootPhoto()录像用Camera.startRecordVideo()停止录像是Camera.stopRecordVideo()。这些方法调用后立即返回结果在回调里收到。千万不能在UI线程等结果因为大疆相机模块在底层做JPEG编码时可能耗时几百毫秒卡住主线程会导致ANR。public void shootPhoto(Camera camera) { camera.startShootPhoto(new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { if (error null) { MediaManager mediaManager camera.getMediaManager(); if (mediaManager ! null) { mediaManager.addMediaUpdatedVideoPlaybackStateListener(state - { // 处理新生成的媒体文件 }); } } } }); }这里还有一个细节拍照完成后新照片会触发MediaManager.VideoPlaybackState更新你可以在这个回调里获取最新的媒体文件列表用于相册刷新。如果只是拍照而不关心文件可以不注册这个监听器。4.4 任务调度避免指令风暴当App需要连续执行多个动作比如“起飞-前进-拍照-返航”如果在每个回调里嵌套调用下一个指令代码会产生回调地狱。DEMO里通常只用简单嵌套但生产环境我建议用一个指令队列private final QueueFlightCommand commandQueue new ConcurrentLinkedQueue(); public void enqueue(FlightCommand cmd) { commandQueue.offer(cmd); if (!isExecuting) { executeNext(); } } private void executeNext() { FlightCommand cmd commandQueue.poll(); if (cmd null) { isExecuting false; return; } isExecuting true; cmd.execute(new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { isExecuting false; executeNext(); } }); }队列的好处是可以控制指令间隔。CompletionCallback返回后立刻执行下一条中间没有延时。如果需要每个指令之间保持1秒间隔可以在executeNext()里加一个Handler.postDelayed。注意队列要用ConcurrentLinkedQueue因为飞行控制的回调线程和工作线程可能同时访问队列。指令回调线程超时表现常见错误startTakeoffSDK回调线程约10秒无响应未解锁或地面不平setVelocitySDK回调线程无固定超时超过最大飞行速度startShootPhotoSDK回调线程约3秒无响应相机正在录像startRecordVideoSDK回调线程约3秒无响应存储卡已满这张表不是官方超时定义而是我实践里观察到的经验值。实际调试时如果发现指令在某个机型上总是超时最好先检查该机型的AircraftParameters确认动作是否被当前飞行模式禁止。4.5 主线程与SDK线程的日志标记调试时我习惯在关键回调上打线程日志这是区分SDK线程和UI线程最直接的手段private String threadName() { return Thread.currentThread().getName(); }然后在回调里打Log.d(THREAD, thread threadName())。大疆SDK的回调线程名通常以DJI或MessageThread开头UI线程是main。如果发现某个回调在main线程执行并且你在里面做了网络请求或文件写入就需要注意卡顿风险。DEMO里很多示例代码没有显式做线程切换实际项目里还是要用Handler转发到主线程。5. 从DEMO到可交付App权限、日志与真机验证的几个细节5.1 运行时权限与Android 12适配DEMO里的权限写在AndroidManifest.xml但Android 6.0以上需要运行时申请。我整理了一个最小权限请求顺序先定位后WiFi再蓝牙。因为大疆SDK在启动连接前会扫描WiFiAndroid系统要求扫描WiFi前必须拿到精确定位权限。String[] permissions { Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.CAMERA, Manifest.permission.WRITE_EXTERNAL_STORAGE }; if (Build.VERSION.SDK_INT Build.VERSION_CODES.M) { requestPermissions(permissions, 100); }对于Android 12及以上还需要处理蓝牙扫描权限BLUETOOTH_SCAN和连接权限BLUETOOTH_CONNECT否则连接遥控器时会报错。这个在DEMO里没有体现属于自己补的内容。权限请求回调后建议检查onRequestPermissionsResult里所有granted状态都为true再启动SDK连接流程否则直接给用户弹提示。5.2 真机验证顺序与Logcat过滤不要一上来就飞先在手机开发者模式里开启USB调试用USB线连着Android Studio跑DEMO。连接无人机前先看Logcat里有没有SDK注册成功日志过滤关键字SDKManager或DJIError。一个可复用的验证顺序是确认注册成功连接遥控器或飞行器热点检查产品连接回调查看FlightController状态回调最后再点击起飞。常用Logcat命令adb logcat -s DJISDK:D adb logcat -s CONNECT:V STATE:V adb logcat *:E -v time第一条只看SDK级别日志第二条看连接和状态回调第三条按时间过滤所有错误。如果怀疑SDK底层崩溃还需要抓取native日志adb logcat -b crash。这几个命令组合足够覆盖大多数连接问题。5.3 ProGuard混淆规则与包体积控制如果正式打包要开启代码混淆必须为大疆SDK添加keep规则否则运行时会出现类被裁剪的问题。在proguard-rules.pro里至少保留这些-keep class com.dji.** { *; } -dontwarn com.dji.** -keep class dji.** { *; } -keepclassmembers class dji.** { *; }原因是大疆SDK大量使用反射、JNI和动态代理混淆后这些调用点会失联。另外如果你把DEMO的模块直接拷进生产项目注意去掉它自带的android:debuggabletrue和多余的日志输出否则上架审核会提示风险。5.4 模块化拆分建议最后说一个提升点不要把DEMO的Activity直接当生产代码用。DEMO把所有状态都堆在Activity里而实际项目应该把SDK连接、飞控指令、相机管理拆成三个单例或Repository模块用LiveData或回调向上层暴露状态。这样在飞行过程中Activity重建时底层连接不会断。我在做过的一个巡检App里就是这样拆的效果是断线重连恢复时间从四五秒缩短到一秒以内因为不用等Activity重建完成。同时建议把SDKManager.getInstance()的调用封装成一个DroneService内部维护连接状态和组件缓存。DEMO里那种到处直接调用SDKManager的写法只适合演示在工程化项目里会造成大量重复判空和错误处理。把这些细节补上才算真正把DEMO的价值吃透。本文还有配套的精品资源点击获取
大疆Mobile SDK Android开发从入门到实践：集成、连接与飞行控制详解
简介面向Android开发者和无人机爱好者的官方大疆Mobile SDK示例DEMO旨在帮助零基础上手大疆无人机App开发。整个压缩包共829个文件大小约10.96MB文件类型涵盖550个HTML说明文档、80个Java源码、61个XML配置文件以及PNG图片、Gradle构建脚本、字体资源等既方便查阅API接口也能对照源码理解Android权限管理、蓝牙/WiFi通信、多线程异步、JNI/NDK集成、实时视频流处理等关键技术点。内容覆盖初始化SDK、连接无人机、接收状态、拍摄照片和录制视频等功能模块。目前已有228人学习适合希望快速搭建大疆SDK项目骨架、熟悉初始化与飞行控制流程的开发者。通过这份DEMO读者可以掌握Android Studio集成方式、无人机状态获取、飞行指令下发、拍照录像等完整调用链还能借鉴官方示例的UI设计、错误处理与日志记录写法并结合测试调试方法为后续二次开发与功能扩展打下扎实基础。1. 从Mobile-SDK-Android-DEMO看大疆Android开发的起点一个大疆Mobile-SDK-Android-master_DEMO_android_项目解压后能看到gradlew.bat和一堆doc-vendor.css、fontawesome.css之类的文档资源说明这套SDK示例把构建脚本和API说明都打包在一起了。对于想碰无人机控制的Android工程师这个DEMO的价值在于它不是玩具代码而是完整演示了从SDK注册、设备连接、状态回调到飞行控制的调用链。适合两类人一是刚接触大疆SDK、想在Android Studio里跑通第一个航点任务的开发者二是做二次集成的老手需要对照官方示例确认某个版本的API签名和回调时序。简单说看明白这个DEMO就等于拿到了大疆Android开发的通用钥匙后面切到其他机型SDK也只是参数层面的差别。2. Android Studio集成与Gradle依赖解析把SDK跑起来2.1 工程结构与构建脚本的识别拿到的项目根目录里有gradlew.bat说明这是一个标准的Gradle工程Windows下可以直接用命令行构建。常见做法是先用Android Studio打开项目根目录让它自己解析Gradle插件版本和依赖仓库。注意这个DEMO的目录里还有大量CSS文件例如doc-vendor.css、doc-app.css、search_panel.css这些是SDK文档站点的静态资源不是App运行资源编译时Gradle不会把它们打进APK但如果你用Android Studio打开整个目录可能会让IDE索引变慢我一般会在Project视图里把docs相关的文件夹标记为Excluded。开始之前还要确认一件事你手里的SDK版本对应的大疆机型范围。不同版本对Android系统版本和ARM架构有不同要求比如较新的SDK要求Android 5.0以上并且只支持arm64-v8a和armeabi-v7a。如果项目里没有配置ndk.abiFilters打包时可能把所有ABI都带进去APK体积会变大某些机型反而出现so库加载失败的问题。2.2 在AndroidManifest中声明权限与硬件特性大疆SDK依赖的权限比普通应用多至少需要网络、WiFi、蓝牙、定位、摄像头和外部存储。以Android 8.0及以上系统为例动态权限还要在代码里逐个申请。下面是一份在DEMO里常见的权限声明uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / uses-permission android:nameandroid.permission.CHANGE_WIFI_STATE / uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / uses-permission android:nameandroid.permission.BLUETOOTH / uses-permission android:nameandroid.permission.CAMERA / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE /这里解释一下每个权限的用途INTERNET用于和无人机之间的TCP/UDP通信大疆SDK的控制指令和视频流都走网络传输ACCESS_FINE_LOCATION在Android 6.0以上是WiFi扫描的必需权限否则你搜不到无人机热点BLUETOOTH用于连接遥控器或部分机型的辅助通信CAMERA给FPV镜头预览使用。注意从Android 6.0开始WRITE_EXTERNAL_STORAGE需要运行时申请单纯在Manifest里写上是不够的。2.3 Gradle依赖与Java 8兼容配置在build.gradle里大疆SDK的依赖通常写成这样dependencies { implementation com.dji:dji-sdk:4.16.1 implementation com.dji:dji-sdk-provided:4.16.1 compileOnly com.dji:dji-sdk-provided:4.16.1 }这个写法有个关键点dji-sdk-provided用compileOnly引入而dji-sdk用implementation。原因是SDK里部分系统API在Android系统里已经存在provided只参与编译不打包能避免类冲突。如果你在DEMO里看到的是compile那多半是老版本Gradle的写法需要同步改成implementation否则在Android Studio 4.0以上会直接报错。同时要在compileOptions里开启Java 8支持因为SDK内部用了Lambda表达式和java.time相关APIcompileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 }不开启的话编译时会报default methods或lambda相关的DexError这个报错在社区里出现频率很高。2.4 注册SDK与初始化时机在MainActivity的onCreate里需要先调用SDK注册再判断注册结果。大疆官方推荐的写法是在Application里做注册因为Activity的生命周期可能被系统回收导致重复注册。下面是一段在DEMO里常见的初始化代码public class DJIApplication extends Application { Override public void onCreate() { super.onCreate(); SDKManager.getInstance().init( this, new SDKManagerCallback() { Override public void onRegister(DJIError error) { if (error DJIError.NO_ERROR) { Log.d(SDK, register success); } else { Log.e(SDK, register failed: error.getDescription()); } } } ); } }这段代码的核心是SDKManager.getInstance().init第一个参数是Application上下文第二个参数是回调。onRegister里判断DJIError是否为NO_ERROR注册失败时错误描述会明确告诉你原因比如App Key未配置、网络不通或SDK版本不匹配。接着在MainActivity的onCreate里检查SDKManager.getInstance().isRegistered()只有返回true才允许进入无人机连接流程。2.5 常见集成报错排查我整理了一张排查表覆盖Android Studio集成阶段最常踩的坑报错或现象可能原因处理方式DexArchiveBuilderExceptionJava 8兼容未开启在compileOptions里配置Java 8ClassNotFoundException: com.dji.sdk.SDKManagerdji-sdk-provided被编译进APK确认依赖写法改成compileOnly注册返回INVALID_APP_KEYAndroidManifest里没配大疆App Key在application标签中加meta-data运行崩溃找不到libSDK.soSDK原生库未打包确认ndk.abiFilters包含arm64-v8a如果注册回调完全没有执行优先检查网络。大疆SDK首次注册需要访问大疆服务器校验App Key测试环境防火墙会直接断掉这个请求。另外注意模拟器上跑SDK会大概率失败因为大疆SDK检测到非真机环境会拒绝连接底层硬件服务。3. 初始化SDK与连接无人机的状态机回调顺序决定成败3.1 从Application到Activity的初始化链路DEMO里有一个很关键的顺序先Application里注册SDK再在Activity里启动连接。很多人直接把注册写在MainActivity里结果Activity重建后回调丢失无人机连接时好时坏。正确的链路是Application.onCreate完成SDKManager.init等onRegister回调返回成功再在MainActivity的onStart里执行startConnection。Override protected void onStart() { super.onStart(); if (SDKManager.getInstance().isRegistered()) { BaseProduct product SDKManager.getInstance().getProduct(); if (product null) { SDKManager.getInstance().startConnection(); } } }这里getProduct()返回当前连接的产品对象如果为null说明还没连上需要startConnection()。注意startConnection是异步的结果通过ProductConnectivityListener回调而不是立即返回。所以不要在调用后立刻读取型号和序列号否则拿到的是空对象。3.2 连接状态回调的注册时机DEMO中通常会在onCreate里注册ProductConnectivityListener但有一个细节注册动作要在registerCallback方法完成之后否则系统把SDK内部状态还没准备好的回调排队导致第一次连接事件丢失。大疆SDK提供了SDKManager.getInstance().addProductConnectivityListener(listener)一般在onResume中注册onPause中注销避免界面不可见时还处理飞行控制。Override protected void onResume() { super.onResume(); SDKManager.getInstance().addProductConnectivityListener(this); } Override protected void onPause() { SDKManager.getInstance().removeProductConnectivityListener(this); super.onPause(); }然后实现onProductConnectivityChanged方法Override public void onProductConnectivityChanged(Product product, boolean isConnected) { if (isConnected) { String model product.getModel().getDisplayName(); String serial product.getSerialNumber(); Log.d(CONNECT, connected: model sn serial); } else { Log.w(CONNECT, disconnected); } }回调里isConnected为true不代表可以立即发指令还需要等待FlightController的非空回调。大疆SDK的组件获取是异步的通常有三种方式getFlightController()直接获取、FlightControllerState.Callback监听状态、以及ComponentAvailabilityCallback处理组件失效。DEMO里最常见的写法是每次使用前判空FlightController flightController product.getFlightController(); if (flightController ! null) { flightController.getState().setStateCallback(state - { double altitude state.getAircraftLocation().getAltitude(); boolean isFlying state.isFlying(); Log.d(STATE, altitude altitude flying isFlying); }); }3.3 状态回调顺序与UI刷新策略这里有个容易忽视的顺序问题onProductConnectivityChanged先触发FlightControllerState.Callback后触发。因此你在产品连接回调里立刻去读取高度、电量大概率是旧数据。正确做法是连接回调里只记录isConnected状态然后等FlightControllerState回调把数据刷进ViewModel或UI字段。事件回调方法触发时机UI建议无人机连接onProductConnectivityChanged热连接或断开瞬间更新设备状态图标电池电量BatteryState.Callback电量变化周期上报刷新百分比文本飞行状态FlightControllerState.Callback姿态/位置/飞行模式变化更新地图与速度表GPS信号FlightControllerState.getSatelliteCount()卫星数变化显示信号强度另外FlightControllerState.Callback是回调在SDK的专用线程不能直接操作UI。DEMO里会写一个Handler(Looper.getMainLooper())转发或者用EventBus。我一般用runOnUiThread但频繁刷新的数据用runOnUiThread会有性能问题建议在回调里把数据放进ValueAnimator或LiveData做节流。3.4 状态机断连恢复的幂等处理无人机的WiFi信号不稳定连接断开会比手机App更频繁。如果你在onProductConnectivityChanged(false)里做清理工作比如清空地图标注那么重连成功后要确保这些数据能被重新拉取。一个常见坑是断连清理时把FlightController对象置空了重连后忘记重新获取导致后续getFlightController()返回null。我在DEMO基础上一般会增加一个recovery标记private boolean recovering false; Override public void onProductConnectivityChanged(Product product, boolean isConnected) { if (isConnected recovering) { recovering false; requestFlightState(); } else if (!isConnected) { recovering true; clearUIState(); } }这样断连后只需要恢复关键状态而不是把整个页面重新初始化。注意在requestFlightState()里要再次调用setStateCallback因为SDK在断连后可能清掉了旧回调。4. 飞行控制指令封装与相机动作别让UI线程背锅4.1 FlightController指令的异步调用方式飞行控制不是直接调takeOff()然后等返回而是通过CommonCallbacks.CompletionCallback异步回调结果。DEMO里的起飞按钮对应的代码大致如下flightController.startTakeoff(new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { if (error null) { Log.d(FLIGHT, takeoff success); } else { Log.e(FLIGHT, takeoff failed: error.getDescription()); } } });注意startTakeoff必须在地面状态下调用如果当前已经在空中回调会返回DJIError并给出描述。另外整个调用过程必须确保飞行控制器为非空且当前没有其他指令在执行。大疆SDK对并行的飞控指令是有限制的一个指令没结束前发新指令可能会被直接拒绝。4.2 编队飞行与速度控制的参数细节除了起飞降落DEMO里展示的更多是速度控制指令。FlightController.setVelocity需要传入VelocityX、VelocityY、VelocityZ和YawRate四个参数单位分别是米/秒和度/秒。注意坐标系是机体坐标系还是地面坐标系默认是地面坐标系。FlightControllerState.Velocity velocity new FlightControllerState.Velocity(2.0f, 0.0f, 0.0f, 30.0f); flightController.setVelocity(velocity, new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { if (error ! null) { Log.e(FLIGHT, velocity fail: error.getDescription()); } } });这里Velocity的构造函数四个参数通常对应x、y、z方向的速度和偏航角速度但不同机型SDK版本对速度上限有不同限制比如Mini系列最高平飞速度只有8m/s你传一个15m/s进去SDK会回调参数错误。所以我在封装指令前会先读取产品参数表用AircraftParameters里的最大值做clamp。4.3 相机拍照与录像的线程模型相机操作和飞控操作一样都是异步任务。拍照用Camera.startShootPhoto()录像用Camera.startRecordVideo()停止录像是Camera.stopRecordVideo()。这些方法调用后立即返回结果在回调里收到。千万不能在UI线程等结果因为大疆相机模块在底层做JPEG编码时可能耗时几百毫秒卡住主线程会导致ANR。public void shootPhoto(Camera camera) { camera.startShootPhoto(new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { if (error null) { MediaManager mediaManager camera.getMediaManager(); if (mediaManager ! null) { mediaManager.addMediaUpdatedVideoPlaybackStateListener(state - { // 处理新生成的媒体文件 }); } } } }); }这里还有一个细节拍照完成后新照片会触发MediaManager.VideoPlaybackState更新你可以在这个回调里获取最新的媒体文件列表用于相册刷新。如果只是拍照而不关心文件可以不注册这个监听器。4.4 任务调度避免指令风暴当App需要连续执行多个动作比如“起飞-前进-拍照-返航”如果在每个回调里嵌套调用下一个指令代码会产生回调地狱。DEMO里通常只用简单嵌套但生产环境我建议用一个指令队列private final QueueFlightCommand commandQueue new ConcurrentLinkedQueue(); public void enqueue(FlightCommand cmd) { commandQueue.offer(cmd); if (!isExecuting) { executeNext(); } } private void executeNext() { FlightCommand cmd commandQueue.poll(); if (cmd null) { isExecuting false; return; } isExecuting true; cmd.execute(new CommonCallbacks.CompletionCallback() { Override public void onResult(DJIError error) { isExecuting false; executeNext(); } }); }队列的好处是可以控制指令间隔。CompletionCallback返回后立刻执行下一条中间没有延时。如果需要每个指令之间保持1秒间隔可以在executeNext()里加一个Handler.postDelayed。注意队列要用ConcurrentLinkedQueue因为飞行控制的回调线程和工作线程可能同时访问队列。指令回调线程超时表现常见错误startTakeoffSDK回调线程约10秒无响应未解锁或地面不平setVelocitySDK回调线程无固定超时超过最大飞行速度startShootPhotoSDK回调线程约3秒无响应相机正在录像startRecordVideoSDK回调线程约3秒无响应存储卡已满这张表不是官方超时定义而是我实践里观察到的经验值。实际调试时如果发现指令在某个机型上总是超时最好先检查该机型的AircraftParameters确认动作是否被当前飞行模式禁止。4.5 主线程与SDK线程的日志标记调试时我习惯在关键回调上打线程日志这是区分SDK线程和UI线程最直接的手段private String threadName() { return Thread.currentThread().getName(); }然后在回调里打Log.d(THREAD, thread threadName())。大疆SDK的回调线程名通常以DJI或MessageThread开头UI线程是main。如果发现某个回调在main线程执行并且你在里面做了网络请求或文件写入就需要注意卡顿风险。DEMO里很多示例代码没有显式做线程切换实际项目里还是要用Handler转发到主线程。5. 从DEMO到可交付App权限、日志与真机验证的几个细节5.1 运行时权限与Android 12适配DEMO里的权限写在AndroidManifest.xml但Android 6.0以上需要运行时申请。我整理了一个最小权限请求顺序先定位后WiFi再蓝牙。因为大疆SDK在启动连接前会扫描WiFiAndroid系统要求扫描WiFi前必须拿到精确定位权限。String[] permissions { Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.CAMERA, Manifest.permission.WRITE_EXTERNAL_STORAGE }; if (Build.VERSION.SDK_INT Build.VERSION_CODES.M) { requestPermissions(permissions, 100); }对于Android 12及以上还需要处理蓝牙扫描权限BLUETOOTH_SCAN和连接权限BLUETOOTH_CONNECT否则连接遥控器时会报错。这个在DEMO里没有体现属于自己补的内容。权限请求回调后建议检查onRequestPermissionsResult里所有granted状态都为true再启动SDK连接流程否则直接给用户弹提示。5.2 真机验证顺序与Logcat过滤不要一上来就飞先在手机开发者模式里开启USB调试用USB线连着Android Studio跑DEMO。连接无人机前先看Logcat里有没有SDK注册成功日志过滤关键字SDKManager或DJIError。一个可复用的验证顺序是确认注册成功连接遥控器或飞行器热点检查产品连接回调查看FlightController状态回调最后再点击起飞。常用Logcat命令adb logcat -s DJISDK:D adb logcat -s CONNECT:V STATE:V adb logcat *:E -v time第一条只看SDK级别日志第二条看连接和状态回调第三条按时间过滤所有错误。如果怀疑SDK底层崩溃还需要抓取native日志adb logcat -b crash。这几个命令组合足够覆盖大多数连接问题。5.3 ProGuard混淆规则与包体积控制如果正式打包要开启代码混淆必须为大疆SDK添加keep规则否则运行时会出现类被裁剪的问题。在proguard-rules.pro里至少保留这些-keep class com.dji.** { *; } -dontwarn com.dji.** -keep class dji.** { *; } -keepclassmembers class dji.** { *; }原因是大疆SDK大量使用反射、JNI和动态代理混淆后这些调用点会失联。另外如果你把DEMO的模块直接拷进生产项目注意去掉它自带的android:debuggabletrue和多余的日志输出否则上架审核会提示风险。5.4 模块化拆分建议最后说一个提升点不要把DEMO的Activity直接当生产代码用。DEMO把所有状态都堆在Activity里而实际项目应该把SDK连接、飞控指令、相机管理拆成三个单例或Repository模块用LiveData或回调向上层暴露状态。这样在飞行过程中Activity重建时底层连接不会断。我在做过的一个巡检App里就是这样拆的效果是断线重连恢复时间从四五秒缩短到一秒以内因为不用等Activity重建完成。同时建议把SDKManager.getInstance()的调用封装成一个DroneService内部维护连接状态和组件缓存。DEMO里那种到处直接调用SDKManager的写法只适合演示在工程化项目里会造成大量重复判空和错误处理。把这些细节补上才算真正把DEMO的价值吃透。本文还有配套的精品资源点击获取
