Android App for AWS IoT FleetWise

Note

This guide makes use of "gated" features of AWS IoT FleetWise for which you will need to request access. See here for more information, or contact the AWS Support Center.

This app demonstrates AWS IoT FleetWise using an Android smartphone or Android Automotive.

Android Smartphone User guide
Android Automotive User Guide
Android Developer Guide

Android Smartphone User guide

Prerequisites:

An Android 5.0+ smartphone.
An ELM327 Bluetooth OBD adapter.
Access to an AWS Account with administrator privileges.
Your AWS account has access to AWS IoT FleetWise "gated" features. See here for more information, or contact the AWS Support Center.
Logged in to the AWS Console in the us-east-1 region using the account with administrator privileges.
- Note: if you would like to use a different region you will need to change us-east-1 to your desired region in each place that it is mentioned below.
- Note: AWS IoT FleetWise is currently available in these regions.

This guide demonstrates AWS IoT FleetWise using a smartphone with Android 5.0+ and a commonly available ELM327 Bluetooth OBD adapter.

Download the latest APK from GitHub to the phone: https://github.com/aws/aws-iot-fleetwise-edge/releases/latest/download/aws-iot-fleetwise-edge.apk
Install the app, which will require enabling installation from unknown sources.
Open the app, which will ask permission to collect GPS location data and access Bluetooth devices.
Open the AWS CloudShell: Launch CloudShell

Copy and paste the following command to clone the latest FWE source code from GitHub.

git clone https://github.com/aws/aws-iot-fleetwise-edge.git ~/aws-iot-fleetwise-edge

Run the following script to provision credentials for the app to connect to your AWS account. You will be asked to enter the name of an existing S3 bucket, in which the credentials will be saved. Note: It is important that the chosen S3 bucket is not public.
```
cd ~/aws-iot-fleetwise-edge/tools/android-app/cloud \
&& pip3 install segno \
&& ./provision.sh \
   --region us-east-1 \
   --s3-qr-code
```
When the script completes, the path to a QR code image file is given: /home/cloudshell-user/aws-iot-fleetwise-edge/tools/android-app/cloud/config/provisioning-qr-code.png. Copy this path, then click on the Actions drop down menu in the top-right corner of the CloudShell window and choose Download file. Paste the path to the file, choose Download, and open the downloaded image.
Scan the QR code with the phone, which will open the link in the app and download the credentials. This will cause the app to connect to the cloud and you should shortly see the status MQTT connection: CONNECTED.
- If scanning the QR code does not open the app, and instead opens a webpage: Copy the webpage link, then open the app, go to 'Vehicle configuration' and paste the link.
Optional: If you want to delete the credentials from the S3 bucket for security, run the command suggested by the output of the script which will be similar to:
```
aws s3 rm s3://<S3_BUCKET_NAME>/fwdemo-android-<TIMESTAMP>-creds.json
```
Plug in the ELM327 OBD Bluetooth adapter to your vehicle and switch on the ignition.
Go to the Bluetooth menu of your phone, then pair the ELM327 Bluetooth adapter. Typically the the name of the device is OBDII and the pairing PIN number is 1234.
Go back to the app, then go to 'Bluetooth device' and select the ELM327 device you just paired.
After a short time you should see that the status is updated with: Bluetooth: Connected to ELM327 vX.X and Supported OBD PIDs: XX XX XX.

In the cloud shell, run the following command to create an AWS IoT FleetWise campaign to collect GPS and OBD PID data and send it to Amazon Timestream. After a short time you should see that the status in the app is updated with: Campaign ARNs: arn:aws:iotfleetwise:us-east-1:XXXXXXXXXXXX:campaign/fwdemo-android-XXXXXXXXXX-campaign.

../../cloud/demo.sh \
   --region us-east-1 \
   --vehicle-name `cat config/vehicle-name.txt` \
   --node-file ../../cloud/obd-nodes.json \
   --node-file ../../cloud/custom-nodes-location.json \
   --decoder-file ../../cloud/obd-decoders.json \
   --decoder-file ../../cloud/custom-decoders-location.json \
   --network-interface-file ../../cloud/network-interface-obd.json \
   --network-interface-file ../../cloud/network-interface-custom-location.json \
   --campaign-file campaign-android-obd.json

Go to the Amazon Timestream Query editor and run the query suggested by the demo script, which will be of the form:

SELECT * FROM "IoTFleetWiseDB-<TIMESTAMP>"."VehicleDataTable" WHERE vehicleName='fwdemo-android-<TIMESTAMP>' AND time between ago(1m) and now() ORDER BY time ASC

Optional: If you want to clean up the resources created by the provision.sh and demo.sh scripts, run the following command. Note: this will not delete the Amazon Timestream database.
```
../../cloud/clean-up.sh \
&& ../../provision.sh \
   --vehicle-name `cat config/vehicle-name.txt` \
   --region us-east-1 \
   --only-clean-up
```

Android Automotive User Guide

This guide demonstrates AWS IoT FleetWise using the Android emulator running Android Automotive (AAOS). Note: this guide uses the pre-built image for AAOS, which means the app will not have access to privileged VHAL properties. To demonstrate the app accessing privileged VHAL properties, follow the Android Automotive system image build guide.

Prerequisites:

Access to an AWS Account with administrator privileges.
Your AWS account has access to AWS IoT FleetWise "gated" features. See here for more information, or contact the AWS Support Center.
Logged in to the AWS Console in the us-east-1 region using the account with administrator privileges.
- Note: if you would like to use a different region you will need to change us-east-1 to your desired region in each place that it is mentioned below.
- Note: AWS IoT FleetWise is currently available in these regions.
A local x86_64 Ubuntu 20.04 machine with the AWS CLI installed.

Android emulator setup and app installation

Install the preview version of Android Studio: https://developer.android.com/studio/preview
From the 'Welcome to Android Studio' window (close any open project), click on ... -> SDK Manager. Under 'SDK Platforms', select 'Show Package Details'. Under 'Android 12L ("Sv2")', select 'Automotive with Play Store Intel x86_64 Atom System Image'. Under 'SDK Tools', select 'Android SDK Platform-Tools'. Click Apply, to download and install the packages.
From the 'Welcome to Android Studio' window, click on ... -> Virtual Device Manager. Under Virtual, select 'Create Device'. Under category, select Automotive, then Next, leave the recommended release selected, then Next and Finish.
Click the refresh button, then the play button to start the emulator. After some time the AAOS home screen is shown.

Run the following on your local machine to download and install the app:

wget https://github.com/aws/aws-iot-fleetwise-edge/releases/latest/download/aws-iot-fleetwise-edge.apk \
&& ~/Android/Sdk/platform-tools/adb install aws-iot-fleetwise-edge.apk

Provision credentials and collect data

Run the following script to provision credentials for the app to connect to your AWS account.

git clone https://github.com/aws/aws-iot-fleetwise-edge.git ~/aws-iot-fleetwise-edge \
&& cd ~/aws-iot-fleetwise-edge/tools/android-app/cloud \
&& ./provision.sh \
   --region us-east-1

Run the following to configure the app with the credentials. This will cause the app to connect to the cloud and you should shortly see the status MQTT connection: CONNECTED.

CREDS=`cat config/creds.json` \
&& ESCAPED_CREDS=`printf "%q" "${CREDS}"` \
&& ~/Android/Sdk/platform-tools/adb shell am start \
   -a android.intent.action.VIEW \
   -n com.aws.iotfleetwise/.MainActivity \
   -e credentials "${ESCAPED_CREDS}"

Run the following command to create an AWS IoT FleetWise campaign to collect GPS and AAOS VHAL data and send it to Amazon Timestream. After a short time you should see that the status in the app is updated with: Campaign ARNs: arn:aws:iotfleetwise:us-east-1:XXXXXXXXXXXX:campaign/fwdemo-android-XXXXXXXXXX-campaign.

sudo -H ../../cloud/install-deps.sh \
&& ../../cloud/demo.sh \
   --region us-east-1 \
   --vehicle-name `cat config/vehicle-name.txt` \
   --node-file ../../cloud/custom-nodes-location.json \
   --node-file custom-nodes-aaos-vhal.json \
   --decoder-file ../../cloud/custom-decoders-location.json \
   --decoder-file custom-decoders-aaos-vhal.json \
   --network-interface-file ../../cloud/network-interface-custom-location.json \
   --network-interface-file network-interface-custom-aaos-vhal.json \
   --campaign-file campaign-android-aaos-vhal.json

Go to the Amazon Timestream Query editor and run the query suggested by the script, which will be of the form:

SELECT * FROM "IoTFleetWiseDB-<TIMESTAMP>"."VehicleDataTable" WHERE vehicleName='fwdemo-android-<TIMESTAMP>' AND time between ago(1m) and now() ORDER BY time ASC

Optional: If you want to clean up the resources created by the provision.sh and demo.sh scripts, run the following command. Note: this will not delete the Amazon Timestream database.
```
../../cloud/clean-up.sh \
&& ../../provision.sh \
   --vehicle-name `cat config/vehicle-name.txt` \
   --region us-east-1 \
   --only-clean-up
```

Android Developer Guide

This guide details how to build the app from source code and use the shared library in your own Android apps.

App build guide

An x86_64 Ubuntu 20.04 development machine with 200GB free disk space should be used.

Clone the source code:

git clone https://github.com/aws/aws-iot-fleetwise-edge.git ~/aws-iot-fleetwise-edge \
&& cd ~/aws-iot-fleetwise-edge

Install the dependencies:

sudo -H ./tools/install-deps-cross-android.sh

Build the shared libraries:

./tools/build-fwe-cross-android.sh \
&& ./tools/build-dist.sh \
    build/x86_64/libaws-iot-fleetwise-edge.so:x86_64 \
    build/arm64-v8a/libaws-iot-fleetwise-edge.so:arm64-v8a \
    build/armeabi-v7a/libaws-iot-fleetwise-edge.so:armeabi-v7a

Build the app:

 mkdir -p tools/android-app/app/src/main/jniLibs \
 && cp -r build/dist/x86_64 build/dist/arm64-v8a build/dist/armeabi-v7a tools/android-app/app/src/main/jniLibs \
 && cp THIRD-PARTY-LICENSES tools/android-app/app/src/main/assets \
 && cd tools/android-app \
 && ANDROID_HOME=/usr/local/android_sdk ./gradlew assemble

Shared library interface

The C++ code is compiled into a shared library using the Android NDK. The interface for shared library can be found in the JNI wrapper class app/src/main/java/com/aws/iotfleetwise/Fwe.java. The shared library can also be used in your app using this interface, which includes a method to ingest raw CAN frame data.

Android Automotive system image build guide

This guide details how to build the Android Automotive system image from source, in order for the app to have access to the privileged VHAL properties. These properties are only accessible to apps signed with the platform certificate, which in this case will be the standard Android test certificate.

Prerequisites:

A high performance x86_64 Ubuntu 20.04 development machine (e.g. an m6a.8xlarge EC2 instance) with 300 GB free storage space.
A local x86_64 Ubuntu 20.04 machine with Android Studio and the AWS CLI installed.

References:

Android Virtual Device as a Development Platform
AAOS car AVD tools

On the development machine, install the dependencies for compiling the system image:

sudo apt update \
&& DEBIAN_FRONTEND=noninteractive sudo -E apt install -y default-jdk zip unzip libncurses5 binutils python curl \
&& sudo curl -o /usr/local/bin/repo https://storage.googleapis.com/git-repo-downloads/repo \
&& sudo chmod +x /usr/local/bin/repo \
&& git config user.name > /dev/null || git config --global user.name "ubuntu" \
&& git config user.email > /dev/null || git config --global user.email "ubuntu@`hostname`" \
&& git config color.ui || git config --global color.ui false

Run the following commands to build the Android Automotive system image. This will take several hours.

ANDROID_BRANCH="android12L-release" \
&& REPO_URL="https://android.googlesource.com/platform/manifest" \
&& mkdir $ANDROID_BRANCH \
&& cd $ANDROID_BRANCH \
&& repo init -u $REPO_URL -b $ANDROID_BRANCH --partial-clone \
&& repo sync -c -j8 \
&& source build/envsetup.sh \
&& lunch sdk_car_x86_64-userdebug \
&& m -j`nproc`

Create the file emu_img_zip.mk and add the content from here, then create the Android Virtual Device (AVD) image ZIP file.
```
m emu_img_zip
```

On your local machine, run the following to download and unzip the AVD image ZIP file in the ~/Android/Sdk/system-images folder:

scp -i <PATH_TO_PEM> ubuntu@<EC2_IP_ADDRESS>:/home/ubuntu/android12L-release/out/target/product/emulator_car_x86_64/sdk-repo-linux-system-images-eng.ubuntu.zip . \
&& unzip -d ~/Android/Sdk/system-images/car_avd \
   sdk-repo-linux-system-images-eng.ubuntu.zip

Create the file create_avd_config.sh and add the content from here, then create the AVD config file (with display settings 213 DPI, 1920x1080 resolution, and 3584 MB of memory):
```
bash create_avd_config.sh \
   car_avd \
   ~ \
   $HOME/Android/Sdk/system-images/car_avd/x86_64/ \
   213 \
   1920 \
   1080 \
   3584 \
   x86_64
```

Run the emulator, which will start AAOS:

ANDROID_SDK_ROOT=~/Android/Sdk ~/Android/Sdk/emulator/emulator -avd car_avd

Copy the platform key and certificate from the development machine (this is the standard Android test certificate):

scp -i <PATH_TO_PEM> ubuntu@<EC2_IP_ADDRESS>:/home/ubuntu/android12L-release/build/target/product/security/platform.x509.pem .
scp -i <PATH_TO_PEM> ubuntu@<EC2_IP_ADDRESS>:/home/ubuntu/android12L-release/build/target/product/security/platform.pk8 .

Download the app from GitHub and re-sign it with the platform key, so that the app has access to the AAOS VHAL properties with privileged level permissions:

curl -o aws-iot-fleetwise-edge-original.apk https://github.com/aws/aws-iot-fleetwise-edge/releases/latest/download/aws-iot-fleetwise-edge.apk \
&& `ls -d ~/Android/Sdk/build-tools/* | tail -n -1`/apksigner sign \
   --key platform.pk8 \
   --cert platform.x509.pem \
   --out aws-iot-fleetwise-edge.apk \
   aws-iot-fleetwise-edge-original.apk

Install the app using adb:

~/Android/Sdk/platform-tools/adb install aws-iot-fleetwise-edge.apk

You can now follow the this section to provision credentials and collect data.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Android App for AWS IoT FleetWise

Android Smartphone User guide

Android Automotive User Guide

Android emulator setup and app installation

Provision credentials and collect data

Android Developer Guide

App build guide

Shared library interface

Android Automotive system image build guide

Files

README.md

Latest commit

History

README.md

File metadata and controls

Android App for AWS IoT FleetWise

Android Smartphone User guide

Android Automotive User Guide

Android emulator setup and app installation

Provision credentials and collect data

Android Developer Guide

App build guide

Shared library interface

Android Automotive system image build guide