PIR – Android App

IDS: Code for the Android App
See Releases »

Research Paper · Test Results · See Global Usage

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • Execution
   • Tests
   • Generation
   • Documentation
4. Contribute
5. Tree Structure
6. Credits
7. Contact

---

About The Project

This code will be used in order to receive the anomalies detected by the Arduino and to check if an event is linked to a distant action.

Built With

• Kotlin
• Android
• Jetpack Compose
• Jetpack Room

Getting Started

Prerequisites

• Android Studio is the preferred way to use this project.

If you don't use Android Studio

• Install the Command line tools for Android and move the content of cmdline-tools/bin into a newly created tree structure: <android_sdk_path>/cmdline-tools/latest/bin/ where <android_sdk_path> is a path of your choice where the SDK will be installed (see: https://developer.android.com/studio/command-line/sdkmanager).

  cd <android_sdk_path>
  mkdir -p cmdline-tools/latest
  cp -r cmdline-tools/* cmdline-tools/latest/

• Install the Android SDK with sdkmanager:

  cd <android_sdk_path>/cmdline-tools/latest/bin
  sdkmanager "platform-tools" "platforms;android-33"

Installation

1. Clone the project. Then if you use Android Studio, open the project and skip to step 3.

   git clone https://github.com/PIR-IDS/IDS-Android-App.git

2. If you don't use Android Studio: Create your local.properties file. Replace <android_sdk_path> with the path to your local Android SDK you installed with sdkmanager.

   echo "sdk.dir=<android_sdk_path>" > local.properties

3. Optional: If you want to test the release version of the app on your device, set up your keystore.properties file by copying keystore.properties.template and renaming it keystore.properties. Fill it with the necessary information, i.e. your local development release keys (see: https://developer.android.com/studio/build/building-cmdline#sign_cmdline and https://developer.android.com/studio/publish/app-signing#secure-shared-keystore).

   cp keystore.properties.template keystore.properties

4. IDS Android App is now ready to run.

Usage

Execution

Use the following script in the project root to install the app in debug mode (with the Android device plugged):

./gradlew installDebug

You can also run the release version when the app is signed (see Installation Step 3) with:

./gradlew installRelease

Tests

You can run the unit tests and the Android tests (with the Android device plugged) powered by JUnit with the following command:

./gradlew test
./gradlew connectedAndroidTest

Generation

To generate all the APKs, launch the following script:

./gradlew build

The APKs are generated in the app/build/outputs/apk directory.

You can also generate the AABs with the following script:

./gradlew bundle

The AABs are generated in the app/build/outputs/bundle directory.

Documentation

To generate all the Dokka documentation, launch the following script:

./gradlew dokkaHtml

The documentation is generated in the app/build/dokka directory.

Contribute

You will find in this section how to add new services and devices to the project.

Add a Service to the compatibility list

To add a new service to the compatible ones, you need to add the necessary resources and then edit some files.

A. Resources

1. Add an square icon for the service in the folder app/src/main/res/drawable-nodpi in PNG, for example my_service_logo.png.
2. Add a string resource for the service description in the folder app/src/main/res/values/strings.xml, for example my_service_description. Do not forget to translate the string in all the languages supported by the app.

B. Sources

1. Add an enumeration to ServiceId with a unique tag in app/src/main/java/fr/pirids/idsapp/data/items/Service.kt. Also add the service to the Service list with the associated devices that will be used to detect the behavioural anomalies.
2. Add a way to handle the service credentials necessary to interact with the API in a new created file in app/src/main/java/fr/pirids/idsapp/data/api/auth, named MyServiceAuth.kt. This class has to inherit from ApiAuth. You will have to provide a way to instanciate this class each time a connection has to be made, notably during the when statements in each of these files: app/src/main/java/fr/pirids/idsapp/controller/detection/Service.kt.
3. Add a way to handle the service data you get from the API in a new created file in app/src/main/java/fr/pirids/idsapp/data/api/data, named MyServiceData.kt. This class has to inherit from ApiData. You will have to provide a way to instanciate this class each time data has to be retrieved, notably during the when statements in each of these files: app/src/main/java/fr/pirids/idsapp/controller/detection/Service.kt, app/src/main/java/fr/pirids/idsapp/ui/views/service/ServiceView.kt, app/src/main/java/fr/pirids/idsapp/controller/detection/Detection.kt, app/src/main/java/fr/pirids/idsapp/controller/daemon/ServiceDaemon.kt.
4. Create a class that will handle the connection to the service, which inherits from ApiInterface in a new created file in app/src/main/java/fr/pirids/idsapp/controller/api, named MyServiceApi.kt. You will have to provide a way to instanciate this class each time a connection has to be made, notably during the when statements in each of these files: app/src/main/java/fr/pirids/idsapp/controller/detection/Service, app/src/main/java/fr/pirids/idsapp/controller/daemon/ServiceDaemon.kt.
5. Add the persistence of the credentials and the data retrieved by creating the entity and DAO linked to the new service. Create a new file in app/src/main/java/fr/pirids/idsapp/data/model/entity/service named MyServiceAuth.kt. Link a foreign key to the ApiAuth entity id. Create a new file in app/src/main/java/fr/pirids/idsapp/data/model/entity/service named MyServiceData.kt. Link a foreign key to the ApiData entity id. Register the newly created entities into the app/src/main/java/fr/pirids/idsapp/data/model/AppDatabase.kt file. Now create the DAO for the new service, following the same logic in the app/src/main/java/fr/pirids/idsapp/data/model/dao package. Call them MyServiceAuthDao and MyServiceDataDao and add their implementation to the app/src/main/java/fr/pirids/idsapp/data/model/AppDatabase.kt file. You will have to use the DAO notably during the when statements in each of these files: app/src/main/java/fr/pirids/idsapp/controller/detection/Service, app/src/main/java/fr/pirids/idsapp/controller/daemon/ServiceDaemon.kt, app/src/main/java/fr/pirids/idsapp/controller/detection/Detection.kt.

Add a BLE Device support

To support a new BLE device, you need to add the necessary resources and then edit some files.

A. Resources

1. Add an square icon for the device in the folder app/src/main/res/drawable-nodpi in PNG, for example ids_device_name_logo.png.
2. Add a string resource for the device description in the folder app/src/main/res/values/strings.xml, for example device_name_desc. Also add a data name, for example device_name_data, an event message, for example device_name_event_message and an intrusion message, for example device_name_intrusion. Do not forget to translate all the strings in all the languages supported by the app.

B. Sources

1. Add an enumeration to DeviceId with a unique tag in app/src/main/java/fr/pirids/idsapp/data/items/Device.kt. Also add the device to the Device list with the associated Bluetooth services that will be used to transmit the data. You can add the services with their characteristics in their respective files if they are still not added.
2. Add a way to handle the service data you get from the device in a new created file in app/src/main/java/fr/pirids/idsapp/data/device/data, named MyDeviceData.kt. This class has to inherit from DeviceData, you can also add some Bluetooth characteristics you would want to store during runtime in there. You will have to provide a way to instanciate this class each time data has to be used, notably during the when statements in each of these files: app/src/main/java/fr/pirids/idsapp/controller/view/menus/NotificationViewController.kt, app/src/main/java/fr/pirids/idsapp/ui/views/service/DeviceView.kt, app/src/main/java/fr/pirids/idsapp/controller/detection/Detection.kt, app/src/main/java/fr/pirids/idsapp/controller/daemon/DeviceDaemon.kt, app/src/main/java/fr/pirids/idsapp/controller/bluetooth/Device.kt, app/src/main/java/fr/pirids/idsapp/controller/bluetooth/BluetoothConnection.kt. You will have to handle the BLE communication in app/src/main/java/fr/pirids/idsapp/controller/bluetooth/BluetoothConnection.kt.
3. Add the persistence of the device data retrieved by creating the entity and DAO linked to the new device. Create a new file in app/src/main/java/fr/pirids/idsapp/data/model/entity/device named MyDeviceData.kt. Link a foreign key to the DeviceData entity id. Register the newly created entity into the app/src/main/java/fr/pirids/idsapp/data/model/AppDatabase.kt file. Now create the DAO for the new device, following the same logic in the app/src/main/java/fr/pirids/idsapp/data/model/dao package. Call it MyDeviceDataDao and add its implementation to the app/src/main/java/fr/pirids/idsapp/data/model/AppDatabase.kt file. You will have to use the DAO notably during the when statements in each of these files: app/src/main/java/fr/pirids/idsapp/controller/daemon/DeviceDaemon.kt, app/src/main/java/fr/pirids/idsapp/controller/bluetooth/BluetoothConnection.kt.

---

Tree Structure

TODO

Credits

Romain Monier [ GitHub ] – Co-developer
Morgan Pelloux [ GitHub ] – Co-developer
David Violes [ GitHub ] – Co-developer
Amélie Muller [ GitHub ] – Co-developer
Malik Sedira [ GitHub ] – Co-developer
Quentin Douarre [ GitHub ] – Co-developer
Noé Chauveau [ GitHub ] – Co-developer
Pierre Favary [ GitHub ] – Co-developer

Contact

Project Link : https://github.com/PIR-IDS/IDS-Android-App

Organization Link : https://github.com/PIR-IDS