DJI Mobile SDK Documentation

      class Battery

      class Battery extends BaseComponent
      Package:dji.sdk.battery
      Inherits From:BaseComponent
      Description:

      This class manages information and real-time status of the connected product's batteries. This object is available from the Aircraft or HandHeld object which is a subclass of BaseProduct.

      Class Members:

      State Updates

      General
      method
      method setStateCallback
      void setStateCallback(@Nullable BatteryState.Callback callback)
      Package:dji.sdk.battery
      Description:

      Sets the callback that updates battery state.

      Input Parameters:
      @Nullable BatteryState.Callback callbackCallback method.
      method setAggregationStateCallback
      static void setAggregationStateCallback(@Nullable AggregationState.Callback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.AGGREGATION_STATE
      Description:

      Sets the callback that updates aggregated battery state.

      Input Parameters:
      @Nullable AggregationState.Callback callbackCallback method.


      Battery Cell Properties

      Voltage
      method
      method getCellVoltages
      void getCellVoltages(@NonNull CompletionCallbackWith<Integer[]> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.CELL_VOLTAGES
      Description:

      Gets the battery's cell voltages. There will be a voltage for each cell in the battery.

      Input Parameters:
      @NonNull CompletionCallbackWith<Integer[]> callbackAsynchronous execution result callback.
      Number
      method
      method getNumberOfCells
      int getNumberOfCells()
      Package:dji.sdk.battery
      SDK Key:BatteryKey.NUMBER_OF_CELLS
      Description:

      Returns the number of battery cells.

      Return:
      intAn int value.
      method setNumberOfCells
      void setNumberOfCells(@IntRange(from = 3, to = 12) int numberOfCells,
      @Nullable CompletionCallback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.NUMBER_OF_CELLS
      Description:

      When the connected battery is not a smart battery, the number of cells needs to be set manually. The flight controller uses the number of cells and the cell voltage threshold to determine if the aircraft should go home or land. The valid range is [3, 12] cells.

      Input Parameters:
      @IntRange(from = 3, to = 12) int numberOfCellsNumber of cells inside the battery.
      @Nullable CompletionCallback callbackAsynchronous execution result callback.


      Information

      Smart Battery
      method
      method isSmartBattery
      boolean isSmartBattery()
      Package:dji.sdk.battery
      SDK Key:BatteryKey.IS_SMART_BATTERY
      Description:

      true if the battery is a smart battery. When the connected battery is a DJI smart battery, more information can be obtained by communicating with the battery.

      Return:
      boolean><code>true</code> if battery is smart battery.
      Pair Batteries
      method
      method pairBatteries
      void pairBatteries(@Nullable CompletionCallback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.PAIR_BATTERIES
      Description:

      A battery's full charge capacity reduces a little every time it goes through a discharge and recharge cycle. Therefore, older batteries that have gone through many cycles will have lower full charge capacity than newer batteries. When multiple batteries are used simultaneously in a product, the aggregate full charge capacity will be limited by the battery with the lowest full charge capacity.

      To optimize the amount of energy delivered by a battery over its lifetime to a product, batteries should be matched or paired with other batteries of similar full charge capacity. The operational challenges of always using paired batteries can be alleviated using the battery pairing interfaces.

      This method will pair two batteries by recording the aggregate of their serial numbers in each of their firmwares. getPairingState can then be used to determine if the installed battery combination is a previously assigned pair or not. Batteries can be repaired.

      Input Parameters:
      @Nullable CompletionCallback callbackCompletion callback that receives the execution result.
      method getPairingState
      void getPairingState(@NonNull CompletionCallbackWith<PairingState> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.PAIRING_STATE
      Description:

      A battery's full charge capacity reduces a little every time it goes through a discharge and recharge cycle. Therefore, older batteries that have gone through many cycles will have lower full charge capacity than newer batteries. When multiple batteries are used simultaneously in a product, the aggregate full charge capacity will be limited by the battery with lowest full charge capacity.

      To optimize the amount of energy delivered by a battery over its lifetime to a product, batteries should be matched or paired with other batteries of similar full charge capacity. The operational challenges of always using paired batteries can be alleviated using the battery pairing interfaces. This method can then be used to determine if the installed battery combination is a previously assigned pair or not.

      Input Parameters:
      @NonNull CompletionCallbackWith<PairingState> callbackCallback that receives the pairing state.


      Behavior at Thresholds

      Voltage Threshold
      method
      method setLevel1CellVoltageThreshold
      void setLevel1CellVoltageThreshold(@IntRange(from = 3600, to = 4000) int voltage,
      @Nullable CompletionCallback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_1_CELL_VOLTAGE_THRESHOLD
      Description:

      Sets the Level 1 cell voltage threshold in mV. When the cell voltage of the battery crosses below the threshold, Level 1 behavior will be executed. The valid range is [3600, 4000] mV. When the new value is not 100 mV higher than the Level 2 cell voltage threshold, the Level 2 threshold will be set to (new value - 100) mV.

      Input Parameters:
      @IntRange(from = 3600, to = 4000) int voltageLevel 1 cell voltage threshold to set in mV.
      @Nullable CompletionCallback callbackCompletion block that receives the setter execution result.
      method getLevel1CellVoltageThreshold
      void getLevel1CellVoltageThreshold(@NonNull CompletionCallbackWith<Integer> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_1_CELL_VOLTAGE_THRESHOLD
      Description:

      Gets the Level 1 cell voltage threshold in mV. When the cell voltage of the battery crosses below the threshold, Level 1 behavior will be executed. The valid range is [3600, 4000] mV.

      Input Parameters:
      @NonNull CompletionCallbackWith<Integer> callbackAsynchronous execution result callback that contains the voltage threshold.
      method setLevel2CellVoltageThreshold
      void setLevel2CellVoltageThreshold(@IntRange(from = 3500, to = 3800) int voltage,
      @Nullable CompletionCallback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_2_CELL_VOLTAGE_THRESHOLD
      Description:

      Sets the Level 2 cell voltage threshold in mV. When the cell voltage of the battery crosses below the threshold, Level 2 behavior will be executed. The valid range is [3500, 3800] mV and must be at least 100 mV lower than the Level 1 voltage threshold.

      Input Parameters:
      @IntRange(from = 3500, to = 3800) int voltageLevel 2 cell voltage threshold to set in mV.
      @Nullable CompletionCallback callbackAsynchronous execution result callback.
      method getLevel2CellVoltageThreshold
      void getLevel2CellVoltageThreshold(@NonNull CompletionCallbackWith<Integer> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_2_CELL_VOLTAGE_THRESHOLD
      Description:

      Gets the Level 2 cell voltage threshold in mV. When the cell voltage of the battery crosses below the threshold, Level 2 behavior will be executed.

      Input Parameters:
      @NonNull CompletionCallbackWith<Integer> callbackAsynchronous execution result callback that contains the voltage threshold.
      Threshold Behavior
      method
      method setLevel1CellVoltageBehavior
      void setLevel1CellVoltageBehavior(@NonNull LowVoltageBehavior behavior,
      @Nullable CompletionCallback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_1_CELL_VOLTAGE_BEHAVIOR
      Description:

      Sets the behavior that will be executed when the cell voltage crosses under the Level 1 threshold. It can only be set when the motors are off.

      Input Parameters:
      @NonNull LowVoltageBehavior behaviorLevel 1 behavior.
      @Nullable CompletionCallback callbackCompletion block that receives the setter execution result.
      method getLevel1CellVoltageBehavior
      void getLevel1CellVoltageBehavior(@NonNull CompletionCallbackWith<LowVoltageBehavior> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_1_CELL_VOLTAGE_BEHAVIOR
      Description:

      Gets the behavior that will be executed when the cell voltage crosses under the Level 1 threshold.

      Input Parameters:
      @NonNull CompletionCallbackWith<LowVoltageBehavior> callbackAsynchronous execution result callback that contains the voltage threshold behavior.
      method setLevel2CellVoltageBehavior
      void setLevel2CellVoltageBehavior(@NonNull LowVoltageBehavior behavior,
      @Nullable CompletionCallback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_2_CELL_VOLTAGE_BEHAVIOR
      Description:

      Sets the operation that will be executed when the cell voltage crosses under Level 2 threshold. It can only be set when motors are off.

      Input Parameters:
      @NonNull LowVoltageBehavior behaviorLevel 2 behavior.
      @Nullable CompletionCallback callbackAsynchronous execution result callback.
      method getLevel2CellVoltageBehavior
      void getLevel2CellVoltageBehavior(@NonNull CompletionCallbackWith<LowVoltageBehavior> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LEVEL_2_CELL_VOLTAGE_BEHAVIOR
      Description:

      Sets the behavior that will be executed when the cell voltage crosses under the Level 2 threshold.

      Input Parameters:
      @NonNull CompletionCallbackWith<LowVoltageBehavior> callbackAsynchronous execution result callback that contains the voltage threshold behavior.


      Warning Records

      method getLatestWarningRecord
      void getLatestWarningRecord(@NonNull CompletionCallbackWith<WarningRecord> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.LATEST_WARNING_RECORD
      Description:

      Gets the battery's most recent warning record. Anytime the battery experiences a significant exception, it will get recorded as a warning record.

      Input Parameters:
      @NonNull CompletionCallbackWith<WarningRecord> callbackAsynchronous execution result callback that contains the latest warning record.
      Historical
      method
      method getWarningRecords
      void getWarningRecords(@NonNull CompletionCallbackWith<WarningRecord[]> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.HISTORICAL_WARNING_RECORDS
      Description:

      Gets the battery's warning records, which are kept for 30 days using objects of type WarningRecord. Call the isSmartBattery() method before using this method. Not supported by Osmo and non-smart batteries.

      Input Parameters:
      @NonNull CompletionCallbackWith<WarningRecord[]> callbackAsynchronous execution result callback that contains the batteries warning records.


      Discharge

      Self Discharge
      method
      method setSelfDischargeInDays
      void setSelfDischargeInDays(@IntRange(from = 1, to = 20) int days,
      @Nullable CompletionCallback callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.SELF_DISCHARGE_IN_DAYS
      Description:

      Smart batteries can be setup to automatically discharge over a custom period of time. This method sets the battery's self discharge period in days with range [1, 10]. For Inspire 2 and M200 series products, the max range value can be 20. Not supported by non-smart batteries, Spark and the Osmo series.

      Input Parameters:
      @IntRange(from = 1, to = 20) int daysDay for self-discharge
      @Nullable CompletionCallback callbackAsynchronous execution result callback.
      method getSelfDischargeInDays
      void getSelfDischargeInDays(@NonNull CompletionCallbackWith<Integer> callback)
      Package:dji.sdk.battery
      SDK Key:BatteryKey.SELF_DISCHARGE_IN_DAYS
      Description:

      Smart batteries can be setup to automatically discharge over a custom period of time. This method gets the battery's self discharge period in days with range [1, 10]. For Inspire 2 and M200 series products, the max range value can be 20. Not supported by non-smart batteries and the Osmo series.

      Input Parameters:
      @NonNull CompletionCallbackWith<Integer> callbackAsynchronous execution result callback that contains the number of days to discharge over.


      General
      class
      enum LowVoltageBehavior
      @EXClassNullAway
      enum LowVoltageBehavior
      Package:dji.common.battery
      SDK Key:BatteryKey.LEVEL_1_CELL_VOLTAGE_BEHAVIOR, BatteryKey.LEVEL_2_CELL_VOLTAGE_BEHAVIOR
      Description:

      Defines aircraft's behavior when the cell voltage is low.

      Enum Members:
      FLASH_LEDLED lights go into warning mode.
      GO_HOMEReturn-to-Home.
      LANDLand aircraft immediately.
      UNKNOWNUnknown.
      Class Members:
      enum PairingState
      @EXClassNullAway
      enum PairingState
      Package:dji.common.battery
      SDK Key:BatteryKey.PAIRING_STATE
      Description:

      Battery pairing state for batteries that can be paired.

      Enum Members:
      UNPAIREDThe batteries didn't match; they're not paired.
      PAIREDBatteries are paired.
      UNKNOWNCan't get the pair state or the batteries.
      Class Members:
      enum SelfHeatingState
      enum SelfHeatingState
      Package:dji.common.battery
      Description:

      Provides the self-heating state for the battery. When the temperature of the battery is below a threshold, it will warm up automatically. For Mavic 2 Enterprise, the self-heating is triggered when the temperature is lower than 6 Celsius degrees. When the temperature reaches 8 Celsius degrees, the battery will start to preserve the temperature and maintain it between 6 Celsius degrees and 8 Celsius degrees.

      Enum Members:
      IDLEThe auto heating feature is idle.
      WARMING_UPThe battery is warming itself up automatically.
      PRESERVINGThe battery is preserving its temperature. For Mavic 2 Enterprise, the temperature will be maintained between 6 Celsius degrees and 8 Celsius degrees.
      UNKNOWNUnknown.
      Class Members:


      enum ConnectionState
      @EXClassNullAway
      enum ConnectionState
      Package:dji.common.battery
      SDK Key:BatteryKey.CONNECTION_STATE
      Description:

      Battery connection status. 0 means NORMAL, 1 means INVALID, and 2 means EXCEPTION in communication.

      Enum Members:
      NORMALNormal.
      INVALIDInvalid.
      EXCEPTIONException.
      UNKNOWNUnknown.
      Class Members:
      Inherited Methods:
      dji.sdk.base.BaseComponent
      method
      method setComponentListener
      void setComponentListener(ComponentListener listener)
      Package:dji.sdk.base
      Description:

      Sets the listener for the DJI component.

      Input Parameters:
      ComponentListener listenerThe callback of ComponentListener.
      method
      method getIndex
      int getIndex()
      Package:dji.sdk.base
      Description:

      Returns the component index. Index is zero based. A component will have an index greater than zero when there are multiple components of the same type on the DJI product, and one of the components already has the index 0. For instance, M210 can have two gimbal mounted cameras, and will therefore have two gimbal components with indices 0 and 1, and two camera components with indices 0 and 1. For Matrice 600, there are printed numbers on the battery boxes. The Battery component instance with index 0 corresponds to battery compartment number 1. For Inspire 2 and M200 series, Battery with index 0 corresponds to the battery on the port (left hand) side of the aircraft. For M210 and M210 RTK, Camera and Gimbal with index 0 corresponds to the camera and gimbal on the port (left hand) side of the aircraft.

      Return:
      intAn int value of index.
      method isConnected
      boolean isConnected()
      Package:dji.sdk.base
      Description:

      true if the component is connected.

      Return:
      booleantrue if the component is connected.
      method getSerialNumber
      void getSerialNumber(@NonNull CompletionCallbackWith<String> callback)
      Package:dji.sdk.base
      Description:

      Gets the serial number of the component. Depending on the component, this serial number might not match the serial number found on the physical component.

      Input Parameters:
      @NonNull CompletionCallbackWith<String> callbackThe execution callback with the value returned.
      method getFirmwareVersion
      void getFirmwareVersion(@NonNull CompletionCallbackWith<String> callback)
      Package:dji.sdk.base
      Description:

      Returns the firmware version of the component. Each component will have a different firmware version, the combination of which will form the package firmware version getFirmwarePackageVersion found in BaseProduct.

      Input Parameters:
      @NonNull CompletionCallbackWith<String> callbackThe execution callback with the value(s) returned.