Android Sample Split (#478)

* Fully split the Android sample and Android SDK builds
aws · Sep 28, 2023 · 02ca5f5 · 02ca5f5
1 parent 45cce3c
commit 02ca5f5
Show file tree

Hide file tree

Showing 39 changed files with 246 additions and 101 deletions.
diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ to Java by the [aws-crt-java](https://github.com/awslabs/aws-crt-java) package.
 *__Jump To:__*
 
 * [Installation](#installation)
+* [Android](./documents/ANDROID.md)
 * [Samples](samples)
 * [Getting Help](#getting-help)
 * [FAQ](./documents/FAQ.md)
@@ -103,51 +104,6 @@ cd aws-iot-device-sdk-java-v2
 # Compile and install
 mvn clean install
 ```
-
-#### Android
-
-Supports API 26 or newer.
-NOTE: The shadow sample does not currently complete on android due to its dependence on stdin keyboard input.
-
-``` sh
-# Create a workspace directory to hold all the SDK files
-mkdir sdk-workspace
-cd sdk-workspace
-# Clone the CRT repository
-#     (Use the latest version of the CRT here instead of "v0.27.3")
-git clone --branch v0.27.3 --recurse-submodules https://github.com/awslabs/aws-crt-java.git
-# Compile and install the CRT for Android
-cd aws-crt-java/android
-./gradlew connectedCheck # optional, will run the unit tests on any connected devices/emulators
-./gradlew publishToMavenLocal
-# Clone the SDK repository
-cd ../..
-git clone https://github.com/awslabs/aws-iot-device-sdk-java-v2.git
-# Compile and install
-cd aws-iot-device-sdk-java-v2/android
-./gradlew publishToMavenLocal
-./gradlew installDebug # optional, will install the IoTSamples app to any connected devices/emulators
-```
-
-Add the following to your project's build.gradle:
-
-``` groovy
-repositories {
-    mavenCentral()
-    maven {
-        url System.getenv('HOME') + "/.m2/repository"
-    }
-}
-
-dependencies {
-    implementation 'software.amazon.awssdk.crt:android:0.27.3'
-}
-```
-[Android IoT Samples README](./android/app/src/main/assets/README.md)
-
-Replace `0.27.3` in `software.amazon.awssdk.crt:android:0.27.3` with the latest version of the CRT.
-Look up the latest CRT version here: https://github.com/awslabs/aws-crt-java/releases
-
 ## Samples
 
 [Samples README](samples)

diff --git a/android/app/.gitignore b/android/app/.gitignore
diff --git a/android/app/src/main/assets/README.md b/android/app/src/main/assets/README.md
diff --git a/android/settings.gradle b/android/settings.gradle
@@ -1,3 +1,2 @@
-rootProject.name='IoTSamples'
-include ':app'
+rootProject.name='aws-iot-device-sdk-android'
 include ':iotdevicesdk'
diff --git a/documents/ANDROID.md b/documents/ANDROID.md
@@ -0,0 +1,96 @@
+# AWS IoT Device SDK for Android
+
+This document provides information about building and using the AWS IoT device SDK for Java V2 with Android.
+
+If you have any issues or feature requests, please file an issue or pull request.
+
+API documentation: https://aws.github.io/aws-iot-device-sdk-java-v2/
+
+This SDK is built on the AWS Common Runtime, a collection of libraries
+([aws-c-common](https://github.com/awslabs/aws-c-common),
+[aws-c-io](https://github.com/awslabs/aws-c-io),
+[aws-c-mqtt](https://github.com/awslabs/aws-c-mqtt),
+[aws-c-http](https://github.com/awslabs/aws-c-http),
+[aws-c-cal](https://github.com/awslabs/aws-c-cal),
+[aws-c-auth](https://github.com/awslabs/aws-c-auth),
+[s2n](https://github.com/awslabs/s2n)...) written in C to be
+cross-platform, high-performance, secure, and reliable. The libraries are bound
+to Java by the [aws-crt-java](https://github.com/awslabs/aws-crt-java) package.
+An Android library of the aws-crt-java package is built from the same library and is
+a dependency of the aws-iot-device-sdk-android library.
+
+*__Jump To:__*
+
+* [Installation](#installation)
+  * [Minimum requirements](#minimum-requirements)
+  * [Build and install IoT Device SDK from source](#build-and-install-iot-device-sdk-from-source)
+* [Consuming IoT Device SDK Android](#consuming-from-locally-installed)
+  * [Consuming from Maven](#consuming-from-maven)
+  * [Consuming from locally installed](#consuming-from-locally-installed)
+* [Samples App](#samples-app)
+
+## Installation
+
+### Minimum requirements
+* Java 11+ ([Download and Install Java](https://www.java.com/en/download/help/download_options.html))
+  * [Set JAVA_HOME](./PREREQUISITES.md#set-java_home)
+* Gradle 7.4.2 ([Download and Install Gradle](https://gradle.org/install/))
+* Android SDK 26 ([Doanload SDK Manager](https://developer.android.com/tools/releases/platform-tools#downloads))
+  * [Set ANDROID_HOME](./PREREQUISITES.md#set-android_home)
+
+### Build and install IoT Device SDK from source
+Supports API 26 or newer.
+NOTE: The shadow sample does not currently complete on android due to its dependence on stdin keyboard input.
+
+``` sh
+# Create a workspace directory to hold all the SDK files
+mkdir sdk-workspace
+cd sdk-workspace
+# Clone the SDK repository
+# (Use the latest version of the SDK here instead of "v1.17.0)
+git clone --branch v1.17.0 --recurse-submodules https://github.com/aws/aws-iot-device-sdk-java-v2.git
+# Compile and install the SDK for Android
+cd aws-iot-device-sdk-java-v2/android
+./gradlew build
+# Install SDK locally
+./gradlew publishToMavenLocal
+```
+
+## Consuming IoT Device SDK Android
+
+### Consuming from Maven
+##### NOTE: aws-iot-device-sdk-android is not currently available in Maven but will be shortly. For now, please publish to maven locally and [Consume from locally installed](#consuming-from-locally-installed)
+Consuming this SDK via Maven is the preferred method of consuming it and using it within your application. To consume
+IoT Device SDK Android in your application, add the following to your `build.gradle` repositories and dependencies:
+
+``` groovy
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    api 'software.amazon.awssdk.iotdevicesdk:aws-iot-device-sdk-android:1.17.0'
+}
+```
+Replace `1.17.0` in `software.amazon.awssdk.iotdevicesdk:aws-iot-device-sdk-android:1.17.0` with the latest release version for the SDK.
+Look up the latest SDK version here: https://github.com/aws/aws-iot-device-sdk-java-v2/releases
+
+### Consuming from locally installed
+You may also consume IoT Device SDK Android in your application using a locally installed version by adding the
+following to your `build.gradle` repositories and depenencies:
+``` groovy
+repositories {
+    mavenLocal()
+}
+
+dependencies {
+    api 'software.amazon.awssdk.iotdevicesdk:aws-iot-device-sdk-android:1.17.0'
+}
+```
+Replace `1.17.0` in `software.amazon.awssdk.iotdevicesdk:aws-iot-device-sdk-android:1.17.0` with the latest release version for the SDK
+or replace with `1.0.0-SNAPSHOT` to use the SDK built and installed from source.
+Look up the latest SDK version here: https://github.com/aws/aws-iot-device-sdk-java-v2/releases
+
+## Samples App
+[Android IoT Samples App README](../samples/Android/README.md)
+
diff --git a/documents/FAQ.md b/documents/FAQ.md
@@ -8,6 +8,7 @@
 * [Mac-Only TLS Behavior](#mac-only-tls-behavior)
 * [How do debug in VSCode?](#how-do-debug-in-vscode)
 * [What certificates do I need?](#what-certificates-do-i-need)
+* [How do I build and use the Android SDK?](#how-do-i-build-and-use-the-android-sdk)
 * [I still have more questions about this sdk?](#i-still-have-more-questions-about-this-sdk)
 
 ### Where should I start?
@@ -110,6 +111,8 @@ Here is an example launch.json file to run the pubsub sample
         * You should have generated/downloaded private and public keys that will be used to verify that communications are coming from you
         * When using samples you only need the private key and it will look like this: `--key abcde12345-private.pem.key`
 
+### How do I build and use the Android SDK?
+Instructions for building, installing, and use of the Android SDK can be found [here](../documents/ANDROID.md)
 ### I still have more questions about this sdk?
 
 * [Here](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) are the AWS IoT Core docs for more details about IoT Core

diff --git a/documents/PREREQUISITES.md b/documents/PREREQUISITES.md
@@ -289,3 +289,20 @@ Or using the command line:
 3. After CMake has installed, close the terminal and reopen it
 4. Type `cmake --version` to confirm CMake is installed.
 
+## Set ANDROID_HOME
+Below are instructions on how you can set `ANDROID_HOME`, which varies from depending on whether you are on Windows or are on MacOS/Linux:
+
+### Windows
+1. Open "Edit the system environment variable"
+2. Click "New" to create new environment variable
+   - variable name: `ANDROID_HOME`
+   - variable value: `<android_sdk_path>` (example: `C:\Users\YourUsername\AppData\Local\Android\Sdk`)
+3. Press "Ok" to save the changes
+4. re-open the command prompt for the environment variables to apply
+
+### MacOS and Linux
+Run the following command to set the JAVA_PATH
+``` sh
+# (example: "/Users/YourUsername/Library/Android/sdk")
+export ANDROID_HOME=<android_sdk_path>
+```
diff --git a/samples/Android/.gitignore b/samples/Android/.gitignore
@@ -0,0 +1 @@
+/.gradle
diff --git a/samples/Android/README.md b/samples/Android/README.md
@@ -0,0 +1,74 @@
+# Sample Application for the AWS IoT Device SDK Android
+[**Return to AWS IoT Device SDK for Android README**](../../documents/ANDROID.md)
+
+The Android sample builds an app that can be installed and run on an Android Device. The app builds and allows you
+to run the following [samples](#links-to-individual-sample-readme-files) from aws-iot-device-sdk-java-v2:
+* BasicPubSub
+* Mqtt5PubSub
+* Jobs
+* Shadow
+* CognitoConnect
+
+*__Jump To:__*
+
+* [Prerequisites](#prerequisites)
+  * [Files required to run samples](#files-required-to-run-samples)
+* [Build and install sample app](#build-and-install-sample-app)
+* [Links to sample README](#links-to-individual-sample-readme-files)
+
+
+# Prerequisites
+The individual samples within the app require specific files to operate. The files must be placed in the
+`app/src/main/assets` directory prior to building for the sample app to connect to IoT Core and complete
+succesfully. The names of the files must be exactly as provided. Explanations for what each file and
+associated argument are doing can be found in the individual [Sample README](#links-to-individual-sample-readme-files)
+files linked below.
+
+## Files required to run samples
+
+### Files required by all samples:
+* `endpoint.txt` - IoT ATS Endpoint
+
+### Required to run BasicPubSub, Mqtt5PubSub, Jobs, and Shadow samples
+* `certificate.pem` - IoT Thing Certificate
+* `privatekey.pem` - IoT Thing Private Key
+
+### Required to run Cognito Client sample:
+* `cognitoIdentity.txt` - Cognito identity ID
+* `signingRegion.txt` - Signing region
+
+### Optional files:
+* `rootca.pem` - override the default system trust store
+* `clientId.txt` - specifies --clientId CLI argument
+* `topic.txt` - specifies --topic CLI argument
+* `message.txt` - specifies --message CLI argument
+* `port.txt` - specifies --port CLI argument
+* `thingName.txt` - specifies --thingName CLI argument
+
+# Build and install sample app
+
+``` sh
+# Change to the app directory
+cd samples/Android/app
+# Use gradlew from the android folder to build the sample app
+../../../android/gradlew build
+
+# Install it to a connected Device
+../../../android/gradlew installDebug
+```
+
+# Links to individual sample README files
+The following links will provide more details on the individual samples available in the
+Android sample app.
+
+[**BasicPubSub**](../BasicPubSub/README.md)
+
+[**Mqtt5PubSub**](../Mqtt5/PubSub/README.md)
+
+[**Jobs**](../Jobs/README.md)
+
+[**Shadow**](../Shadow/README.md)
+
+[**CognitoConnect**](../CognitoConnect/README.md)
+
+##### NOTE: The shadow sample does not currently complete on android due to its dependence on stdin keyboard input.
diff --git a/samples/Android/app/.gitignore b/samples/Android/app/.gitignore
@@ -0,0 +1,4 @@
+/build
+./gradle
+/local.properties
+/.gradle
diff --git a/android/app/build.gradle → samples/Android/app/build.gradle b/android/app/build.gradle → samples/Android/app/build.gradle
@@ -1,3 +1,21 @@
+buildscript {
+    ext.kotlin_version = '1.5.0'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:7.1.2"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+repositories {
+    google()
+    mavenLocal()
+    mavenCentral()
+}
+
 apply plugin: 'com.android.application'
 apply plugin: 'kotlin-android'
 
@@ -18,11 +36,11 @@ android {
 
     sourceSets {
         main {
-            java.srcDir '../../samples/Utils/CommandLineUtils'
-            java.srcDir '../../samples/BasicPubSub/src/main/java'
-            java.srcDir '../../samples/Jobs/src/main/java'
-            java.srcDir '../../samples/Shadow/src/main/java'
-            java.srcDir '../../samples/CognitoConnect/src/main/java'
+            java.srcDir '../..Utils/CommandLineUtils'
+            java.srcDir '../..BasicPubSub/src/main/java'
+            java.srcDir '../..Jobs/src/main/java'
+            java.srcDir '../..Shadow/src/main/java'
+            java.srcDir '../..CognitoConnect/src/main/java'
             java.srcDir 'src/main/java'
         }
     }
@@ -40,14 +58,9 @@ android {
     ndkVersion '23.1.7779620'
 }
 
-repositories {
-    mavenLocal()
-    mavenCentral()
-}
-
 dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
-    implementation project(":iotdevicesdk")
+    api 'software.amazon.awssdk.iotdevicesdk:aws-iot-device-sdk-android:1.17.0'
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
     implementation 'androidx.appcompat:appcompat:1.1.0'
     implementation 'androidx.core:core:1.2.0'