# Getting Started on Android

# Introduction

<span lang="EN-US" style="mso-fareast-language: ZH-CN;">This manual gives brief instructions to get the Matlab-Connector sample applications built and deployed on Android. Namely, those are MLC-Cluster and MLC-Signals.</span>

<span lang="EN-US" style="mso-fareast-language: ZH-CN;">This Guide addresses the experienced user, therefore the obvious points will not be explained here. Topic are only the essential steps, but not things like the usage of the build tool CMake.</span>

#### <span lang="EN-US" style="mso-fareast-language: ZH-CN;">Abbreviations / Terminology</span>

<table border="1" id="bkmrk-abbreviation-termino" style="border-collapse: collapse; width: 100%; height: 89.3907px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="background-color: rgb(35, 111, 161); height: 29.7969px;"><span style="color: rgb(255, 255, 255);">**Abbreviation**</span></td><td style="background-color: rgb(35, 111, 161); height: 29.7969px;"><span style="color: rgb(255, 255, 255);">**Terminology**</span></td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">CANDERA</td><td style="height: 29.7969px;">CANDERA GmbH</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">ADB</td><td style="height: 29.7969px;">Android Debug Bridge, an important management tool</td></tr></tbody></table>

# Prerequisites

#### CMake GUI

For building, the tool cmake-gui is needed. Navigate to <span style="color: rgb(230, 126, 35);">[https://cmake.org/download/](https://cmake.org/download/)</span> and download the latest stable version for your PC, 64bit etition and install it.

#### Ninja build tool

For building android applications, yet another build tool is required.

- Navigate to <span style="color: rgb(230, 126, 35);">[https://ninja-build.org/](https://ninja-build.org/)</span> and download the ninja binary (yes, it’s only **ninja.exe**)  
    <div drawio-diagram="3103"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678168606.png" alt=""/></div>
- Save it at **C:\\Programs\\Ninja\\** and add this path to your **PATH** environment variable.

#### Android Studio

- Download the latest stable version of Android-Studio from Google and install it.
- Next, a special version of the Android-NDK is required because the newer ones are broken:  
    Navigate to: <span style="color: rgb(230, 126, 35);">[https://developer.android.com/ndk/downloads/older\_releases ](https://developer.android.com/ndk/downloads/older_releases)</span>and download the android-NDK-r17c as shown below.  
      
    <div drawio-diagram="3105"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678168826.png" alt=""/></div>
- Extract the downloaded zip file, rename the unpacked folder to **ndk-r17c** and move it to:  
    **%USERPROFILE%\\AppData\\Local\\Android\\Sdk\\**  
    This way, the NDK-r17c exists in parallel to the delivered one and will not be affected by updates.
- Set the environment variable **ANDROID\_NDK** to the path where you saved ndk-r17c:  
    here it is: **%USERPROFILE%\\AppData\\Local\\Android\\Sdk\\ndk-r17c\\**  
    This is mandatory for the toolchain file.
- Finally extend the **PATH** environment variable to the **platform tools directory**:  
    Here, this is **%USERPROFILE% \\AppData\\Local\\Android\\Sdk\\platform-tools\\**  
    This makes tools like **adb** available on **CMD**, which makes live a lot easier.

# Building an Application Library

- Open CMake Gui, fill in source and build directory and click Configure.
- A Dialog opens: Select “Ninja” as build system and check “Select toolchain file”
- Select: **cgi\_studio\_devices\\src\\Android\\ToolchainFiles\\GCC-toolchain-x86\_64-Android.cmake**  
    or **cgi\_studio\_devices\\src\\Android\\ToolchainFiles\\GCC-toolchain-ARM64-Android.cmake**  
    depending what you need.
- After first configure run, perform following cmake configurations:  
    **MLC\_SIMULATION**:=OFF (This is only relevant in case of an MLC application)  
    **ANDROID\_PLATFORM\_LEVEL**:=&lt;number between 21 and 28, which is the android api level&gt;  
    This should be **smaller or equal** the android version of your device.  
    (If you don’t select a level, the toolchain file decides. This might then not be what you want)
- Finally click “Configure” once more, then “Generate” afterwards.  
    If you created the corresponding Asset-Libraries within the designated “Assets” directory before, the platform-specific one gets also copied to the build folder, which is very handy for deploying (see next section).
- In a CMD window navigate to you build folder and type ninja.
- This builds the application and should deliver you a **libApplicationLib.so** file, which we’ll need for the next steps.

# Deploying the Asset Library

Before an android application can be launched, the asset library has to be deployed on the Android device. Now the tool ADB (Android Debug Bridge) comes into play, which is part of the sdk-platform tools. It is a command line tool which has to be called e.g. within a Windows CMD. ADB is a general device management tool for Android.

The most important tasks are:

- Pushing and pulling files between the host computer and the android device
- Installing/uninstalling android apps on the device
- Viewing the logcat
- It even provides a bash terminal access (yes, even root user) to the android device

The most important commands for this work are:

- adb help  
    Show help and description of supported commands
- adb devices   
    List all connected android devices
- adb push &lt;source-file&gt; &lt;target-file or target-folder&gt;  
    Push a local file to the android device
- adb shell  
    Open a bash terminal session on the android device – this is the god-mode, so be careful!

<div drawio-diagram="5116"><img src="https://doc316en.candera.eu/uploads/images/drawio/2024-01/drawing-5-1706252739.png" alt=""/></div>

 Steps for deploying the AssetLib on the Android device:

- Open a Windows CMD and navigate to the build folder (or where you generated the asset library)
- Type e.g.: adb push AssetLibCff\_Android\_Target.bin /sdcard/AssetLibCff.bin

<p class="callout info"> /sdcard is the internal or external storage on Android. That’s the location, where the app expects the asset library.  
</p>

# Generating and deploying an Android-App

Now an android studio project skeleton is needed for constructing a so-called apk file, which is the format of android app packages, like those on Google AppStore.

- Navigate to cgi\_studio\_apps/references/Android/ and copy the MlcSample project to a location you like
- From your build directory, copy the file libApplicationLib.so to following location of your project skeleton:  
    &lt;MlcProject&gt;/app/native-libs/&lt;architecture&gt;/
- Open Android-Studio and open your MlcSample project. This wil take a few seconds, wait till everything is ready.
- Click at “Syncronise Project” like shown below and wait again till everything is ready:  
    (This is only needed when the project is opened the first time)  
    <div drawio-diagram="3108"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169637.png" alt=""/></div>
- Next click at “Show Project-Structure” like shown below:  
    (This is only needed when the project is opened the first time)  
    <div drawio-diagram="3109"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169672.png" alt=""/></div>
- A dialog opens. Select the tab “SDK Location” and there ensure that the field “Android NDK location” (the bottom-most one) is set to the ndk-r17c, which you installed previously:  
    <div drawio-diagram="3110"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169700.png" alt=""/></div>
- Click OK and you’re ready to build and deploy.
- Ensure that you connected your android device to an USB port and enabled “USB debugging” on that device.
- Finally klick the “Run-Button”, like shown below and await what will happen:  
    <div drawio-diagram="3111"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169731.png" alt=""/></div>
- Sometimes Android Studio asks for device selection – do so and proceed…  
    <div drawio-diagram="3112"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169743.png" alt=""/></div>
- Sometimes Android Studio asks to install missing platforms. Simply do so and proceed…  
    <div drawio-diagram="3113"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169765.png" alt=""/></div>
- And if you’re using an absolutely new platform like shown in the dialog above, Android-Studio still cries around: Simply klick OK to proceed and forget about that:  
    <div drawio-diagram="3114"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169782.png" alt=""/></div>
- Finally if the application is deployed and running, Android Studio should look like this:  
    <div drawio-diagram="3115"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169797.png" alt=""/></div>

# Trouble-Shooting

- If you experience Problems, sometimes the so called “Log Cat” is quite helpful, which also allows live filtering by keywords like e.g. “myappname” or “failed” and thelike.  
    <div drawio-diagram="3116"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169896.png" alt=""/></div>
- Depending on the kind of your Android OS, sometimes the Permissions-Dialog is not displayed.  
    In such a case, the user has no chance to grant the needed permissions, when the app is installed the first time. That’s how to solve this problem:  
    Click “app-&gt;Edit Configurations”, like shown below:  
    <div drawio-diagram="3117"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169914.png" alt=""/></div>
    
      
    A dialog opens; In the field “Install Flags” input “-g” which pre-grants all permissions on installing.  
    <div drawio-diagram="3118"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169928.png" alt=""/></div>
    
      
    After saving this configuration, clicking at the Build-Button should do it’s job.
- When you want to debug your application and encounter that your breakpoints are ignored, you can try following: go to the run-configurations at the top right toolbar of android studio as shown below.  
    <div drawio-diagram="3119"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169948.png" alt=""/></div>
    
      
    A Popup appears, navigate do “Debugger” and ensure that “Dual” is set for the field: Debug types:  
    <div drawio-diagram="3120"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-03/drawing-4-1678169961.png" alt=""/></div>