public class

GroundSdk

extends Object

 java.lang.Object

↳com.parrot.drone.groundsdk.GroundSdk

Subclasses:

ManagedGroundSdk

Overview

Core ground SDK access class.

This class provides the main entry-point API of GroundSdk allowing to retrieve and manage devices (drones and/or remote controls)

A GroundSdk instance also represents a session through which GroundSdk API can be used. Such a session has a lifecycle that MUST be properly managed by the application.
A session has mainly two purposes:

  • It allows GroundSdk to start its underlying engines as soon as the first session is requested by the application and to close them when the last session is closed by the application.
  • It keeps track of all the observers that the application may register using GroundSdk APIs in order to unregister them automatically when the session closes. It also provides the application a way to suspend or resume all those registered observers so that it can receive change notifications only when appropriate depending on its own lifecycle.

The following methods form, together, the session management API: newSession, resume, suspend, retain and finally close.

newSession method allows the application to create a new session. Every call to this method leads to the creation of a new session that MUST be closed by the application at some point.
A new session is always implicitly linked to an android Context (an Activity, a Service or an Application), that must be provided when the session is requested.
This context is tied to the session lifecycle; as a consequence, a session MUST NEVER outlive its associated context. In other words, method GroundSdk.close() must be called before the associated context disappears.
Failure to do so will result in a session leak, and GroundSdk won't be able to stop its underlying engines when necessary, which in turn will keep the application process running, draining battery and possibly using network.
Optionally, the application may provide an android Bundle containing retained session information in order to 'restore' a retained session. See below.

A new GroundSdk session is always created in a so-called 'suspended' state: any observer that the application may register with this session through any GroundSdk API will not forward any change notification to the application while the session remains in this state.
The application must call the GroundSdk.resume() method to allow observers to forward change notifications, and may call GroundSdk.suspend() method in order to get back to the suspended state, to stop receiving change notifications.

retain method allows the application to temporarily persist a session before it is closed in order to restore it at a later time: when one or more sessions are retained, GroundSdk won't stop its underlying engines, even if all sessions (including the retained ones) are closed.
To retain a session, the application must provide an Android Bundle where GroundSdk can record internal session info. The application can then later restore the session using GroundSdk.newSession(Context, Bundle) method by providing this bundle.
The application needs to be careful that a retained session MUST always be restored at some point. Failure to do so will result in a session leak, and GroundSdk won't be able to stop its underlying engines when necessary, which in turn will keep the application process running, draining battery and possibly using network.
Note that the session will be restored in a 'suspended' state, as if it was a new session, and all lifecycle recommendations presented above apply.

Below are given several recommendations to use a GroundSdk session tied to an android Activity:

For example:

  public class MyGroundSdkActivity extends Activity {
      private GroundSdk mGroundSdk;

      @Override
      public void onCreate(@Nullable Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          mGroundSdk = GroundSdk.newSession(this, savedInstanceState);
      }

      @Override
      public void onStart() {
          super.onStart();
          mGroundSdk.resume();
      }

      @Override
      public void onStop() {
          mGroundSdk.suspend();
          super.onStop();
      }

      @Override
      public void onSaveInstanceState(@NonNull Bundle outState) {
          super.onSaveInstanceState(outState);
          if (isChangingConfigurations()) {
              mGroundSdk.retain(outState);
          }
      }

      @Override
      public void onDestroy() {
          mGroundSdk.close();
          super.onDestroy();
      }
  }
 
GroundSdk also provides automatic session lifecycle management in correlation with an Activity lifecycle, please refer to ManagedGroundSdk documentation for further information.

Summary

Methods
public voidclose()

Closes this session.

public final booleanconnectDrone(String uid)

Connects a drone identified by its uid.

public final booleanconnectDrone(String uid, DeviceConnector connector)

Connects a drone identified by its uid using a specific connector.

public final booleanconnectDrone(String uid, DeviceConnector connector, String password)

Connects a secured drone identified by its uid.

public final booleanconnectRemoteControl(String uid)

Connects a remote control identified by its uid.

public final booleanconnectRemoteControl(String uid, DeviceConnector connector)

Connects a remote control identified by its uid using a specific connector.

public final booleanconnectRemoteControl(String uid, DeviceConnector connector, String password)

Connects a remote control identified by its uid.

public final booleandisconnectDrone(String uid)

Disconnects a drone identified by its uid.

public final booleandisconnectRemoteControl(String uid)

Disconnects a remote control identified by its uid.

public final booleanforgetDrone(String uid)

Forgets a drone identified by its uid.

public final booleanforgetRemoteControl(String uid)

Forgets a remote control identified by its uid.

public final DronegetDrone(String uid)

Gets a drone by uid.

public final DronegetDrone(String uid, GroundSdk.OnDeviceRemovedListener listener)

Gets a drone by uid.

public final Ref<List>getDroneList(Predicate<DroneListEntry> filter, Ref.Observer<List> observer)

Gets a list of known drones and registers an observer notified each time this list changes.

public final FacilitygetFacility(Class<Facility> facilityClass)

Retrieves a facility.

public final Ref<Facility>getFacility(Class<Facility> facilityClass, Ref.Observer<Facility> observer)

Retrieves a facility and registers an observer notified each time it changes.

public final RemoteControlgetRemoteControl(String uid)

Gets a remote control by uid.

public final RemoteControlgetRemoteControl(String uid, GroundSdk.OnDeviceRemovedListener listener)

Gets a remote control by uid.

public final Ref<List>getRemoteControlList(Predicate<RemoteControlListEntry> filter, Ref.Observer<List> observer)

Gets a list of known remote controls and registers an observer notified each time this list changes.

public static voidmanageRcAccessory(Context context, UsbAccessory rcAccessory)

Commands GroundSDK to manage the given remote controller USB accessory.

public static GroundSdknewSession(Context context, Bundle savedInstanceState)

Obtains a new GroundSdk session instance.

public final Ref<FileReplay>replay(FileReplay.Source source, Ref.Observer<FileReplay> observer)

Creates a new replay stream for some local media file.

public voidresume()

Resumes this session.

public voidretain(Bundle outState)

Retains this session.

public voidsuspend()

Suspends this session.

from Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods

public static GroundSdk newSession(Context context, Bundle savedInstanceState)

Obtains a new GroundSdk session instance.

Parameters:

context: the android context to tie with the session
savedInstanceState: a bundle containing a retained session info to be restored, otherwise null

Returns:

a new GroundsSdk session

public void resume()

Resumes this session.

All registered observers may now notify changes to the application, and may do so immediately in case any observed component did change while the session was suspended.

See also: GroundSdk.suspend()

public void suspend()

Suspends this session.

All registered observers are not allowed to notify changes to the application until GroundSdk.resume() is called.

See also: GroundSdk.resume()

public void retain(Bundle outState)

Retains this session.

Parameters:

outState: android-provided bundle where session information will be stored temporarily

public void close()

Closes this session.

All registered observers are disposed. Session must not be used anymore after this method is called.

public final Ref<List> getDroneList(Predicate<DroneListEntry> filter, Ref.Observer<List> observer)

Gets a list of known drones and registers an observer notified each time this list changes.

Parameters:

filter: filter to select drones to include into the returned list. The filter criteria must not change during the list reference lifecycle.
observer: observer notified each time this list changes

Returns:

a reference to the requested list

public final Ref<List> getRemoteControlList(Predicate<RemoteControlListEntry> filter, Ref.Observer<List> observer)

Gets a list of known remote controls and registers an observer notified each time this list changes.

Parameters:

filter: filter to select remote controls to include into the returned list. The filter criteria must not change during the list reference lifecycle.
observer: observer notified each time this list changes

Returns:

a reference to the requested list

public final Drone getDrone(String uid)

Gets a drone by uid.

Parameters:

uid: uid of the requested drone

Returns:

the drone with the requested uid, or null if there is no drone with such uid

public final RemoteControl getRemoteControl(String uid)

Gets a remote control by uid.

Parameters:

uid: uid of the requested remote control

Returns:

the remote control with the requested uid, or null if there is no remote control with such uid

public final Drone getDrone(String uid, GroundSdk.OnDeviceRemovedListener listener)

Gets a drone by uid.

Parameters:

uid: uid of the requested drone
listener: called back when the requested drone disappears. Never called if the requested drone does not exist (i.e. when this method returns null).

Returns:

the drone with the requested uid, or null if there is no drone with such uid

public final RemoteControl getRemoteControl(String uid, GroundSdk.OnDeviceRemovedListener listener)

Gets a remote control by uid.

Parameters:

uid: uid of the requested remote control
listener: called back when the requested remote control disappears. Never called if the requested remote control does not exist (i.e. when this method returns null).

Returns:

the remote control with the requested uid, or null if there is no remote control with such uid

public final boolean connectDrone(String uid)

Connects a drone identified by its uid.

Connects the drone with the best available connector, chosen as follows:

  • If there is only one available connector, then it is used to connect the drone. Otherwise,
  • if there is only one available , then it is used to connect the drone.
If none of the aforementioned condition holds, then the connection fails and false is returned.
GroundSdk.connectDrone(String, DeviceConnector) method shall be used to select an appropriate connector instead.

Parameters:

uid: uid of the drone to connect

Returns:

true if the connection process has started, otherwise false, for example if the drone is not visible anymore

public final boolean connectDrone(String uid, DeviceConnector connector)

Connects a drone identified by its uid using a specific connector.

Parameters:

uid: uid of the drone to connect
connector: the connector through which to establish the connection

Returns:

true if the connection process has started, otherwise false, for example if the drone is not visible anymore

public final boolean connectDrone(String uid, DeviceConnector connector, String password)

Connects a secured drone identified by its uid.

Parameters:

uid: uid of the drone to connect
connector: the connector through which to establish the connection
password: password to use for authentication

Returns:

true if the connection process has started, otherwise false, for example if the drone is not visible anymore

public final boolean connectRemoteControl(String uid)

Connects a remote control identified by its uid.

Connects the remote control with the best available connector, chosen as follows:

  • If there is only one available connector, then it is used to connect the remote control. Otherwise,
  • if there is only one available connector (note that there can be two of those in case both the device USB and the USB Debug Bridge are used), then it is used to connect the remote control.
If none of the aforementioned condition holds, then the connection fails and false is returned.
GroundSdk.connectRemoteControl(String, DeviceConnector) method shall be used to select an appropriate connector instead.

Parameters:

uid: uid of the remote control to connect

Returns:

true if the connection process has started, otherwise false, for example if the remote control is not visible anymore

public final boolean connectRemoteControl(String uid, DeviceConnector connector)

Connects a remote control identified by its uid using a specific connector.

Parameters:

uid: uid of the remote control to connect
connector: the connector through which to establish the connection

Returns:

true if the connection process has started, otherwise false, for example if the remote control is not visible anymore

public final boolean connectRemoteControl(String uid, DeviceConnector connector, String password)

Connects a remote control identified by its uid.

Parameters:

uid: uid of the remote control to connect
connector: the connector through which to establish the connection
password: password to use for authentication

Returns:

true if the connection process has started, otherwise false, for example if the remote control is not visible anymore

public final boolean disconnectDrone(String uid)

Disconnects a drone identified by its uid.

This method can be used to disconnect the drone when connected or to cancel the connection process if the drone is currently connecting.

Parameters:

uid: uid of the drone to disconnect

Returns:

true if the disconnection process has started, otherwise false

public final boolean disconnectRemoteControl(String uid)

Disconnects a remote control identified by its uid.

This method can be used to disconnect the remote control when connected or to cancel the connection process if the remote control is currently connecting.

Parameters:

uid: uid of the remote control to disconnect

Returns:

true if the disconnection process has started, otherwise false

public final boolean forgetDrone(String uid)

Forgets a drone identified by its uid.

Persisted drone data are deleted and the drone is removed if it is not currently visible.

Parameters:

uid: uid of the drone to forget

Returns:

true if the drone has been forgotten, otherwise false

public final boolean forgetRemoteControl(String uid)

Forgets a remote control identified by its uid.

Persisted remote control data are deleted and the remote control is removed if it is not currently visible.

Parameters:

uid: uid of the remote control to forget

Returns:

true if the remote control has been forgotten, otherwise false

public final Facility getFacility(Class<Facility> facilityClass)

Retrieves a facility.

Parameters:

facilityClass: class of the facility

Returns:

requested facility, or null if it's not present

public final Ref<Facility> getFacility(Class<Facility> facilityClass, Ref.Observer<Facility> observer)

Retrieves a facility and registers an observer notified each time it changes.

Parameters:

facilityClass: class of the facility
observer: observer to notify when the facility changes

Returns:

reference to the requested facility

public final Ref<FileReplay> replay(FileReplay.Source source, Ref.Observer<FileReplay> observer)

Creates a new replay stream for some local media file.

Every call to this method creates a new replay stream instance for the given local file, that must be disposed by closing the returned reference once that stream is not needed.

Closing the returned reference automatically stops the referenced replay stream.

Parameters:

source: identifies local source stream
observer: observer notified when the stream state changes

Returns:

a reference onto a new replay stream for the given file

public static void manageRcAccessory(Context context, UsbAccessory rcAccessory)

Commands GroundSDK to manage the given remote controller USB accessory.

Client application is responsible to obtain the USB accessory in question using the appropriate Android API and also to request proper permission to use the latter from Android SDK.
This is usually done using an activity registered with the ACTION_USB_ACCESSORY_ATTACHED intent action filter.
Please refer to Android USB accessory guide for further documentation.

Parameters:

context: an android context
rcAccessory: android USB RC accessory to manage