4.X 和 5.X 版本差异说明
以下内容主要目的是将MSDK 4.X版本和MSDK 5.X版本中的核心接口做对比和说明，其中主要包含了DJIKey类型接口的对比说明，和几个核心模块的差异点说明，例如SDK注册管理类（SDKManager）、设备健康状态管理类（DeviceHealthManager）等，希望能帮助开发者快速了解和使用MSDK 5.X版本。
注意：
- 目前MSDK 4.X和5.X还不兼容，不能一起使用。
- MSDK 5.X 目前支持机型查看版本发布中的“支持产品列表和固件版本”，且未来只计划支持部分DJI的新机型。
DJIKey差异说明
DJIKey
MSDK 5.X 大多数与设备交互的功能，都是基于DJIKey来实现的，一个DJIKey代表指定模块的具体功能。
在4.X上，大部分接口的本质是对DJIKey的封装，比如说Camera$startShootPhoto，其本质是CameraKey.START_SHOOT_PHOTO的应用。在后面对比表格中，对于4.X，只显示DJIKey，而不是接口。如有特别需要说明的情况，会特殊处理。
这里以FlightControllerState下的Motors中的方法areMotorsOn为例：先通过方法areMotorsOn在4.X文档中，搜到areMotorsOn的方法说明，然后查询到对应的4.X DJIKey.FlightControllerKey.ARE_MOTOR_ON，继而在迁移文档中找到方法areMotorsOn对应的5.X DJIKey。
区别：
| 功能描述 | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| DJIKey操作 | KeyManager | IKeyManager | Key操作封装类 |
| DJIKey创建 | 各类Key Class中的create方法，如：CameraKey$create、CameraKey$createLensKey、FlightControllerKey$create等。 | KeyTools | 5.X的Key创建统一用Keytools中的相关接口 |
| DJIKey-产品 | ProductKey | ProductKey | 5.X是针对整机来说的 |
| DJIKey-AirLink | AirLinkKey | AirLinkKey | AirLink相关 |
| DJIKey-基站 | BaseStationKey | RtkBaseStationKey | RTK基站相关 |
| DJIKey-电池 | BatteryKey | BatteryKey | 电池相关 |
| DJIKey-相机 | CameraKey | CameraKey | 相机相关 |
| DJIKey-飞控 | FlightControllerKey | FlightControllerKey | 飞控相关 |
| DJIKey-云台 | GimbalKey | GimbalKey | 云台相关 |
| DJIKey-激光雷达 | LidarKey | LidarKey | 激光雷达相关 |
| DJIKey-DJI负载 | PayloadKey | PayloadKey | Payload负责相关 |
| DJIKey-雷达 | RadarKey | RadarKey | 雷达相关 |
| DJIKey-遥控 | RemoteControllerKey | RemoteControllerKey | 遥控相关 |
KeyManager
| 功能描述 | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 读取数据 | KeyManager$getValue | IKeyManager$getValue | 类似 |
| 设置数据 | KeyManager$setValue | IKeyManager$setValue | 类似 |
| 执行Action | KeyManager$performAction | IKeyManager$performAction | 类似 |
| 监听 | KeyManager$addListener | IKeyManager$listen | 5.X引入一个Holder的概念，开发者可以将一系列Listener实例绑定到Holder上，后面在释放监听时，可以通过IKeyManager$cancelListen(Object listenHolder)一并取消 |
| 取消监听 | KeyManager$removeListener | IKeyManager$cancelListen | 见监听的说明 |
| 移除Key的数据 | KeyManager$removeKey | 无 | 5.X不支持该功能 |
如何CreateKey
在4.X上，DJIKey的create方法定义在各类模块Key中，这里以CameraKey来举例：
- 创建主位置的Key：CameraKey$create(String paramKey)
- 创建指定位置的Key：CameraKey$create(String paramKey, int componentIndex)
- 创建指定位置、指定镜头的Key：CameraKey$createLensKey(String paramKey, int componentIndex, int subComponentIndex)
在5.X上，DJIKey的create方法统一定义到KeyTools中，以CameraKey为例：
只有一种方法，创建指定位置、指定镜头的DJIKey：KeyTools$createCameraKey(DJIKeyInfo<T> mKeyInfo, ComponentIndexType componentIndexType, CameraLensType cameraLensType)，相关DJIKey如果不指明镜头的话，就用CameraLensType.CAMERA_LENS_DEFAULT（在Kotlin上，DJIKeyInfo有扩展方法createCamera，cameraLensType默认值就是CameraLensType.CAMERA_LENS_DEFAULT）。
参数说明：
| 功能描述 | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| DJIKey信息 | paramKey | mKeyInfo | 描述DJIKey的基本信息。 |
| 相机位置 | componentIndex | ComponentIndexType | 相机位置，5.X上使用枚举来替代。 |
| 镜头位置 | subComponentIndex | CameraLensType | 镜头位置，5.X上使用枚举来替代。 |
5.X的其他部分，请参考KeyTools文档：KeyTools
ProductKey映射关系
| 功能描述 | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 产品连接 | ProductKey.CONNECTION | ProductKey.KeyConnection | 类似 |
FligthControllerKey映射关系
| 功能描述(FligthController) | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 产品连接 | FlightControllerKey.CONNECTION | FlightControllerKey.KeyConnection | 类似 |
| 电机是否启动 | FlightControllerKey.ARE_MOTOR_ON | FlightControllerKey.KeyAreMotorsOn | 类似 |
| airSense 连接状态 | FlightControllerKey.AIR_SENSE_SYSTEM_CONNECTE | FlightControllerKey.KeyAirSenseSystemConnected | 类似 |
| airSense 信息 | FlightControllerKey.AIR_SENSE_SYSTEM_WARNING_LEVEL 、FlightControllerKey.AIR_SENSE_AIRPLANE_STATES | FlightControllerKey.KeyAirSenseSystemInformation | 类似 |
| 飞机高度 | FlightControllerKey.ALTITUDE | FlightControllerKey.KeyAltitude | 类似 |
| 起飞点高度 | FlightControllerKey.TAKEOFF_LOCATION_ALTITUDE | FlightControllerKey.KeyTakeoffLocationAltitude | 类似 |
| 返航点高度 | FlightControllerKey.GO_HOME_HEIGHT_IN_METERS | FlightControllerKey.KeyGoHomeHeight | 类似 |
| Home点位置 | FlightControllerKey.HOME_LOCATION_LATITUDE、FlightControllerKey.HOME_LOCATION_LONGITUDE | FlightControllerKey.KeyHomeLocation | 类似 |
| 当前高度 | FlightControllerKey.ALTITUDE | FlightControllerKey.KeyAltitude | 类似 |
| 飞机位置 | FlightControllerKey.AIRCRAFT_LOCATION_LATITUDE、FlightControllerKey.AIRCRAFT_LOCATION_LONGITUDE | FlightControllerKey.KeyAircraftLocation | 4.X经纬度分别是两个Key，5.X上为一个对象里包含两者数据 |
| 是否正在飞行 | FlightControllerKey.IS_FLYING | FlightControllerKey.KeyIsFlying | 类似 |
| 是否正在下降 | FlightControllerKey.IS_LANDING | FlightControllerKey.KeyIsInLandingMode | 类似 |
| 是否需要确认下降 | FlightControllerKey.IS_LANDING_CONFIRMATION_NEEDED | FlightControllerKey.KeyIsLandingConfirmationNeeded | 类似 |
| 强制降落高度 | FlightControllerKey.FORCE_LANDING_HEIGHT | FlightControllerKey.KeyTouchDownConfirmLimitHeight | 类似 |
| 飞行模式字符串 | FlightControllerKey.FLIGHT_MODE_STRING | FlightControllerKey.KeyFlightModeString | 类似 |
| 降落保护状态 | FlightControllerKey.LANDING_PROTECTION_STATE | FlightAssistantKey.KeyLandingProtectionState | 类似 |
| 返航所需电量 | FlightControllerKey.BATTERY_PERCENTAGE_NEEDED_TO_GO_HOME | FlightControllerKey.KeyBatteryPercentNeededToGoHome | 类似 |
CameraKey映射关系
| 功能描述 （Camera） | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 连接状态 | CameraKey.CONNECTION | CameraKey.KeyConnection | 类似 |
| 开始拍照 | CameraKey.START_SHOOT_PHOTO | CameraKey.KeyStartShootPhoto | 类似 |
| 停止拍照 | CameraKey.STOP_SHOOT_PHOTO | CameraKey.KeyStopShootPhoto | 类似 |
| 自动曝光开关 | CameraKey.AE_LOCK | CameraKey.KeyAELockEnabled | 类似 |
| 是否正在录像 | CameraKey.IS_RECORDING | CameraKey.KeyIsRecording | 类似 |
| 录制时长 | CameraKey.CURRENT_VIDEO_RECORDING_TIME_IN_SECONDS | CameraKey.KeyRecordingTime | 类似 |
| 相机类型 | CameraKey.CAMERA_TYPE | CameraKey.KeyCameraType | 类似 |
| 存储类型 | CameraKey.CAMERA_STORAGE_LOCATION | CameraKey.KeyCameraStorageLocation | 类似 |
| SD卡状态 | CameraKey.SDCARD_STATE | CameraKey.KeyCameraSDCardState | 类似 |
| 内部存储介质状态 | CameraKey.INNERSTORAGE_STATE | CameraKey.KeyInternalStorageState | 类似 |
| 当前SD卡可录制时长 | CameraKey.SDCARD_AVAILABLE_RECORDING_TIME_IN_SECONDS | CameraKey .KeySSDAvailableRecordingTimeInSeconds | 类似 |
| 当前内部存储可录制时长 | CameraKey.INNERSTORAGE_AVAILABLE_RECORDING_TIME_IN_SECONDS | CameraKey.KeyInternalStorageAvailableVideoDuration | 类似 |
| 开始录制 | CameraKey.START_RECORD_VIDEO | CameraKey.KeyStartRecord | 类似 |
| 结束录制 | CameraKey.STOP_RECORD_VIDEO | CameraKey.KeyStopRecord | 类似 |
| 自动包围曝光次数 | CameraKey.PHOTO_AEB_COUNT | CameraKey.KeyAEBSettings | 4.X的count在5.X的PhotoAEBSettings类里 |
| 连拍次数 | CameraKey.PHOTO_BURST_COUNT | CameraKey.KeyPhotoBurstCount | 类似 |
| 连拍设置 | CameraKey.PHOTO_TIME_INTERVAL_SETTINGS | CameraKey.KeyPhotoIntervalShootSettings | 类似 |
| raw格式连拍次数 | CameraKey.PHOTO_RAW_BURST_COUNT | CameraKey.KeyRawBurstCount | 类似 |
| 全景模式 | CameraKey.PHOTO_PANORAMA_MODE | CameraKey.KeyPhotoPanoramaMode | 类似 |
| 是否正在拍照 | CameraKey.IS_SHOOTING_PHOTO | CameraKey.KeyIsShootingPhoto | 类似 |
| 是否正在保存照片 | CameraKey.IS_STORING_PHOTO | CameraKey.KeyCameraStoringFile | 类似 |
| 能否拍照 | CameraKey.IS_SHOOTING_PHOTO_ENABLED | CameraKey.KeyShootPhotoNotAllowed | 类似 |
| 是否正在拍照全景照片 | CameraKey.IS_SHOOTING_PANORAMA_PHOTO | CameraKey.KeyIsShootingPhotoPanorama | 类似 |
| 曝光模式 | CameraKey.EXPOSURE_MODE | CameraKey.KeyExposureMode | 类似 |
| 曝光模式范围 | CameraKey.EXPOSURE_MODE_RANGE | CameraKey.KeyExposureModeRange | 类似 |
| ISO设置 | CameraKey.ISO | CameraKey.KeyISO | 类似 |
| ISO设置范围 | CameraKey.ISO_RANGE | CameraKey.KeyISORange | 类似 |
| 曝光设置 | CameraKey.EXPOSURE_SETTINGS | CameraKey.KeyExposureSettings | 类似 |
| 曝光感光度设置 | CameraKey.EXPOSURE_SENSITIVITY_MODE | CameraKey.KeyExposureSensitivityMode | 类似 |
| EI值 | CameraKey.EI_VALUE | CameraKey.KeyEI | 类似 |
| 推荐EI值 | CameraKey.RECOMMENDED_EI_VALUE | CameraKey.KeyRecommendedEI | 类似 |
| EI值范围 | CameraKey.EI_VALUE_RANGE | CameraKey.KeyEIRange | 类似 |
| 相机模式 | CameraKey.MODE/CameraKey.FLAT_CAMERA_MODE | CameraKey.KeyCameraMode | 5.X对4.X 两个ModeKey做了统一处理，整合成一个 |
| 图传视频源 | CameraKey.CAMERA_VIDEO_STREAM_SOURCE | CameraKey.KeyCameraVideoStreamSource | 类似 |
| 对焦模式 | CameraKey.FOCUS_MODE | CameraKey.KeyCameraFocusMode | 类似 |
| 测光模式 | CameraKey.METERING_MODE | CameraKey.KeyCameraMeteringMode | 类似 |
| 对焦目标 | CameraKey.FOCUS_TARGET | CameraKey.KeyCameraFocusTarget | 类似 |
| 点测光目标 | CameraKey.SPOT_METERING_TARGET | CameraKey.KeySpotMeteringTargetPoint | 类似 |
GimbalKey映射关系
| 功能描述 (Gimbal) | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 云台连接状态 | GimbalKey.CONNECTION | GimbalKey.KeyConnection | 类似 |
| 云台姿态 | GimbalKey.ATTITUDE_IN_DEGREES | GimbalKey.KeyGimbalAttitude | 类似 |
| 旋转云台 | GimbalKey.ROTATE | GimbalKey.KeyRotateBySpeed、GimbalKey.KeyRotateByAngle | 5.X抽离了模式，变成了两个Key |
RemoteControlKey映射关系
| 功能描述 (RemoteControl) | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 连接事件 | RemoteControllerKey.CONNECTION | RemoteControllerKey.KeyConnection | 类似 |
| 电池状态 | RemoteControllerKey.BATTERY_STATE | RemoteControllerKey.KeyBatteryInfo | 类似 |
| 是否低电量 | RemoteControllerKey.IS_CHARGE_REMAINING_LOW | RemoteControllerKey.KeyBatteryInfo | 需要开发者根据当前电量自己算，4.X时小于30%为低。 |
| 遥控GPS信息 | RemoteControllerKey.GPS_DATA | RemoteControllerKey.KeyRcGPSInfo | 类似 |
| 遥控模式设置 | RemoteControllerKey.AIRCRAFT_MAPPING_STYLE | RemoteControllerKey.KeyControlMode | 相比4.X，5.X更直接，可以通过枚举明确遥控模式。 |
RTKKey映射关系
| 功能描述 (RTK) | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| Home点数据源 | FlightControllerKey.RTK_FUSION_HOME_LOCATION_DATA_SOURCE | RtkMobileStationKey.KeyRTKHomePointInfo | 类似 |
| 起飞高度是否设置 | FlightControllerKey.RTK_FUSION_HAS_SET_TAKE_OFF_ALTITUDE | RtkMobileStationKey.KeyRTKTakeoffAltitudeInfo | 类似 |
| 是否启用RTK | FlightControllerKey.RTK_ENABLED | RtkMobileStationKey.KeyRTKEnable | 类似 |
| 是否支持RTK | FlightControllerKey.IS_RTK_SUPPORTED | FlightControllerKey.KeyIsRtkSupported | 类似 |
| RTK是否连接 | FlightControllerKey.IS_RTK_CONNECTED | RtkMobileStationKey.KeyConnection | 类似 |
BatteryKey映射关系
| 功能描述 (Battery) | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 电池温度 | BatteryKey.TEMPERATURE | BatteryKey.KeyBatteryTemperature | 类似 |
| 电池电量 | BatteryKey.CHARGE_REMAINING_IN_PERCENT | BatteryKey.KeyChargeRemainingInPercent | 类似 |
| 电池电压 | BatteryKey.CELL_VOLTAGES | BatteryKey.KeyCellVoltages | 类似 |
| 异常信息 | BatteryKey.LATEST_WARNING_RECORD | BatteryKey.KeyBatteryException | 5.X都集中在这个Key中 |
| 整合信息 | BatteryKey.AGGREGATION_STATE | BatteryKey.KeyNumberOfConnectedBatteries、BatteryKey.KeyIsAnyBatteryDisconnected、BatteryKey.KeyIsCellDamaged、BatteryKey.KeyIsFirmwareDifferenceDetected、BatteryKey.KeyIsVoltageDifferenceDetected、BatteryKey.KeyIsLowCellVoltageDetected、BatteryKey.KeyBatteryOverviews | 4.X上读取的是多电池的聚合信息，在5.X上，创建DJIKey时，传入ComponentIndexType.AGGREGATION |
DJI核心模块差异说明
ISDKManager
ISDKManager为MSDK入口管理类，相对于4.X做了简化。请参考快速入门，熟悉注册、配置、APP_Key申请以及示例代码的使用。
| 功能描述 | 4.x | 5.x | 说明/区别 |
|---|---|---|---|
| 注册/激活 | DJISDKManager$registerApp | SDKManager$init 和 SDKManager$registerApp | 5.x抽离了init部分，开发者需要在应用启动后，有且仅调用一次init。 |
| 设备连接事件 | SDKManagerCallback$onComponentChange | 使用各类Key 的KeyConnection，如：CameraKey.KeyConnection、FlightControllerKey.KeyConnection | 5.x通过各模块的KeyConnection来监听设备连接事件 |
虚拟摇杆模块
虚拟摇杆4.X和5.X接口层面差异较多，请参考5.X文档：虚拟摇杆。
如果原来使用DJIKey实现的话，有如下对比：
| 功能描述（VirtualStick） | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 开/关虚拟摇杆 | FlightControllerKeys.VIRTUAL_STICK_CONTROL_MODE_ENABLED | FlightControllerKey.KeyVirtualStickEnabled | 类似 |
| 发送虚拟摇杆数据 | FlightControllerKeys.SEND_VIRTUAL_STICK_FLIGHT_CONTROL_DATA | FlightControllerKey.KeySendVirtualStickFlightControlData | 整体数据类似 |
图传模块
相比于4.X，5.X图传简化了不少操作，请参考5.X文档：图传。
直播模块
相比于4.X，5.X直播功能更丰富，支持的协议更多，请参考5.X文档：直播。
诊断管理模块
在5.X上，错误诊断通过IDeviceHealthManager来完成，请参考5.X文档：诊断管理。
参数对比：
| 描述 | 4.X | 5.X | 说明/区别 |
|---|---|---|---|
| 错误码 | DJIDiagnostics$getCode | DJIDeviceHealthInfo$informationCode | 相对于4.X，5.X的HMS错误码更方便查阅、更全面、更多。 |
| 错误描述 | DJIDiagnostics$getReason、DJIDiagnostics$getSolution | DJIDeviceHealthInfo$title、DJIDeviceHealthInfo$description | 5.X统一为title以及错误描述（支持中英文）。 |
模拟器模块
模拟器请参考5.X文档：模拟器。
媒体文件模块
媒体文件请参考5.X文档：多媒体。
航线模块
当前航线通过KMZ文件发送到飞机，请参考5.X文档：航线。
RTK模块
RTK请参考5.X文档：RTK。
LDM模块
LDM请参考5.X文档：LDM。