Use the Mobile API Android package

- the API files were removed from the repo, they are now distributed as an Android package from the GitHub Gradle registry, this repo now only contains the example app
- the GitHub Gradle registry requires authentication, the setup is documented in the README file
- the API documentation and sources are distributed in the package
- the API documentation is also available on GitHub Pages: https://clariusdev.github.io/mobileapi/reference/9.4.0/
- added "sdk" in the package name: me.clarius.sdk.mobileapi

Author: julien-l

.gitignore

@@ -2,6 +2,7 @@
 .gradle
 .idea
 /local.properties
+/secrets.properties
 .DS_Store
 /build
 /captures

CHANGELOG.md

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+# 9.4.0
+
+Changed:
+- The Mobile API is now distributed as an Android Package in the GitHub Gradle registry.
+- Renamed package from `me.clarius.mobileapi` to `me.clarius.sdk.mobileapi`.
+
 # 9.3.0
 
 Fixed:

README.md

@@ -14,15 +14,41 @@ It also supports sending user commands such as changing the imaging depth or tak
 Note: Virtual scanners are supported without a license since version 8.0.1.
 
 
-# Quickstart
+# SDK reference
+
+https://clariusdev.github.io/mobileapi/reference/9.4.0
+
+
+# Get the package
+
+Starting with Clarius App version 9.4.0, the Mobile API is distributed as an Android package.
+The package is hosted in the GitHub Gradle registry which requires authentication (a GitHub account is needed).
+
+1. Generate a GitHub Personal Access Token (PAT) with the `read:packages` scope.
+Refer to the [GitHub documentation][github-pat] for instructions to generate tokens.
+
+1. Create a file `secrets.properties` in the project's root folder (which will be read by the Gradle build script) with the following content:
+
+        // file /secrets.properties
+        // do not put quotes (') around the values 
+        gpr.user=your_user_name
+        gpr.token=personal_access_token_with_read_packages_scope
+
+3. Alternatively, if the secrets file is missing, the build script will attempt to read the environment variables `GITHUB_ACTOR` and `GITHUB_TOKEN`.
+
+[github-pat]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+[github-gradle]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#using-a-published-package
+
+
+# Quick start
 
 1. On your Android device, start the Clarius App and connect to your scanner.
 
-2. Open this project in Android Studio, select the Quickstart App and run it on your Android device.
+2. Open this project in Android Studio and run the example application on your Android device.
 
-3. Optional: run both apps in split screen, otherwise let the Clarius App run in the background.
+3. Optional: run both applications in split screen, otherwise let the Clarius App run in the background.
 
-4. In the Quickstart App, select Menu `⋮` > `connect` to start receiving images.
+4. In the example application, select Menu `⋮` > `connect` to start receiving images.
 
 <img height="450px" alt="connection menu" src="images/quickstart_connect.png"/>
 
@@ -34,7 +60,7 @@ Usage:
 
 * Menu `⋮` > `Ask *`: obtain imaging information, like the current depth or gain.
 
-* Menu `⋮` > `settings`: configure the image sent over the Mobile API (this is the image rendered by the Clarius App and transmitted over the Mobile API).
+* Menu `⋮` > `settings`: configure the image rendered by the Clarius App and sent over the API.
 
 
 # Architecture
@@ -63,32 +89,36 @@ The Clarius App takes care of connecting to the probe and pre-processing the ima
                             |                       |
                             +-----------------------+
 
+
 # API Description
 
 On Android, the Mobile API is implemented as an Android _Bound Service_ running in the Clarius App itself.
-Refer to the Android developer guide for details about bound services.
-https://developer.android.com/guide/components/bound-services
+Refer to the [Android developer guide](android-bound-services) for details about bound services.
 
 The interface to the bound service is provided by an Android _Messenger_.
 Android Messengers allow interprocess communications (IPC) by exchanging `Message` objects containing an action code and a payload.
 The sequence of messages and their content constitute the communication protocol which is described below.
 
+[android-bound-services]: https://developer.android.com/guide/components/bound-services
+
 
 # Protocol
 
-1. The client binds to the service by calling `Context.bindService()` and receives the server's `IBinder`. This `IBinder` is used to create a Messenger that can send messages _to the server_.
-2. The client sends its own Messenger to the server in the `replyTo` field of a `Message` object with code `MSG_REGISTER_CLIENT`. This Messenger is used by the server to send messages _to the client_.
+1. The client binds to the service by calling `Context.bindService()` and receives the server's `IBinder`.
+This `IBinder` is used to create a Messenger that can send messages _to the server_.
+2. The client sends its own Messenger to the server in the `replyTo` field of a `Message` object with code `MSG_REGISTER_CLIENT`.
+This Messenger is used by the server to send messages _to the client_.
 3. The client sends the image configuration to the server (`MSG_CONFIGURE_IMAGE`).
 4. During operation, the server will send the image data to the client (`MSG_NEW_PROCESSED_IMAGE`) and other notable events such as button presses, freeze state, etc.
 5. The client can request the execution of predefined functions such as "increase depth" or "capture image" (`MSG_USER_FN`).
 
-All messages and their associated payload are described in the [MobileApi.java](mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java) file.
+All messages and their associated payload are described in the https://clariusdev.github.io/mobileapi repository.
 
 
 # Licensing
 
 The service operates only when the Clarius App is connected to a scanner with the appropriate license.
-Contact Clarius for details: https://clarius.com/contact/
+Contact Clarius for licensing options: https://clarius.com/contact/.
 
 However, the service accepts binding requests from clients even when no proper license is active to accommodate workflows where the license is removed for legitimate reasons, for example when a probe is disconnected to save battery.
 In this case, the service enters a restricted mode where it stops handling requests and sending updates, but will resume normal operation as soon as a licensed scanner is connected again.
@@ -98,12 +128,13 @@ The license check workflow is as follows:
 1. The client binds to the service
 2. The service starts and accepts the bind request, regardless of the license status
 3. Depending on the current license status:
-    - if active, the service operates normally: all client requests are handled and all updates are sent to the clients;
+    - if active, the service operates normally: all client requests are handled and all updates are sent to the clients
     - if inactive, the service enters restricted mode: no update is sent (except `MSG_LICENSE_UPDATE`) and no client request is handled (except `MSG_REGISTER_CLIENT` and `MSG_UNREGISTER_CLIENT`). The service will reply `MSG_NO_LICENSE` to any other request
 4. If the license status changes during operation, the service sends `MSG_LICENSE_UPDATE` and changes its mode of operation:
     - if the license becomes inactive: the service clears the image configuration and enter restricted mode
     - if the license becomes active: the service resumes normal operations, but the client must re-send the image configuration
 
+
 # Raw Data
 
 Workflow to obtain raw data:
@@ -115,7 +146,9 @@ Workflow to obtain raw data:
     - notify the client with `MSG_RAW_DATA_AVAILABLE`
 3. In the client, send `MSG_COPY_RAW_DATA` to request a copy, include the following data:
     - the capture's identifier and
-    - and a writable URI where the archive will be written, see https://developer.android.com/training/secure-file-sharing for details
+    - and a writable URI where the archive will be written, refer to the [Android developer guide](android-file-sharing) for details about file sharing
 4. In the client, wait for the reply in message `MSG_RAW_DATA_COPIED`
 
 Note: it is possible to trigger a capture via the Mobile API with `MSG_USER_FN`.
+
+[android-file-sharing]: https://developer.android.com/training/secure-file-sharing

build.gradle

@@ -5,20 +5,31 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:7.0.0'
+        classpath 'com.android.tools.build:gradle:7.2.1'
 
         // NOTE: Do not place your application dependencies here; they belong
         // in the individual module build.gradle files
     }
 }
 
 allprojects {
+    def secrets = new Properties()
+    secrets.load(new FileInputStream(rootProject.file("secrets.properties")))
     repositories {
         google()
         mavenCentral()
+        mavenLocal()
+        maven {
+            name = 'GitHubPackages'
+            url = uri('https://maven.pkg.github.com/clariusdev/mobileapi')
+            credentials {
+                username = secrets['gpr.user'] ?: System.getenv('GITHUB_ACTOR')
+                password = secrets['gpr.token'] ?: System.getenv('GITHUB_TOKEN')
+            }
+        }
     }
 }
 
 task clean(type: Delete) {
     delete rootProject.buildDir
-}
+}

mobileapi/.gitignore example/.gitignore

@@ -0,0 +1,47 @@
+plugins {
+    id 'com.android.application'
+}
+
+android {
+    compileSdk 32
+
+    defaultConfig {
+        applicationId "me.clarius.sdk.mobileapi.example"
+        minSdk 26
+        targetSdk 32
+        versionCode 1
+        versionName "1.0"
+
+        buildConfigField("String", "CLARIUS_PACKAGE_NAME", clariusPackageName)
+        buildConfigField("String", "CLARIUS_SERVICE_NAME", clariusServiceName)
+        buildConfigField("String", "FILE_PROVIDER_NAME", fileProviderName)
+        buildConfigField("String", "FILE_PROVIDER_PATH", fileProviderPath)
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    buildFeatures {
+        viewBinding true
+    }
+}
+
+dependencies {
+    implementation 'androidx.appcompat:appcompat:1.4.1'
+    implementation 'com.google.android.material:material:1.6.0'
+    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
+    implementation 'androidx.navigation:navigation-fragment:2.4.2'
+    implementation 'androidx.navigation:navigation-ui:2.4.2'
+    implementation 'androidx.preference:preference:1.2.0'
+    implementation 'me.clarius.sdk:mobileapi:9.4.0-SNAPSHOT'
+    implementation project(path: ':helper')
+}

example/build.gradle

@@ -1,10 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="me.clarius.mobileapi.quickstart">
+    package="me.clarius.sdk.mobileapi.example">
 
     <queries>
         <package android:name="me.clarius.clarius" />
         <package android:name="me.clarius.clarius.release" />
+        <package android:name="me.clarius.clarius.develop.developer.debug" />
     </queries>
 
     <application
@@ -20,7 +21,6 @@
             android:exported="true">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
-
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
         </activity>
@@ -30,7 +30,7 @@
         </activity>
         <provider
             android:name="androidx.core.content.FileProvider"
-            android:authorities="me.clarius.mobileapi.quickstart.fileprovider"
+            android:authorities="me.clarius.sdk.mobileapi.FileProvider"
             android:exported="false"
             android:grantUriPermissions="true">
             <meta-data

mobileapi/proguard-rules.pro example/proguard-rules.pro

@@ -1,4 +1,4 @@
-package me.clarius.mobileapi.quickstart;
+package me.clarius.sdk.mobileapi.example;
 
 import android.os.Bundle;
 import android.view.LayoutInflater;

quickstart/src/main/AndroidManifest.xml example/src/main/AndroidManifest.xml

@@ -1,4 +1,4 @@
-package me.clarius.mobileapi.quickstart;
+package me.clarius.sdk.mobileapi.example;
 
 import android.graphics.Bitmap;
 
@@ -7,7 +7,7 @@
 import androidx.lifecycle.ViewModel;
 
 /**
- * Communication with fragments
+ * Share data from activity to fragments.
  * <p>
  * https://developer.android.com/guide/fragments/communicate
  */