Class GroundSdk

  • Direct Known Subclasses:
    ManagedGroundSdk

    public class GroundSdk
    extends Object
    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 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 resume() method to allow observers to forward change notifications, and may call 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 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:

    • Create the session in activity onCreate() method, passing the android-provided savedInstanceState Bundle, and to close it in activity onDestroy() method.
    • Resume the session in activity onStart() and suspend it in activity onStop().
    • Alternatively, resume the session in activity onResume() and suspend it in activity onPause().
    • Retain the session in activity onSaveInstanceState() method, if (and only if) there is a pending configuration change.

    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.
    • Method Detail

      • newSession

        @NonNull
        public static GroundSdk newSession​(@NonNull
                                           Context context,
                                           @Nullable
                                           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
      • resume

        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:
        suspend()
      • suspend

        public void suspend()
        Suspends this session.

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

        See Also:
        resume()
      • retain

        public void retain​(@NonNull
                           Bundle outState)
        Retains this session.
        Parameters:
        outState - android-provided bundle where session information will be stored temporarily
      • close

        public void close()
        Closes this session.

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

      • getDroneList

        @NonNull
        public final Ref<List<DroneListEntry>> getDroneList​(@NonNull
                                                            Predicate<DroneListEntry> filter,
                                                            @NonNull
                                                            Ref.Observer<List<DroneListEntry>> 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
      • getRemoteControlList

        @NonNull
        public final Ref<List<RemoteControlListEntry>> getRemoteControlList​(@NonNull
                                                                            Predicate<RemoteControlListEntry> filter,
                                                                            @NonNull
                                                                            Ref.Observer<List<RemoteControlListEntry>> 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
      • getDrone

        @Nullable
        public final Drone getDrone​(@NonNull
                                    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
      • getRemoteControl

        @Nullable
        public final RemoteControl getRemoteControl​(@NonNull
                                                    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
      • getDrone

        @Nullable
        public final Drone getDrone​(@NonNull
                                    String uid,
                                    @NonNull
                                    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
      • getRemoteControl

        @Nullable
        public final RemoteControl getRemoteControl​(@NonNull
                                                    String uid,
                                                    @NonNull
                                                    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
      • connectDrone

        public final boolean connectDrone​(@NonNull
                                          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 remote control connector, then it is used to connect the drone.
        If none of the aforementioned condition holds, then the connection fails and false is returned.
        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
      • connectDrone

        public final boolean connectDrone​(@NonNull
                                          String uid,
                                          @NonNull
                                          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
      • connectDrone

        public final boolean connectDrone​(@NonNull
                                          String uid,
                                          @NonNull
                                          DeviceConnector connector,
                                          @NonNull
                                          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
      • connectRemoteControl

        public final boolean connectRemoteControl​(@NonNull
                                                  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 USB 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.
        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
      • connectRemoteControl

        public final boolean connectRemoteControl​(@NonNull
                                                  String uid,
                                                  @NonNull
                                                  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
      • connectRemoteControl

        public final boolean connectRemoteControl​(@NonNull
                                                  String uid,
                                                  @NonNull
                                                  DeviceConnector connector,
                                                  @NonNull
                                                  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
      • disconnectDrone

        public final boolean disconnectDrone​(@NonNull
                                             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
      • disconnectRemoteControl

        public final boolean disconnectRemoteControl​(@NonNull
                                                     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
      • forgetDrone

        public final boolean forgetDrone​(@NonNull
                                         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
      • forgetRemoteControl

        public final boolean forgetRemoteControl​(@NonNull
                                                 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
      • getFacility

        @Nullable
        public final <F extends Facility> F getFacility​(@NonNull
                                                        Class<F> facilityClass)
        Retrieves a facility.
        Type Parameters:
        F - type of the facility class
        Parameters:
        facilityClass - class of the facility
        Returns:
        requested facility, or null if it's not present
      • getFacility

        @NonNull
        public final <F extends FacilityRef<F> getFacility​(@NonNull
                                                             Class<F> facilityClass,
                                                             @NonNull
                                                             Ref.Observer<F> observer)
        Retrieves a facility and registers an observer notified each time it changes.
        Type Parameters:
        F - type of the facility class
        Parameters:
        facilityClass - class of the facility
        observer - observer to notify when the facility changes
        Returns:
        reference to the requested facility
      • replay

        @NonNull
        public final Ref<FileReplay> replay​(@NonNull
                                            FileReplay.Source source,
                                            @NonNull
                                            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
      • manageRcAccessory

        public static void manageRcAccessory​(@NonNull
                                             Context context,
                                             @NonNull
                                             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 UsbManager.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