DJI Mobile SDK for Android

Introduced in SDK 4.0, Keyed Interfaces provide a modern way to access and monitor the state of a connected DJI product. Instead of using traditional component-based interfaces (e.g., getProduct().getCamera()), you use DJIKey objects as "addresses" to specific pieces of state and interact with them via the KeyManager.

Core Workflow

1. Identify the Key: Use a specific DJIKey subclass (like CameraKey or FlightControllerKey) to create a key representing the state you want to access.
2. Access State: Use KeyManager.getValue() to retrieve the current value or KeyManager.setValue() to change it.
3. Listen for Changes: Use KeyManager.addListener() to receive updates only when the specific state actually changes.

Key Advantages over Existing Interfaces

• Multiple Listeners: Unlike traditional state callbacks which often allow only one listener at a time, you can attach multiple KeyListener instances to the same DJIKey.
• Reduced Noise: Traditional callbacks often fire at high frequencies regardless of whether the specific value changed. Keyed interface listeners are only triggered when the value actually changes.
• Performance: The SDK uses an in-memory cache for keyed interfaces, reducing latency by avoiding unnecessary roundtrip calls to the hardware when a valid cached value exists.
• UI Integration: The mechanism is optimized for UI layers; the DJI UI Library is built entirely on this interface.

// Example: Accessing ISO via Keyed Interface
DJIKey isoKey = CameraKey.create(CameraKey.ISO);
DJISDKManager.getInstance().getKeyManager().getValue(isoKey, new GetCallback() {
    @Override public void onSuccess(@NonNull Object value) {
        if (value instanceof SettingsDefinitions.ISO) {
            SettingsDefinitions.ISO iso = (SettingsDefinitions.ISO) value;
            // Use ISO value
        }
    }

    @Override public void onFailure(@NonNull DJIError error) {
        // Handle error
    }
});

To react to changes in product state (like altitude or battery level) without the overhead of high-frequency polling, use KeyManager.addListener(). This method allows you to register a KeyListener that triggers only when the value associated with a specific DJIKey changes.

Implementation Steps

1. Create the DJIKey for the property you want to monitor.
2. Call DJISDKManager.getInstance().getKeyManager().addListener(key, listener).
3. Implement onValueChange(Object oldValue, Object newValue) to handle the update.

Example: Monitoring Aircraft Altitude

// 1. Create the Flightcontroller altitude key object
DJIKey altitudeKey = FlightControllerKey.create(FlightControllerKey.ALTITUDE);

// 2. Add a listener for altitude changes
DJISDKManager.getInstance().getKeyManager().addListener(altitudeKey, new KeyListener() {
    @Override public void onValueChange(@Nullable Object oldValue, @Nullable Object newValue) {
        if (newValue instanceof Float) {
            final float altitude = (Float) newValue;
            // Handle altitude change
        }
    }
});

// Create Flightcontroller altitude key object
DJIKey altitudeKey = FlightControllerKey.create(FlightControllerKey.ALTITUDE);

// Add a listener with KeyListener callback for altitude key. NOTE: You can add multiple listeners for the same key
DJISDKManager.getInstance().getKeyManager().addListener(altitudeKey, new KeyListener() {
    @Override public void onValueChange(@Nullable Object oldValue, @Nullable Object newValue) {
        if (newValue instanceof Float) {
            final float altitude = (Float) newValue;
            // Do something with altitude value
        }
    }
});

A DJIKey acts as a unique address for a specific piece of state information. Each component (Camera, FlightController, Battery, etc.) has its own dedicated DJIKey subclass.

To create a key, use the .create(String paramKey) method of the appropriate subclass. You can find available parameter keys in the class files or the component's existing interface documentation.

Common Patterns

• Single Component: CameraKey.create(CameraKey.ISO)
• Indexed Components: For products with multiple components of the same type (like multiple batteries on a Matrice 600), pass an index to the create method.

Examples

// Access camera shooting mode
DJIKey cameraShootPhotoModeKey = CameraKey.create(CameraKey.SHOOT_PHOTO_MODE);
    
// Address a specific battery (e.g., battery index 2)
DJIKey chargeRemainingOfBattery2Key = BatteryKey.create(BatteryKey.CHARGE_REMAINING, 2);

// Access flight controller status
DJIKey isFlyingKey = FlightControllerKey.create(FlightControllerKey.IS_FLYING);

// Examples of DJIKey constructor methods
DJIKey cameraShootPhotoModeKey = CameraKey.create(CameraKey.SHOOT_PHOTO_MODE);
    
// Addresses specific battery if the product has multiple batteries (eg. Matrice 600)
DJIKey chargeRemainingOfBattery2Key = BatteryKey.create(BatteryKey.CHARGE_REMAINING, 2);

DJIKey isFlyingKey = FlightControllerKey.create(FlightControllerKey.IS_FLYING);

For certain components (specifically Matrice 300 RTK and Zenmuse H20 series), you can use the hms.json and hms_match_sdkerror.json files to retrieve detailed error descriptions for device components. It is recommended to use this health information instead of older diagnostics for the flight controller and RTK.

Note on Duplicated Errors: Some component errors (gimbal, battery, perception module) may appear duplicated on the Matrice 300 RTK. Use the following mapping to resolve them:

| DJIDiagnosticsError | Enum Value | AlarmId |
|:------------- |:---------------:| -------------:|
| `BATTERY_DISCHARGE_OVER_CURRENT`  | 3001 | 0x110B0001|
| `BATTERY_DISCHARGE_OVER_HEAT` | 3002 | 0x110B0002|
| `BATTERY_LOW_TEMPERATURE` | 3003 | 0x110B0003|
| `BATTERY_CELL_BROKEN` | 3004 | 0x110B0006 |
| `GIMBAL_CONNECT_TO_FC_ERROR` | 2005 | 0x1D030001 |
| `GIMBAL_GYROSCOPE_ERROR` | 2001 | 0x1D040002 |
| `GIMBAL_PITCH_ERROR` | 2002 | 0x1D040004 |
| `GIMBAL_ROLL_ERROR` | 2003 | 0x1D040003 |
| `GIMBAL_YAW_ERROR` | 2004 | 0x1D040005 |