DJI Mobile SDK Documentation

      class DJIBattery

      @interface DJIBattery : DJIBaseComponent
      Header:DJIBattery.h
      Inherits From:DJIBaseComponent
      Description:

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

      Class Members:

      State Updates

      General
      property
      property delegate
      @property(nonatomic, weak) id<DJIBatteryDelegate> delegate
      Header:DJIBattery.h
      Description:

      Delegate that receives the updated state pushed by the battery.

      See Also:

      DJIBatteryDelegate

      Aggregation
      class method
      class method setAggregationDelegate
      + (void)setAggregationDelegate:(id<DJIBatteryAggregationDelegate>_Nullable)delegate
      Header:DJIBattery.h
      Description:

      Delegate that receives the updated state pushed by the battery.

      Input Parameters:
      id<DJIBatteryAggregationDelegate>_Nullable delegateThe delegate that will receive the aggregation information.
      class method aggregationDelegate
      + (id<DJIBatteryAggregationDelegate>_Nullable)aggregationDelegate
      Header:DJIBattery.h
      Description:

      Gets the delegate that receives the battery aggregation state. It is only useful when the aircraft has multiple batteries.

      Return:
      id<DJIBatteryAggregationDelegate>_NullableThe delegate setup to receive battery aggregation information.


      Battery Cell Properties

      method getCellVoltagesWithCompletion
      - (void)getCellVoltagesWithCompletion:(void (^_Nonnull)(NSArray<NSNumber *> *_Nullable cellVoltages,
      NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamCellVoltages
      Description:

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

      Input Parameters:
      NSArray<NSNumber *> *_Nullable cellVoltagesArray of battery cell voltages. For example, the Inspire 1 has a 6 cell battery and therefore will have a 6 element array.
      NSError *_Nullable errorError retrieving the value.
      void (^_Nonnull)(NSArray<NSNumber *> *_Nullable cellVoltages, NSError *_Nullable error) completionAsynchronous execution result block.
      Number
      property
      property numberOfCells
      @property(nonatomic, readonly) NSUInteger numberOfCells
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamNumberOfCells
      Description:

      Returns the number of battery cells.

      method setNumberOfCells:withCompletion
      - (void)setNumberOfCells:(NSUInteger)numberOfCells withCompletion:(DJICompletionBlock)completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamNumberOfCells
      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:
      NSUInteger numberOfCellsNumber of cells inside the battery.
      DJICompletionBlock completionAsynchronous execution result block.


      Information

      Smart Battery
      method
      method isSmartBattery
      - (BOOL)isSmartBattery
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamIsSmartBattery
      Description:

      YES 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:
      BOOL<code>Yes</code>> if battery is smart battery.
      Pair Batteries
      method
      method pairBatteriesWithCompletion
      - (void)pairBatteriesWithCompletion:(DJICompletionBlock)completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamPairBatteries
      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. getPairingStateWithCompletion can then be used to determine if the installed battery combination is a previously assigned pair or not. Batteries can be repaired.

      Input Parameters:
      DJICompletionBlock completionCompletion block that receives the execution result.
      method getPairingStateWithCompletion
      - (void)getPairingStateWithCompletion:(void (^_Nonnull)(DJIBatteryPairingState pairingState, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamPairState
      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:
      void (^_Nonnull)(DJIBatteryPairingState pairingState, NSError *_Nullable error) completionBlock that receives the pairing state.
      DJIBatteryPairingState pairingStatePairing state.
      NSError *_Nullable errorError retrieving the value.


      Behavior at Thresholds

      method setLevel1CellVoltageThreshold:withCompletion
      - (void)setLevel1CellVoltageThreshold:(NSUInteger)voltage withCompletion:(DJICompletionBlock)completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel1CellVoltageThreshold
      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:
      NSUInteger voltageLevel 1 cell voltage threshold to set in mV.
      DJICompletionBlock completionCompletion block that receives the setter execution result.
      method getLevel1CellVoltageThresholdWithCompletion
      - (void)getLevel1CellVoltageThresholdWithCompletion:(void (^_Nonnull)(NSUInteger voltage, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel1CellVoltageThreshold
      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:
      void (^_Nonnull)(NSUInteger voltage, NSError *_Nullable error) completionAsynchronous execution result block that contains the voltage threshold.
      NSUInteger voltageVoltage in mV
      NSError *_Nullable errorError retrieving the value.
      method setLevel2CellVoltageThreshold:withCompletion
      - (void)setLevel2CellVoltageThreshold:(NSUInteger)voltage withCompletion:(DJICompletionBlock)completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel2CellVoltageThreshold
      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:
      NSUInteger voltageLevel 2 cell voltage threshold to set in mV.
      DJICompletionBlock completionAsynchronous execution result block.
      method getLevel2CellVoltageThresholdWithCompletion
      - (void)getLevel2CellVoltageThresholdWithCompletion:(void (^_Nonnull)(NSUInteger voltage, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel2CellVoltageThreshold
      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:
      void (^_Nonnull)(NSUInteger voltage, NSError *_Nullable error) completionAsynchronous execution result block that contains the voltage threshold.
      NSUInteger voltageVoltage in mV
      NSError *_Nullable errorError retrieving the value.
      method setLevel1CellVoltageBehavior:withCompletion
      - (void)setLevel1CellVoltageBehavior:(DJIBatteryLowVoltageBehavior)behavior
      withCompletion:(DJICompletionBlock)completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel1CellVoltageBehavior
      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:
      DJIBatteryLowVoltageBehavior behaviorLevel 1 behavior.
      DJICompletionBlock completionCompletion block that receives the setter execution result.
      method getLevel1CellVoltageBehaviorWithCompletion
      - (void)getLevel1CellVoltageBehaviorWithCompletion:(void (^_Nonnull)(DJIBatteryLowVoltageBehavior behavior, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel1CellVoltageBehavior
      Description:

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

      Input Parameters:
      void (^_Nonnull)(DJIBatteryLowVoltageBehavior behavior, NSError *_Nullable error) completionAsynchronous execution result block that contains the voltage threshold behavior.
      DJIBatteryLowVoltageBehavior behaviorAircraft behavior when voltage threshold is crossed.
      NSError *_Nullable errorError retrieving the value.
      method setLevel2CellVoltageBehavior:withCompletion
      - (void)setLevel2CellVoltageBehavior:(DJIBatteryLowVoltageBehavior)behavior
      withCompletion:(DJICompletionBlock)completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel2CellVoltageBehavior
      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:
      DJIBatteryLowVoltageBehavior behaviorLevel 2 behavior.
      DJICompletionBlock completionAsynchronous execution result block.
      method getLevel2CellVoltageBehaviorWithCompletion
      - (void)getLevel2CellVoltageBehaviorWithCompletion:(void (^_Nonnull)(DJIBatteryLowVoltageBehavior behavior, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel2CellVoltageBehavior
      Description:

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

      Input Parameters:
      void (^_Nonnull)(DJIBatteryLowVoltageBehavior behavior, NSError *_Nullable error) completionAsynchronous execution result block that contains the voltage threshold behavior.
      DJIBatteryLowVoltageBehavior behaviorAircraft behavior when voltage threshold is crossed.
      NSError *_Nullable errorError retrieving the value.


      Warning Records

      method getLatestWarningRecordWithCompletion
      - (void)getLatestWarningRecordWithCompletion:(void (^_Nonnull)(DJIBatteryWarningRecord *_Nullable record, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLatestWarningRecord
      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:
      void (^_Nonnull)(DJIBatteryWarningRecord *_Nullable record, NSError *_Nullable error) completionAsynchronous execution result block that contains the latest warning record.
      DJIBatteryWarningRecord *_Nullable recordWarning record.
      NSError *_Nullable errorError retrieving the value.
      method getWarningRecordsWithCompletion
      - (void)getWarningRecordsWithCompletion:(void (^_Nonnull)(NSArray<DJIBatteryWarningRecord *> *_Nullable records, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamWarningInformationRecords
      Description:

      Gets the battery's history, which is kept for 30 days. The 'records' variable in the block stores objects of type DJIBatteryWarningRecord.

      Input Parameters:
      NSArray<DJIBatteryWarningRecord *> *_Nullable recordsWarning records.
      NSError *_Nullable errorError retrieving the value.
      void (^_Nonnull)(NSArray<DJIBatteryWarningRecord *> *_Nullable records, NSError *_Nullable error) completionRemote execution result callback block.


      Discharge

      method setSelfDischargeInDays:withCompletion
      - (void)setSelfDischargeInDays:(uint8_t)days withCompletion:(DJICompletionBlock)completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamSelfDischargeInDays
      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:
      uint8_t daysDay for self-discharge
      DJICompletionBlock completionAsynchronous execution result block.
      method getSelfDischargeInDaysWithCompletion
      - (void)getSelfDischargeInDaysWithCompletion:(void (^_Nonnull)(uint8_t days, NSError *_Nullable error))completion
      Header:DJIBattery.h
      SDK Key:DJIBatteryKey.DJIBatteryParamSelfDischargeInDays
      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:
      void (^_Nonnull)(uint8_t days, NSError *_Nullable error) completionAsynchronous execution result block that contains the number of days to discharge over.
      uint8_t daysNumber of days to discharge over.
      NSError *_Nullable errorError retrieving the value.


      Delegate
      protocol
      protocol DJIBatteryDelegate
      @protocol DJIBatteryDelegate <NSObject>
      Header:DJIBattery.h
      Inherits From:NSObject
      Description:

      This protocol provides a delegate method to update the battery's current state.

      Protocol Methods:

      Protocol Method

      method battery:didUpdateState
      @optional
      - (void)battery:(DJIBattery *_Nonnull)battery didUpdateState:(DJIBatteryState *_Nonnull)state
      Header:DJIBattery.h
      Description:

      Delegate to update battery state.

      Input Parameters:
      DJIBattery *_Nonnull batteryBattery having an updated state.
      DJIBatteryState *_Nonnull stateThe battery's state.
      protocol DJIBatteryAggregationDelegate
      @protocol DJIBatteryAggregationDelegate <NSObject>
      Header:DJIBattery.h
      Inherits From:NSObject
      Description:

      This protocol provides a delegate method to update the current aggregated battery state.

      Protocol Methods:

      Protocol Method

      method batteriesDidUpdateState
      @optional
      - (void)batteriesDidUpdateState:(DJIBatteryAggregationState *_Nonnull)state
      Header:DJIBattery.h
      Description:

      Callback to update aggregated battery state.

      Input Parameters:
      DJIBatteryAggregationState *_Nonnull stateThe aggregated battery state.
      General
      class
      enum DJIBatteryLowVoltageBehavior
      typedef NS_ENUM (uint8_t, DJIBatteryLowVoltageBehavior)
      Header:DJIBatteryState.h
      SDK Key:DJIBatteryKey.DJIBatteryParamLevel1CellVoltageBehavior, DJIBatteryKey.DJIBatteryParamLevel2CellVoltageBehavior
      Description:

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

      Enum Members:
      DJIBatteryLowVoltageBehaviorFlashLEDLED lights go into warning mode.
      DJIBatteryLowVoltageBehaviorGoHomeReturn-to-Home.
      DJIBatteryLowVoltageBehaviorLandLand aircraft immediately.
      DJIBatteryLowVoltageBehaviorUnknownUnknown.
      enum DJIBatteryPairingState
      typedef NS_ENUM (uint8_t, DJIBatteryPairingState)
      Header:DJIBatteryState.h
      SDK Key:DJIBatteryKey.DJIBatteryParamPairState
      Description:

      Battery pairing state for batteries that can be paired.

      Enum Members:
      DJIBatteryPairingStateUnpairedThe batteries didn't match; they're not paired.
      DJIBatteryPairingStatePairedBatteries are paired.
      DJIBatteryPairingStateUnknownCan't get the pair state or the batteries.
      enum DJIBatterySelfHeatingState
      typedef NS_ENUM (uint8_t, DJIBatterySelfHeatingState)
      Header:DJIBatteryState.h
      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:
      DJIBatterySelfHeatingStateIdleThe auto heating feature is idle.
      DJIBatterySelfHeatingStateWarmingUpThe battery is warming itself up automatically.
      DJIBatterySelfHeatingStatePreservingThe battery is preserving its temperature. For Mavic 2 Enterprise, the temperature will be maintained between 6 Celsius degrees and 8 Celsius degrees.
      DJIBatterySelfHeatingStateUnknownUnknown.