Help
===============

1) Introduction

The OK Lab Stuttgart has a project to build fine particulate matter sensors by yourself. The data can then be sent to the database of https://Luftdaten.Info. This app shows you data from this network. To do so, it is not necessary to operate an own sensor.

Multiple sensor types are part of this network. This app focuses on displaying the follwing parameters:

- fine particulate matter,
- temperature and humidity.

Often, a sensor collects multiple parameters.

2) Short manual

a) Fine particulate matter values close to you („mobile“)

After installation, you should launch the app. The app may ask you for permission to access your location. Then, you will be asked in a green field if you want to load a list of known sensors. Both is necessary if the app should display fine particulate matter concentrations close to you.

Make sure you have a data connection available, e.g. WiFi. Tap on the button labeled „Load sensor locations“. While loading the sensor list, you should not terminate the app. Otherwise, the list cannot be loaded successfully. The app will indicate the progress.

As soon as the list has been loaded successfully, turn on your location service if applicable.

The fine particulate matter values should be displayed to you shortly thereafter.

This functionality can also be displayed on your home screen using a widget.

If you like to view the temperature and humidity instead of fine partuculate matter, you can use a switch in the upper right corner of the display to do so.

b) Monitor a certain sensor continuously („local“)

Besides fine particulate matter, a sensor often also measures temperature and humidity. The app can monitor all three parameters. You can alternatively select two sensors to display their fine particulate matter or temperature and humidity values.

To select the sensors, you can tap on a sensor number in the mobile display. An information screen will pop up. By using the buttons, you can set this sensor to be the local sensor number 1 or 2.

Alternatively, you can enter the sensor numbers manually. To do so, go to the settings and chose „Setup local sensors“. You can now enter the sensor numbers manually. Unless disabled in the settings, the app will try to determine the corresponding temperature and humidity sensor. If this fails, the app will try to determine the next close sensor.

This screen has further settings for widgets, see 4).

3) Displaying the measured data

This app has two basic functions to display fine particulate matter concentrations. The are called "mobile" and "local".

MOBILE: the app shows you data of the next sensors close to you.

LOCAL: the app shows you the data of two permanently entered sensors. Here, you can enter your own sensor or a sensor close to you.

When tapping on a sensor number in the mobile display or tapping on the chart in the local display, more detailed information about this sensor will be shown.

The app focuses on displaying the measured data using widgets on the home screen. Widgets are tools that can be used to individually style your home screen and to extend it with functions.

The app provides three widgets:
- a large widget that displays the sensor data close to you
- a small text widget that displays data of a local sensor
- a large widget that displays the measured data of a local sensor in a chart over 24h

The app looks up the measured data of the local sensor continously if at least one of the latter two widgets is placed on your home screen. Otherwise, the app will not collect any measured data automatically.

4) Detailed widget settings

It depends on your installed system how a widget is placed on the home screen. Commonly, you do the following:

Go to the home screen. This is the screen that pops up after you start your device. Tap a little longer on a piece of free space. A selection should appear that is named „widgets“. Tap it and select the widget, you may have to scroll to find it. The widget has to be tapped longer and – without taking your finger from the screen – moved to the desired location on your home screen.

When you have chosen one of the widgets displaying local sensor data, a screen will pop up. You may have to enter sensor numbers here. You can change some further settings here:

a) „connect the measured values with lines“

Instead of displaying points (what is scientifically more accurate), the measured values can also be connected with lines.

b) „use dark widget theme“

The widget can be displayed in a dark-on-bright theme. This is especially useful when the background is very bright or very colorful.

c) „show compact values in large widget“

This option reduces text size slightly and displays the measured values in two (instead of three) lines.

d) „widget opacity“

Here, you can set the opacity of the widget. A value of 100% means a widget without any displayed transparency.

To place the widget, you have to close this screen by pressing the „continue“ button at the very bottom.

Changes in the settings may get applied with a delay until the widget gets updated. Ff the automatic update does not succeed, you may try manually by tapping on the widget.

The size of all widgets may be modified.

5) How does the app collect data?

The app gets the data from the API (application programming interface) at https://luftdaten.info. If at least one widget for local sensor data is placed on the home screen, each local widget type polls sensor data every 30 minutes.

To update the data, just tap on the widget.

To display the mobile data, the app is querying your location and updates the display if necessary. You can specify in the settings when and how often this is done.

6) The widget does not get updated continously

This may have multiple reasons:

- Make sure that you have internet connection. If your device loses internet connection, especially in sleep mode, the widget will not get updated continuously. Sometimes, internet connection can be brittle, especially Wi-Fi connections. You may try changing the option "Keep Wi-Fi on during sleep" to "Always" in the Wi-Fi settings.

- A "security app" may have blocked the internet access.

- A "battery-saving" app may prevent the updates.

Privacy
======

Summary: the app determines your location to identify the sensors close to you. To load the measured data of these sensors, sensor numbers are sent to the API at https://luftdaten.info. To do so, your IP address has to be sent to https://luftdaten.info within the context of the internet connection so that the measured data may be sent to you.

If you save and/or share measured values as images, they may include your location combined with the date and time. Other apps on your device may access these images.

In detail:

1) the app needs the following permissions:

- INTERNET: this permission is needed to load data from https://luftdaten.info.
- ACCESS_FINE_LOCATION: this permission is needed to determine your location and the next sensors close to you.
- READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE: this permission is needed to save mesured data locally in images and to share them.

2) What data does the app store?

The app stores locally:

a) a list of known sensors

At the first launch, the app asks you to load this list. This list can be re-loaded from the app settings. This list gets deleted when the app data is being deleted and/or the app is deinstalled.

b) measured values including information about the sensors who measured them

The app stores measured data (and corresponding sensor information) over 24 hours. As soon as a widget gets updated or the app is launched, all measured values older than 24 hours will be deleted. Please note that this clean-up is only done if a widget gets updated and/or the app gets launched. This data is also deleted when the app data is deleted and/or the app is deinstalled.

c) data manually saved and shared as images

The app provides a feature to save measured data as images and to share them.

When you share an image with measured data, this image is always also saved locally on your device. The images are not put inside the app, but in the generally accessible storage (also called “internal/external storage”) of your device. This way, for example, you can also access the images with the gallery. Other apps on your device can also access these images.

Please note that the saved images may include your location, the date and the time. This may be sensitive information.

The saved images are not deleted automatically. They are also not deleted when the app data is deleted and/or the app is uninstalled.

The images are placed in a sub-folder of the folder where your device saves pictures. There, they can be deleted manually with the file manager, for example.

3) What data is sent by the app?

The app sends sensor numbers to the API at https://luftdaten.info to get measured values. To do so, your IP address must be sent to the API at https://luftdaten.info in the context of the internet connection.

When you load the list of known sensors, your IP address needs to be sent to the  API at https://luftdaten.info in the context of the internet connection.

In detail:

Should you have granted the app the permission to determine your location, your location is used to determine the next close sensors using the list of known sensors locally on your device.

The app sends the locally determined sensor numbers to the API at https://luftdaten.info in order to get the measured values.

The app also sends the sensor numbers of the „local“ sensors to the API at https://luftdaten.info in order to get the measured values.

The data transfer between the app and the API at https://luftdaten.info is done encrypted using the HTTPS protocol. Please note: to query the sensor data, your IP-address is being sent in the context of the internet connection to https://luftdaten.info, so that the sensor data can be sent to you.

Besides the sensor numbers, which are sent to the API at https://luftdaten.info, no other data is sent by the app automatically.

In particular, no location data and no measured values are automatically shared and/or sent.

This only happens if you save and/or share images with measured values: doing so, you save your location data (with the date and time) locally on your device as an image and share it in the way you decided by yourself.

4) Miscellaneous

In some cases, more sensors are queried than displayed. The reason is, that some sensors do not always present current data. If a sensor does not present any data at the moment, it is being ignored in the display.

To determine the location, the app also uses the last known location. The app displays the time when this location has been determined. Especially when moving quickly, this position may be older and may not correspond to your current location. As soon as the location changes, the app and/or the mobile widget gets updated accordingly. When no location information is available, it can take a while until the device successfully determines the location. A green bar points at this fact.

How can I contribute?
=================

Tell the author any errors/bugs, problems and suggestions. You can do so on the project site found on https://codeberg.org or by email ( pawel@kaffeemitkoffein.de ).