Prepare for publishing

- Added README
- Added proper javadoc comments

README.md

@@ -0,0 +1,88 @@
+# SensorReadoutApp
+Simple Android-App for the collection of sensor data, Wifi-Scans, Bluetooth-Scans, and Wifi RTT.
+
+Additionally to the collection of raw sensor data, the app also allows the user to do manual tagging within the data, such as the currently performed activity, or "ground truth" points, which allow to map a recording to a certain pre-defined path.
+
+## File-Format:
+The file format used by the application is based on events.
+Each incomming sensor value is mapped to its corresponding EventId, and logged to the csv-like file using the components:
+- Nano-Timestamp (original timestamp reported by the Android sensor subsystem)
+- EventId
+- Dynamic amount of parameters, separated by the csv-separator
+
+For a list of EventIds and their meaning, have a look at `SensorType.java`.
+
+### Example:
+```csv
+0;-2;Wed Apr 08 15:35:20 GMT+02:00 2020;Markus;FHWS
+0;50;STANDING;1
+51272330;0;-0.30166942;4.3526587;8.734048
+51272330;3;0.064983115;-0.23649593;0.16192514
+56328330;0;-0.34955344;4.343082;8.456321
+56328330;3;0.064983115;-0.23223473;0.15872924
+56328330;1;-0.112231635;0.048184782;9.805753
+56328330;2;-0.23463176;4.2904096;-1.3455414
+61368330;0;-0.22505496;4.4101195;8.121132
+61368330;3;0.06604841;-0.21732058;0.14807628
+61368330;12;0.1907712;-0.15619373;-0.6493728;0.71935177
+66408330;0;-0.20111294;4.486734;7.896077
+66408330;3;0.064983115;-0.17790459;0.1384886
+66408330;12;0.19772942;-0.16232795;-0.6445509;0.72045046
+66408330;18;0.2370983;-0.09607227;-0.40076905
+66408330;1;-0.20620692;4.8463116;8.52272
+66408330;2;0.0047884034;-0.35913026;-0.62249243
+```
+
+| Nano Timestamp | EventId | Arg0 | Arg1 | Arg2 | Arg3 | ... |
+|:--------------:|:-------:|:----------------------------------:|:-----------:|:-----------:|:----------:|-----|
+| 0 | -2 | Wed Apr 08 15:35:20 GMT+02:00 2020 | Markus | FHWS |  |  |
+| 0 | 50 | STANDING | 1 |  |  |  |
+| 51272330 | 0 | -0.30166942 | 4.3526587 | 8.734048 |  |  |
+| 51272330 | 3 | 0.064983115 | -0.23649593 | 0.16192514 |  |  |
+| 56328330 | 1 | -0.112231635 | 0.048184782 | 9.805753 |  |  |
+| 56328330 | 2 | -0.23463176 | 4.2904096 | -1.3455414 |  |  |
+| 61368330 | 3 | 0.06604841 | -0.21732058 | 0.14807628 |  |  |
+| 61368330 | 12 | 0.1907712 | -0.15619373 | -0.6493728 | 0.71935177 |  |
+| 66408330 | 0 | -0.20111294 | 4.486734 | 7.896077 |  |  |
+| 66408330 | 12 | 0.19772942 | -0.16232795 | -0.6445509 | 0.72045046 |  |
+| 66408330 | 18 | 0.2370983 | -0.09607227 | -0.40076905 |  |  |
+
+
+## Supported Sensors:
+- Accelerometer
+- Gravity
+- Linear Acceleration (without Gravity)
+- Gyroscope
+- MagneticField
+- Pressure
+- Orientation (New / Old)
+- Rotation Matrix
+- Wifi (Access-Point advertisements with RSSI)
+- Bluetooth (Beacon Advertisements with RSSI)
+- Relative Humidity
+- Rotation Vector
+- Light
+- Ambient Temperature
+- GPS
+- Wifi RTT
+- Game Rotation Vector
+
+## Supported User-Tagging
+Additionally to the collection of sensor values, the app also supports some functions for user-tagging of the data while recording.
+
+### Currently performed activity
+The application allows the user to tag the activity he is currently performing.
+The full set of currently supported activities is:
+- Walking
+- Standing
+- Stairs Up
+- Stairs Down
+- Elevator Up
+- Elevator Down
+- Messing Around
+- Ground-Truth points
+
+### Ground-Truth points
+If the path to walk is pre-defined, it can be helpful to mark certain "key-points" of "ground-truth" points on the floor, so the user can tell the app when he passed such a point.
+
+This allows to map a recording onto the pre-defined path later on, by matching the key-points and interpolating between them.

app/src/main/java/de/fhws/indoor/sensorreadout/MainActivity.java

@@ -39,7 +39,6 @@ import de.fhws.indoor.sensorreadout.loggers.OrderedLogger;
 import de.fhws.indoor.sensorreadout.sensors.GpsNew;
 import de.fhws.indoor.sensorreadout.sensors.GroundTruth;
 import de.fhws.indoor.sensorreadout.sensors.PedestrianActivity;
-import de.fhws.indoor.sensorreadout.sensors.PedestrianActivityButton;
 import de.fhws.indoor.sensorreadout.sensors.PhoneSensors;
 import de.fhws.indoor.sensorreadout.sensors.WiFi;
 import de.fhws.indoor.sensorreadout.sensors.WiFiRTT;

app/src/main/java/de/fhws/indoor/sensorreadout/MetadataFragment.java

@@ -14,6 +14,9 @@ import androidx.fragment.app.DialogFragment;
 import androidx.fragment.app.FragmentManager;
 import androidx.fragment.app.FragmentTransaction;
 
+/**
+ * @author Markus Ebner
+ */
 public class MetadataFragment extends DialogFragment {
 
     public interface ResultListener {

app/src/main/java/de/fhws/indoor/sensorreadout/MyException.java

@@ -6,9 +6,8 @@ import de.fhws.indoor.sensorreadout.MainActivity;
 import de.fhws.indoor.sensorreadout.R;
 
 /**
- * Created by Frank on 05.06.2016.
+ * @author Frank Ebner
  */
-
 public class MyException extends RuntimeException {
 
     public MyException(final String err, final Throwable t) {

app/src/main/java/de/fhws/indoor/sensorreadout/PedestrianActivityButton.java

@@ -1,4 +1,4 @@
-package de.fhws.indoor.sensorreadout.sensors;
+package de.fhws.indoor.sensorreadout;
 
 import android.content.Context;
 import android.graphics.Color;
@@ -9,12 +9,18 @@ import android.widget.LinearLayout;
 import android.widget.TextView;
 
 import de.fhws.indoor.sensorreadout.R;
+import de.fhws.indoor.sensorreadout.sensors.PedestrianActivity;
 
 /**
- * Created by toni on 10/01/18.
+ * Button used in the UI to represent a specific activity.
- * Extended by Markus on 19/06/19
+ * <p>
+ *     These buttons are used by the user to live-tag the recording with information about the
+ *     currently performed physical activity.
+ * </p>
+ *
+ * @author Toni Fetzer
+ * @author Markus Ebner
  */
-
 public class PedestrianActivityButton extends LinearLayout {
 
     private LinearLayout innerBtn;

app/src/main/java/de/fhws/indoor/sensorreadout/SettingsActivity.java

@@ -3,6 +3,9 @@ package de.fhws.indoor.sensorreadout;
 import androidx.appcompat.app.AppCompatActivity;
 import android.os.Bundle;
 
+/**
+ * @author Markus Ebner
+ */
 public class SettingsActivity extends AppCompatActivity {
 
     @Override

app/src/main/java/de/fhws/indoor/sensorreadout/SettingsFragment.java

@@ -6,6 +6,9 @@ import androidx.preference.SwitchPreferenceCompat;
 
 import de.fhws.indoor.sensorreadout.sensors.WiFiRTT;
 
+/**
+ * @author Markus Ebner
+ */
 public class SettingsFragment extends PreferenceFragmentCompat {
 
     @Override

app/src/main/java/de/fhws/indoor/sensorreadout/loggers/Logger.java

@@ -11,6 +11,13 @@ import java.util.concurrent.atomic.AtomicLong;
 
 import de.fhws.indoor.sensorreadout.sensors.SensorType;
 
+/**
+ * Base-Class for all Logger implementations.
+ * <p>
+ *     This class defines the public interface of all logging implementations.
+ * </p>
+ * @author Markus Ebner
+ */
 public abstract class Logger {
 
     public static final long BEGINNING_TS = -1;

app/src/main/java/de/fhws/indoor/sensorreadout/loggers/LoggerRAM.java

@@ -14,10 +14,15 @@ import de.fhws.indoor.sensorreadout.MyException;
 import de.fhws.indoor.sensorreadout.sensors.SensorType;
 
 /**
- * log sensor data to RAM
+ * Simple (ordered) RAM Logger.
- * only flush to file when finished
+ * <p>
+ *     This logger stores all events in memory first.
+ *     Only when the logger is stopped does it sort them and flush them to the logfile.
  *
- * WARNING: overflows RAM on some smartphones, with large recordings
+ *     WARNING: This overflows the RAM if the recording gets too long.
+ *     If this happens, all the data is gone.
+ * </p>
+ * @author Frank Ebner
  */
 public final class LoggerRAM extends Logger {
 

app/src/main/java/de/fhws/indoor/sensorreadout/loggers/OrderedLogger.java

@@ -16,8 +16,12 @@ import java.util.concurrent.atomic.AtomicInteger;
 import de.fhws.indoor.sensorreadout.MyException;
 
 /**
- * live-reorder logged sensor data, and write to file
+ * Live (ordered) logger.
- * Created by Markus on 07.04.2020.
+ * <p>
+ *     This logger contains an internal caching structure that regularly sorts the contained entries
+ *     and commits the oldest ones to the logfile using the correct order.
+ * </p>
+ * @author Markus Ebner
  */
 public final class OrderedLogger extends Logger {
 

app/src/main/java/de/fhws/indoor/sensorreadout/loggers/UnorderedLogger.java

@@ -11,10 +11,15 @@ import java.util.concurrent.ArrayBlockingQueue;
 import de.fhws.indoor.sensorreadout.MyException;
 
 /**
- * log sensor data to file
+ * Live (unordered) Logger.
- * Created by Frank on 25.03.2015.
+ * <p>
- * Re-Written by Markus on 20.06.2019.
+ *     This logger takes the incomming events and commits them to the logfile in a background thread.
- * Re-Written by Markus on 07.04.2020.
+ *
+ *     WARNING: This produces files with non-monotonic increasing timestamps.
+ *     Reordering is required on the parser-side, or as post-processing step.
+ * </p>
+ * @author Frank Ebner
+ * @author Markus Ebner
  */
 public final class UnorderedLogger extends Logger {
 

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/Gps.java

@@ -15,7 +15,7 @@ import androidx.core.content.ContextCompat;
 import de.fhws.indoor.sensorreadout.MyException;
 
 /**
- * Created by student on 20.03.17.
+ * GPS sensor.
  */
 @TargetApi(23)
 public class Gps extends mySensor implements LocationListener {

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/GroundTruth.java

@@ -4,7 +4,11 @@ import android.app.Activity;
 import android.os.SystemClock;
 
 /**
- * Created by Toni on 02.06.2015.
+ * Virtual Ground-Truth sensor
+ * <p>
+ *     This sensor inserts the ground-truth events generated by user-interaction.
+ * </p>
+ * @author Toni Fetzer
  */
 public class GroundTruth extends mySensor {
 

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/Helper.java

@@ -1,9 +1,8 @@
 package de.fhws.indoor.sensorreadout.sensors;
 
 /**
- * Created by Frank on 05.06.2016.
+ * @author Frank Ebner
  */
-
 public class Helper {
 
     /** remove all ":" within the MAC to reduce file footprint */

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/PedestrianActivity.java

@@ -1,9 +1,9 @@
 package de.fhws.indoor.sensorreadout.sensors;
 
 /**
- * Created by toni on 10/01/18.
+ * Enum mapping all supported Activities to their ids.
+ * @author Toni Fetzer
  */
-
 public enum PedestrianActivity {
 
     WALK(0),

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/PhoneSensors.java

@@ -16,9 +16,14 @@ import java.io.IOException;
 import de.fhws.indoor.sensorreadout.loggers.DataFolder;
 
 /**
- * all available sensors
+ * Sensor that surfaces all Sensors a phone has.
- * and what to do within one class
+ * <p>
+ *     While the term "sensor" is used for all implementations, such as Wifi and iBeacon, the term
+ *     "sensor" in this context actually refers to a smartphone's sensors, such as
+ *     Accelerometer, Gyroscope, MagneticField, Light, Pressure, ...
  *
+ *     This Sensor implementation exports all sensors supported by the smartphone.
+ * </p>
  *
  * Created by Toni on 25.03.2015.
  */

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/SensorType.java

@@ -1,7 +1,10 @@
 package de.fhws.indoor.sensorreadout.sensors;
 
 /**
- * Created by toni on 02/06/16.
+ * Enum mapping all supported events in the logfile to their corresponding ids.
+ *
+ * @author Toni Fetzer
+ * @author Frank Ebner
  */
 public enum SensorType {
 

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/WiFi.java

@@ -16,7 +16,8 @@ import de.fhws.indoor.sensorreadout.MyException;
 
 
 /**
- * Created by Frank on 25.03.2015.
+ * Wifi sensor exporting scan/advertisement events.
+ * @author Frank Ebner
  */
 public class WiFi extends mySensor {
 

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/WiFiRTT.java

@@ -24,6 +24,10 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.Executor;
 
+/**
+ * Wifi RTT sensor exporting time-of-flight measurements.
+ * @author Markus Bullmann
+ */
 public class WiFiRTT extends mySensor {
 
     private final Activity act;

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/iBeacon.java

@@ -16,7 +16,8 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Created by Frank on 25.03.2015.
+ * Bluetooth iBeacon sensor.
+ * @author Frank Ebner
  */
 public class iBeacon extends mySensor {
 

app/src/main/java/de/fhws/indoor/sensorreadout/sensors/mySensor.java

@@ -3,9 +3,9 @@ package de.fhws.indoor.sensorreadout.sensors;
 import android.app.Activity;
 
 /**
- * base-class for all Sensors
+ * Base-class for all Sensors
  *
- * Created by Frank on 25.03.2015.
+ * @author Frank Ebner
  */
 public abstract class mySensor {