projectindoor / projectindoorweb

Desktop application to view and analyse indoor navigation data

Project Indoor (Web)

A web application which helps to test and evaluate indoor positioning algorithms.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

To get started with development you first need to ensure a current Java JDK is installed on your System (JDK8 or later). You can get version 8 of the Java Development Kit from Oracle here or from the repository of your distribution when using Linux.

Installing

To get a basic setup you just need to clone the project and run a few commands to get started:

# Clone the project
git clone https://github.com/ProjectIndoor/projectindoorweb.git
# Go to the cloned directory
cd projectindoorweb
# Preload client (JS) dependencies
./gradlew clientInstall

This is the basic state you need to continue development. You could use any IDE compatible with gradle projects (or basically any text editor, even vim, and execute gradle from the commandline). We recommend using IntelliJ IDEA for development though.

To build the application using gradle you just have to run:

./gradlew build

To start up the application during development you can also use gralde calling:

./gradlew bootRun

The application then can be accessed with your browser on http://localhost:8080

Deployment

For deployment a Dockerfile is provided it can be used to create an image of the application. It can be build from gradle using:

./gradlew build docker

Please note that you need a working basic development setup like it is described above.

Pre build docker image releases are also available directly on docker hub, you can find more information about the image there too.

Push a new image

To publish a new image you first build it with the command above, this will create a new local version of the docker image. This can than be tagged and pushed to docker hub (see here for a detailed explanation).

# Create a tag (latest as default)
docker tag hftstuttgart/projectindoorweb hftstuttgart/projectindoorweb
# Create a tag for a versioned build (e.g. 1.0)
docker tag hftstuttgart/projectindoorweb hftstuttgart/projectindoorweb:1.0

# Push the image to docker hub (see link above to setup account)
docker push hftstuttgart/projectindoorweb

Docker-compose

To make the usage of the docker images even easier this repository also comes with an example docker-compose setup. This setup consists of three containers: mariadb, nginx and the indoor web application. To start this setup it is enough to just run in the checked out repository:

docker-compose up
# or run it in the background with
docker-compose up -d

Note that the provided compose file defines all three services to restart always.

To remove the application run, again in the repository folder:

docker-compose down

But note that the defined example volume indoor_map will be removed too with this method, so either use another volume or a path on the disk to persist them.

Documentation

Additional information about the application is available in the doc folder in this repository.

• Frontend - Structure and architecture of the frontend
• Frontend User Guide - User guide for the frontend
• Backend - Usage and architecture of the backend
• Radiomap - Information about the creation of logfiles and needed information for further processing

Built With

• Spring - The Java web framework used
• AngularJS - HTML/JavaScript framework used
• Gradle - Build tool used

Authors

This application was initially developed at the HFT Stuttgart for a software project by the students of the Software Technology Master in winter semester 17/18.

See also the list of contributors who participated in this project.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details

projectindoorweb's Issues

Implement demonstration program

The purpose of the small demonstration program to be developed is to show how reading, parsing, and saving sensor data could work using Spring Data JPA. It also serves the purpose of understanding how the previously designed ER model can be translated into POJOs in the context of Spring Data JPA.

Write JavaDoc for backend functionalities and components

Extend Floor entity to also have floorNames

A floor should also have a name e.g. "EG"

Write CRUD blackbox tests for project controller

Add descriptions to parameters

Currently, the backend provides a list of all parameters, but returns a dummy description along with each parameter. The dummy description will be replaced by a real description that shortly outlines how the parameter in question is used in the backend.

Test the parser

Testing the new CSV Parser

Add floor name during floor map upload

Method /building/addFloorToBuilding expects a floorName, it seems to not get set to the floor.

Reproduce
Call /building/addFloorToBuilding with a floorName, then call /building/getAllBuildings

What is expected
floorName of the previous set floor should be filled with the value of the first call

What happens
floorName is empty

Re-implement pre-processing steps

In order to generate radio maps, the pre-processing steps carried out by the prototype we received from our customer have to be re-implemented in the context of the entities specified by our ER model as well as the top-level interfaces specified in the source code.

Create result entity

The result entity created in scope of this task will be used to deliver the result of an algorithm run back to the frontend of the Desktop app or to the smartphone app.

Implement mechanism to give back detailed warning and error information to frontend

Implement a functionality to check what the outcome of a current function call is, map it to an associated HTTP response and return that one with the correct function result object.

Plan and implement first iteration of REST interface

Plan and implement first iteration of REST interface between Front-End and Back-End

Return error messages as json

Instead of returning plain text, provide the error messages as json responses.

Example

{
"message": "Wrong file type for radiomap file"
}

New REST Method: addFloorToBuilding

A method which allows to add a floor map and name to a building.
It should be using form-data as request type (see upload radiomap function)
Example:
[
{
"buildingIdentifier": 1,
"floorIdentifier": 1,
"floorName": "EG"
"floorMap": FILE
}
]

Add CSV Java parser library

Add a usefull csv library for java which is capable of reading and writing csv files.

Implement workflow: Create Project; generate Radiomap; calculate PositionResults

Generating a radiomap and calculating position results based on that radiomap is the workflow the prototype of our customer is able to execute. For our next meeting with him on the upcoming Monday, it is therefore important that our backend is able to carry out the same workflow -- with the addition of creating a new project and saving the radio map or a list of radio maps to the database.

Implement entities to match proposed database tables

The current state of the backend application logic will be modified so there are entity classes that match the database tables as proposed in document collection "Desktop UML".

Create persistency services for all entities concerned with creation of a Radio Map

The REST endpoint for generating a Radio Map using EVAAL log files was already set up. The business logic for creating the Radio Maps -- which is based on the pre-processing steps carried out by the customer's prototype -- exists as well. The two will be wired together in scope of this task by adding necessary JPA functionality.

Add delete methods for Projects, Buildings, Evaal files

Refactor JSON wrapper classes

The backend currently contains a couple of classes that wrap JSON requests and responses coming in and being sent out, respectively. The naming of the containing package as well as the classes themselves is not optimal, however, so they will be refactored so their naming reflects their role more appropriately.

Adjust parser component to new interface plans

Adjust the parser component and interface in a way that it is suitable to other components in this program.

Adjust REST interface to Front-end requirements

See trello task for needed changes

Fix bug that causes faulty reference positions if used evaluation file has empty POSI lines

Damn, a bug :'(

Make parameters "Lowest Considered RSSI value" and "Radio Propagation Exponent" configurable by user

Write example csv parser

Write a simple java parser example using the previously added csv parser library.

Document REST API with springfox

Use spring fox to write a dynamic REST API documentation.

Implement black box test for BuildingController

Create Developer Manual

Add Licence

Give back reference position along with calculated position, if possible

In order to compare a calculated position with the real position -- and thus to verify the correctness of the former --, the real position (available through the POSI references) will be included in the result object along with the calculated position. This can only be done if the evaluation file given as base for the position calculation contains POSI references.

Add REST endpoint to get all Evaal files

Another API enpoint is needed, it should provide a list of all evaal files (radiomap and evaluation).

Expected endpoint

/position/getAllEvaalEntries

Expected parameters
none

Expected result
An array containing evaal objects with: id, entryName, type (radiomap/evaluation), buildingName

[
  {
    "id": 1,
    "entryName": "radiomap.txt"
    "type": "radiomap"
    "buildingName": "HFT Building 2"
  },
  {
    "id": 2,
    "entryName": "evaluation.txt"
    "type": "evaluation"
    "buildingName": "HFT Building 2"
  }
]

Implement Scalar weight calculation for retrieving position results

Currently, our backend can calculate weighted positions based on a given radio map according to Euclidian distances. In scope of this task, a second calculation mode will be added that is based on Scalar positions. The reference implementation will be taken from Mr. Knauth's prototype.

Extend getAllBuildings to also send image size and floors

Old response:

[

{
"buildingName": "string",
"floorCount": 0,
"id": 0
}
]

New expected response:
[ { "buildingName": "string", "floorCount": 0, "id": 0 "floors": [ { floorNo: 0, floorName: "UG1", url: "/maps/hft_2_floor_0.png" }, { floorNo: 1, floorName: "EG", url: "/maps/hft_2_floor_1.png" } ], "imagePixelWidth" = 3688, "imagePixelHeight" = 2304 } ]

Implement transformation-class

Implement REST communication with modulated components

Implement REST communication with modulated system components.

Create CSV Parser Component

Use the CSV parsers from previous tasks to create a extensible CSV parser component.

Persistency service: Implement "Project" interaction

The persistency service will be implemented to connect the existing business functionality to a JPA-managed database and to enable REST interface functionality to work with "real" objects.

Implement black box test for PositioningController

Use environment variables for temporary and peristent Files

Current state
Currently temporary files, which are created during processing of radiomap/evaluation files, are placed in the working directory (e.g. the project root folder during development).
Floor map uploads are persisted in ./src/main/resources/static/floor_maps

Problem
Temporary files are not deleted and sum up, but are not needed anymore.
The location of persistent floor_maps depends on the working directory, so it may change between calls.

Proposed Solution
Use springs properties mechanism to get paths for the systems TEMP folders for temporary files and define an environment variable for the application.properties file which points to an floor_map directory (e.g. $HOME/.floor_map).
Default location of properties file: src/main/resources/application.properties

Additional references
Spring documentation: https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html

Add project id parameter to file processing methods

Add an optional project id parameter to the following REST calls and save it in the database if available:

• generateBatchPositionResult
• generateSinglePositionResult

Connect REST interface to backend

Connect the finished REST interface to the backend in a way that correct solutions are published based on incoming requests.

Extend demonstration program

The existing demonstration program is to be extended so it will have the following functionality until Friday, October 27th 2017:

• Parse all categories of sensor data and persist them to a database. For the time being, this can still be an in-memory database.
• Read floor maps provided in the sample data and persist them to a database.

Adapt pre-processing steps to new entities

The pre-processing steps carried out by our current backend application logic will be adapted to the newly created entities (see attached Trello task).

Modifie getAllAlgorithms method to also return algorithm parameters

Remove getAlgorithmParameterListForAlgorithmId method and return all parameters in getAllAlgorithms instead.

Extend REST interface

1. getBuildings(/) Return List Building: buildingId, Name, floorCount
2. getEvaluationEntries(buildingId)Return List Entry: Name, logFileId
3. getAlgorithmTypes()Return List AlgorithmType:ClassName, Nicename
4. getAlgorithmParamterList(AlgorithmId)Return: List->Parametertype: Name, type
5. AddBuilding(buildingName, numberOfFloors, SoutWestAnchor, SouthEastAnchor, NorthEastAnchor, NorthWerst -> Position mit Longitude and Lattitude)

Extend REST interface to accept "empty" log file (file with POSI references where LatLong is not given)

In scope of this task, another method "processRadioMaps()" will be added that accepts a radio map file with "empty" POSI references along with a list of transformed points. Internally, this method will call one of Gerald's utility methods (see attached Trello task) to calculate the position of each POSI reference in Latitude and Longitude based on the list of transformed points.

Re-implement Wifi algorithm

In scope of this task, the Wifi algorithm contained in Mr. Knauth's prototype will be re-implemented using the classes available in the 'entities' package.

Include new parameter to control assignment of reference positions

Include Gerald's transformation methods to calculate Building corner points out of Building reference position

Response of getAllProjects should contain buildingIds

The response of the said endpoint contains the building name but not the id, but I need to have the id in order to fetch the floors of this building.

It would be great, if the response project model could be extended by the property buildingId.

Rework CRUD operations for entity "Project"

CRUD operations fot "Project" entities were already included in the backend, but due to the recently added, new work flow, they are out of date. In scope of this task, the CRUD operations will thus be reworked so they fully accommodate for our new workflow.