Interface FollowMePilotingItf

  • All Superinterfaces:
    Activable, PilotingItf

    public interface FollowMePilotingItf
    extends PilotingItf, Activable
    Piloting interface used to make the drone follow some (possibly moving) target.

    Availability

    This interface will be unavailable until a specific set of conditions are met:

    • the drone must be flying,
    • the drone must be properly calibrated,
    • the drone must have sufficient GPS location information,
    • the drone must be sufficiently far above the ground,
    • the drone must be sufficiently far away from the target,
    • the application must provide sufficient information to the drone so that it can identify and track the target (see Target selection for further information on how to provide target tracking information.)
    All unsatisfied conditions are reported by this interface, when unavailable, so that the application can inform the user and take appropriate measures to satisfy those conditions as appropriate. Once all conditions are satisfied, then the interface will become available and can be activated so that the drone starts following the target.

    Note that this interface, even while available or active may become unavailable back again, as soon as any of those conditions is not satisfied anymore.

    Mode

    This interface supports different modes of operation. This may be configured through the mode setting, regardless of interface availability. Mode changes will be applied immediately in case the interface is currently active, without the need to activate it again.
    Note also that this setting is not persisted.

    Alerts and behavior

    When available or active, this interface may also alert about specific conditions that hinders optimally accurate tracking of the target, although tracking remains feasible under such conditions:

    • TODO : refine and list exactly which cases can be forwarded as an 'alert' from the drone.
    The application may use such alerts to inform the user and take appropriate measures to improve tracking performance.

    This interface will also report when such conditions actually force the drone to adopt a downgraded behavior. For example, some conditions may force the drone to remain only stationary instead of following the target when it moves.

    Movement

    When this interface is active, the drone will fly autonomously to follow the moving target as the current mode permits it, unless manually instructed to move using this interface's setPitch(int), setRoll(int) or setVerticalSpeed(int) piloting commands.
    In any case, the drone will always try to follow the target and may thus move independently of the provided piloting commands to do so.

    Target selection

    In order for this interface to be available, the application must instruct the drone how to identify and track the desired target. To do so, the TargetTracker peripheral must be used.

    Using this peripheral, the application may:

    • Require controller (remote control, or user device) barometer and location information to be sent regularly to the drone. In case sent information is sufficiently accurate, it may be sufficient to allow the drone to track the controller, in which case, provided other requirements are satisfied, the interface will become available and, when active, will make the drone follow the controller.
    • Provide external information about where the desired target is located, its direction and current movement. Such information may for example come from results of image processing applied to the drone video stream. In case sent information is sufficiently accurate and coherent, it may be sufficient to allow the drone to track the desired target, in which case, provided other requirements are satisfied, the interface will become available and, when active, will make the drone follow the desired target.

    Note that both controller barometer/location information and external target information may be sent to the drone at the same time, provided they give coherent positioning information on the SAME target.
    For instance, it is possible to perform image processing on the drone video stream to identify the controller and send the results to the drone, along with controller barometer/location updates, for better tracking performance.
    However, care must be taken not to provide incoherent information, such as forwarding controller/barometer location and, as the same time, external information on a different target than the controller; behavior is undefined in such a case.

    This piloting interface can be obtained from a drone using:

    drone.getPilotingItf(FollowMePilotingItf.class)
    See Also:
    PilotingItf.Provider.getPilotingItf(Class), PilotingItf.Provider.getPilotingItf(Class, Ref.Observer)
    • Method Detail

      • mode

        @NonNull
        EnumSetting<FollowMePilotingItf.Mode> mode()
        Gives access to the operating mode setting.

        This setting allows to select the operating mode of this interface.

        Returns:
        operating mode setting
      • activate

        boolean activate()
        Activates this piloting interface.

        If successful, the currently active piloting interface (if any) is deactivated and this one is activated.

        Returns:
        true on success, false in case the piloting interface cannot be activated at this point
      • getAvailabilityIssues

        @NonNull
        EnumSet<TrackingIssue> getAvailabilityIssues()
        Tells why this piloting interface is currently be unavailable.

        The returned set may contain values only if the interface is unavailable.

        Returns:
        the set of reasons that preclude this piloting interface from being available at present
      • getQualityIssues

        @NonNull
        EnumSet<TrackingIssue> getQualityIssues()
        Alerts about issues that currently hinders optimal behavior of this interface.

        The returned set may contain values only if the interface is not Activable.State.UNAVAILABLE.

        Returns:
        a set of issues that hinders optimal behavior of this interface
      • setPitch

        void setPitch​(int pitch)
        Sets the current pitch value.

        The drone tries to both conform to the requested pitch command and keep directed towards the target.

        value is expressed as a signed percentage of the max pitch/roll setting, in range [-100, 100].
        -100 corresponds to a pitch angle of max pitch/roll towards ground (drone will fly forward), 100 corresponds to a pitch angle of max pitch/roll towards sky (copter will fly backward).

        Note: value may be clamped if necessary, in order to respect the maximum supported physical tilt of the copter.

        Parameters:
        pitch - the new pitch value to set
      • setRoll

        void setRoll​(int roll)
        Sets the current roll value.

        The drone tries to both conform to the requested roll command and keep directed towards the target.

        value is expressed as a signed percentage of the max pitch/roll setting, in range [-100, 100].
        -100 corresponds to a roll angle of max pitch/roll to the left (copter will fly left), 100 corresponds to a roll angle of max pitch/roll to the right (copter will fly right).

        Note: value may be clamped if necessary, in order to respect the maximum supported physical tilt of the copter.

        Parameters:
        roll - the new pitch roll to set
        See Also:
        ManualCopterPilotingItf.getMaxPitchRoll()
      • setVerticalSpeed

        void setVerticalSpeed​(int verticalSpeed)
        Set the current vertical speed value.

        The drone tries to both conform to the requested vertical speed command and keep directed towards the target.

        value is expressed as as a signed percentage of the max vertical speed setting, in range [-100, 100].
        -100 corresponds to max vertical speed towards ground,100 corresponds to max vertical speed towards sky.

        Parameters:
        verticalSpeed - the new vertical speed value to set
        See Also:
        ManualCopterPilotingItf.getMaxVerticalSpeed()