This is the Mobile Sensing Android app of the European Mobile Sensing Research Consortium.
How To Get Started
- Checkout emsrc-android-core project to a folder of your choice
git clone https://github.com/emsrc-team/emsrc-android-core.git
- navigate into the folder that was created on checkout
- Here checkout all other modules' repositories you want to use. E.g.
git clone https://github.com/emsrc-team/emsrc-android-wifi.gitand
git clone https://github.com/emsrc-team/emsrc-android-appusage.git
- Open emsrc-android-core in Android Studio - and you're done
In order to work properly, it is important that the folders common, core, and all module folders (e.g. logging_wifi) are in the same directory. Later you don't have to worry about having multiple repositories in one project, Android Studio handles this fine.
Project Modules Structure
The EMSRC Android App consists of 2 + x modules, where x is the amount of logging components.
This is the main module, containing the app stuff like UI, LoggingService, the main gradle build file, etc. All other modules (common and the logging component modules) are used by this module as a dependency.
This module contains code that is required as a dependency by both the core module and the logging component modules. For example it implements interfaces for logging components or general helper classes.
E.g. logging_wifi Each logging module implements a logging functionality - this is where the actual magic happens. They can be plugged in and out from the app build through Gradle dependency configuration - see below for more details.
Build Flavors and logging component inclusion
Despite the build types debug and release, the EMSRC project configures a build flavor dimension named study. There are the flavors emsrc, isabella, phonestudy and remap. Which flavor actually is used can be selected in Android Studio's Build Variants window (on the very left of Android Studio). Build flavors affect the following:
The default sourceset used is src/main/... . This one is used in the emsrc flavor, which kinda is our default. If the flavor remap is used, the default sourceset and the sourceset src/remap/... are merged. This allows customizing the app, e.g. overriding the app name by creating a src/remap/res/values/strings.xml file (which would replace the default src/main/res/values/strings.xml in remap flavor builds).
Logging Module Inclusion
The used study flavor also affects which logging component modules will be compiled into the app. This is defined in the core module's Gradle file core/build.gradle:
// components that are included in all flavors implementation project(":logging_wifireceiver") // components that phonestudy builds will include phonestudyImplementation project(":logging_appusage") // components that isabella builds include // --- no ones yet ---- // components that are included in remap builds remapImplementation project(":logging_appusage")
Here, all builds include the wifi logging component, but only phonestudy and remap additionally include the appusage logging component. This is the single point of configuration, defining which logging components will be compiled + started in the app. Only those modules that are included as dependency by the selected study flavor have to be checked out into the project. Others may miss.
Creating a new Logging Component Module
In order to make that smooth component management work, a logging component must be setup correctly:
- Module name and repository name must be the same
- Include the common module as a dependency
- Contain a "main" class, implementing the interface ILoggingComponent
- The module's Android Manifest must contain a meta-data entry, registering that "main" class:
<manifest ... > <application> ... <meta-data android:name="org.emsrc.logging.component.appusage" android:value="org.emsrc.logging.appusage.AppUsageLoggingComponent" /> </application> </manifest>
The name property must start with org.emsrc.logging.component. and end with a unique identifier The value property must be the "main" class which implements ILoggingComponent
- In settings.gradle you have to add the new module, so that it becomes available to the project
- Now you can include it in or more study flavors, see Section Logging Module Inclusion
WIP: Development Guidelines
- Customization through sourcesets should be used rarely (especially overriding Java classes can reduce maintainability!)
- Dependencies, permissions, ... belonging to a logging component should be implemented there. E.g. the ACCESS_WIFI permission should be requested in the logging_wifi module's AndroidManifest.xml, and not in the core's Manifest.
- use feature branch