diff --git a/README.md b/README.md index 5733234c..ae4da09a 100644 --- a/README.md +++ b/README.md @@ -33,33 +33,17 @@ Screenshots Development setup ----------------- -The App is developed using Android Studio. +The App is developed using Android Studio and should pretty much work out-of-the-box when you clone +the Git repository and open the project with Android Studio. -For testing the app, you need to obtain free API Keys for the -[GoingElectric API](https://www.goingelectric.de/stromtankstellen/api/), -the [Chargeprice API](https://github.com/chargeprice/chargeprice-api-docs), -the [OpenChargeMap API](https://openchargemap.org/site/profile/appedit), -as well as for [Google APIs](https://console.developers.google.com/) -("Maps SDK for Android" and "Places API" need to be activated) and/or [Mapbox](https://www.mapbox.com/). These API keys need to be put into the -app in the form of a resource file called `apikeys.xml` under `app/src/main/res/values`, with the -following content: +The only exception is that you need to obtain some free API keys for the different data sources that +EVMap uses and put them into the app in the form of a resource file called `apikeys.xml` under +`app/src/main/res/values`. You can find more information on which API keys are necessary for which +features and how they can be obtained in our [documentation page](docs/api_keys.md). -```xml - - - insert your Google Maps key here - - - insert your Mapbox key here - - - insert your GoingElectric key here - - - insert your Chargeprice key here - - - insert your OpenChargeMap key here - - -``` +There are two different build flavors, `google` and `foss`, where only the `google` variant uses +Google Maps data and provides the Android Auto integration. The `foss` variant only uses Mapbox data +and should run on devices without Google Play Services. + +We also have a special [documentation page](docs/android_auto.md) on how to test the Android Auto +app. diff --git a/doc/android_auto.md b/doc/android_auto.md new file mode 100644 index 00000000..fe3c76f3 --- /dev/null +++ b/doc/android_auto.md @@ -0,0 +1,75 @@ +Testing EVMap on Android Auto +============================= + +In addition to the Android app on the phone, EVMap is also available as an Android Auto app built +using the [Android for Cars App Library](https://developer.android.com/training/cars/apps). The +Android Auto app is only available in the `google` build flavor of the app, and thus its code is +located in the `app/src/google/java` directory under the `net.vonforst.evmap.auto` package. + +This page contains instructions on how to test the Android Auto app using the Desktop Head Unit +(DHU). + +Further information about testing Android Auto apps is also available on the +[Android Developers site](https://developer.android.com/training/cars/testing). + +Install the Desktop Head Unit +----------------------------- + +Refer to the instructions on the +[Android Developers site](https://developer.android.com/training/cars/testing#install) +to install the DHU 2.0 using the SDK manager. + +Install Android Auto +-------------------- + +If you haven't already, install the +[Android Auto](https://play.google.com/store/apps/details?id=com.google.android.projection.gearhead) +and +[Android Auto for phone screens](https://play.google.com/store/apps/details?id=com.google.android.projection.gearhead.phonescreen) +apps on your test device from the Google Play Store. + +If you are using the Android Emulator, the Play Store may show the Android Auto app as incompatible. +In that case, download the APK for the newest version from a site like +[APKMirror](https://www.apkmirror.com/apk/google-inc/android-auto/) +(choosing the correct architecture for your emulator - x86_64, x86 or ARM) +and drag it onto the running emulator window to install. + +Starting the DHU +---------------- +(see also the corresponding section on +the [Android Developers site](https://developer.android.com/training/cars/testing#running-dhu)) + +1. Start the Android Auto for phone screens app, tap the menu icon on the top left to go to settings +2. Scroll all the way down to the app version, tap it 10 times +3. Click *OK* in the dialog that appears to enable developer mode +4. In the menu on the top left, tap *Start head unit server* +5. On your computer, run the following command to set up the required port forwarding: + ```shell + adb forward tcp:5277 tcp:5277 + ``` +6. Start the DHU by running the command `desktop-head-unit.exe` (on Windows) or + `./desktop-head-unit` (on macOS or Linux) in a console window from the + `SDK_LOCATION/extras/google/auto/` directory. + +The desktop head unit should appear and show the Android Auto interface. If this is the first time +the Android device is connected to the DHU, you may need to open the Android Auto app again on the +phone to accept some permissions before the connection can succeed. + +Testing EVMap on the DHU +------------------------ + +Make sure that you have selected the `googleDebug` variant in the *Build Variants* tool window in +Android Studio (the `foss` variants do not contain the Android Auto app). Then, install the app on +your phone - if the DHU is connected, the app should also automatically appear in the apps menu on +Android Auto. + +For testing features that require car sensors, you need to start the DHU with the option +`-c config/default_sensors.ini` to select a configuration file that enables these sensors. From the +console, you can then type certain commands to update the data of these sensors, such as: + +```shell +location 54.0 9.0 # latitude, longitude +fuel 50 # percentage +range 100 # in kilometers +speed 28 # in m/s +``` diff --git a/doc/api_keys.md b/doc/api_keys.md new file mode 100644 index 00000000..7deacef4 --- /dev/null +++ b/doc/api_keys.md @@ -0,0 +1,165 @@ +API keys required for testing EVMap +=================================== + +EVMap uses multiple different data sources, most of which require an API key. These API keys need to +be put into the app in the form of a resource file called `apikeys.xml` under +`app/src/main/res/values`, with the following content: + +
+apikeys.xml content + +```xml + + + + insert your Google Maps key here + + + insert your Mapbox key here + + + insert your GoingElectric key here + + + insert your Chargeprice key here + + + insert your OpenChargeMap key here + + +``` + +
+ +Not all API keys are strictly required if you only want to work on certain parts of the app. For +example, you can choose only one of the map providers and one of the charging station databases. The +Chargeprice API key is also only required if you want to test the price comparison feature. + +All API keys are available for free. Some APIs require payment above a certain limit, but the free +tier should be plenty for local testing and development. + +Below you find a list of all the services and how to obtain the API keys. + +Map providers +------------- + +The different Map SDKs are wrapped by our [fork](https://github.com/johan12345/AnyMaps) of the +[AnyMaps](https://github.com/sharenowTech/AnyMaps) library to provide a common API. The `google` +build flavor of the app includes both Google Maps and Mapbox and allows the user to switch between +the two, while the `foss` flavor only includes the Mapbox SDK. + +> ⚠️ When testing the app using the Android Emulator, we recommend using Google Maps and not Mapbox, as the latter has +[issues displaying the markers](https://github.com/mapbox/mapbox-gl-native/issues/10829). It works fine on real Android devices. + +### Google Maps + +[Maps SDK for Android](https://developers.google.com/maps/documentation/android-sdk/overview) ++ [Places API](https://developers.google.com/maps/documentation/places/android-sdk/overview) + +
+How to obtain an API key + +1. Log in to the [Google API console](https://console.developers.google.com/) with your Google + account +2. Create a new project, or select an existing one that you want to use +3. Under *APIs & Services → Library*, enable + the [Maps SDK for Android](https://console.cloud.google.com/apis/library/maps-android-backend.googleapis.com) + and [Places API](https://console.cloud.google.com/apis/library/places-backend.googleapis.com). +4. Under *APIs & Services → Credentials*, click on *Create credentials → API Key* +5. Copy the displayed key to your `apikeys.xml` file. + +
+ +### Mapbox + +[Maps SDK for Android](https://docs.mapbox.com/android/maps) + +
+How to obtain an API key + +1. [Sign up](https://account.mapbox.com/auth/signup) for a Mapbox account +2. Under [Access Tokens](https://account.mapbox.com/access-tokens/), create a new access token +3. Set a name for the scope and enable only the preselected public scopes. Do not restrict the token + to a specific URL (this setting is not compatible with Android apps) + +
+ + +Charging station databases +-------------------------- + +### **GoingElectric.de** + +GoingElectric.de provides an [API](https://www.goingelectric.de/stromtankstellen/api/) for their +community-maintained directory of charging stations. The website and data are mostly only available +in German. + +
+How to obtain an API key + +1. [Sign up](https://www.goingelectric.de/forum/ucp.php?mode=register) for an account in the + GoingElectric.de forum. The registration page can be switched to English using the dropdown menu + under "Sprache". Then, agree to the registration terms. +2. Fill in your desired username, password and email address and submit the registration form. You + do not need to fill the information under *GoingElectric Usermap*. +3. Verify your account by clicking on the link in the email you received +4. [Log in](https://www.goingelectric.de/forum/ucp.php?mode=login) to the GoingElectric forum +5. Go to [this link](https://www.goingelectric.de/stromtankstellen/api/new/) to request access to + the API. This page is only available in German. You need to fill in the following data: + - name / company (*Name / Firma*) + - street address (*Straße, Nr.*) + - postal code, town (*Postleitzahl, Ort*) + - country (*Land*) + - email address (*E-Mail Adresse*) + - website (*Webseite*, optional) + - phone number (*Telefonnummer*, optional) + - name of the app (*Name der App*): EVMap + - app website (*Webseite der App*): https://github.com/johan12345/EVMap + - description (*kurze Beschreibung der App*): please explain that you would like to contribute to + the development of EVMap and therefore need access to the GoingElectric.de API. + - Referrer (*Herkunft*): leave this field blank! +6. When your access to the API is approved, you can access the + [API console](https://www.goingelectric.de/stromtankstellen/api/ucp/) to retrieve your API key. + +
+ +### **OpenChargeMap** + +[API documentation](https://openchargemap.org/site/develop/api) + +
+How to obtain an API key + +1. [Sign up](https://openchargemap.org/site/loginprovider/register) for an account at OpenChargeMap +2. Go to the [My Apps](https://openchargemap.org/site/profile/applications) page and click + *Register an application* +3. Enter the name of the app (EVMap) and website (https://github.com/johan12345/EVMap), and in the + description field describe that you would like to contribute to the development of EVMap and + therefore need access to the OpenChargeMap API. Do not tick the *List App in Public Showcase* + box. Then, click *save*. +4. Your API key will appear on the + [My Apps](https://openchargemap.org/site/profile/applications) page. + +
+ +Pricing providers +----------------- + +### Chargeprice.app + +[API documentation](https://github.com/chargeprice/chargeprice-api-docs) + +
+How to obtain an API key + +1. Check the + [Pricing page](https://github.com/chargeprice/chargeprice-api-docs/blob/master/plans.md) + for information on the current plans at Chargeprice. There should be a free tier up to a certain + limit of API calls per month. +2. Contact [contact@chargeprice.net](mailto:contact@chargeprice.net), stating that you would like to + contribute to the development the open source EVMap app and therefore need access to the + Chargeprice API for testing. +3. When your access to the API is approved, you will receive an API key via email. + +
+