mirror/EVMap
1
0
Fork 0
mirror of https://github.com/ev-map/EVMap.git synced 2026-04-23 23:57:08 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve docs for first-time contributors

Browse Source 
adds two docs pages with info on API keys and Android Auto testing.
fixes #112
This commit is contained in:
johan12345
2021-10-17 13:59:54 +02:00
parent 123680d3e8
commit 8331f92f10
3 changed files with 252 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@@ -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
<resources>
<string name="google_maps_key" templateMergeStrategy="preserve" translatable="false">
insert your Google Maps key here
</string>
<string name="mapbox_key" translatable="false">
insert your Mapbox key here
</string>
<string name="goingelectric_key" translatable="false">
insert your GoingElectric key here
</string>
<string name="chargeprice_key" translatable="false">
insert your Chargeprice key here
</string>
<string name="openchargemap_key" translatable="false">
insert your OpenChargeMap key here
</string>
</resources>
```
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.

75
doc/android_auto.md Normal file
View File

@@ -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
```

165
doc/api_keys.md Normal file
View File

@@ -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:
<details>
<summary>apikeys.xml content</summary>
```xml
<resources>
<string name="google_maps_key" templateMergeStrategy="preserve" translatable="false">
insert your Google Maps key here
</string>
<string name="mapbox_key" translatable="false">
insert your Mapbox key here
</string>
<string name="goingelectric_key" translatable="false">
insert your GoingElectric key here
</string>
<string name="chargeprice_key" translatable="false">
insert your Chargeprice key here
</string>
<string name="openchargemap_key" translatable="false">
insert your OpenChargeMap key here
</string>
</resources>
```
</details>
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)
<details>
<summary>How to obtain an API key</summary>
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.
</details>
### Mapbox
[Maps SDK for Android](https://docs.mapbox.com/android/maps)
<details>
<summary>How to obtain an API key</summary>
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)
</details>
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.
<details>
<summary>How to obtain an API key</summary>
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.
</details>
### **OpenChargeMap**
[API documentation](https://openchargemap.org/site/develop/api)
<details>
<summary>How to obtain an API key</summary>
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.
</details>
Pricing providers
-----------------
### Chargeprice.app
[API documentation](https://github.com/chargeprice/chargeprice-api-docs)
<details>
<summary>How to obtain an API key</summary>
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.
</details>