GroundSdk

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 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 onCreate method, passing the android-provided savedInstanceState Bundle, and to close it in onDestroy method.
• Resume the session in onStart and suspend it in onStop.
• Alternatively, resume the session in onResume and suspend it in onPause.
• Retain the session in 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();
     }
 }