App4hab control server overview

App4hab server is a RESTapi server allowing remote control of App4hab installation. It allows users for remotely turning on and off application modules to save battery life and check if the app works as it should.

The server was designed to be easy to install for non-specialist users with little technology background, however basic uderstanding of IT is required.

How it works

The app was designed to simplify the installation and deployment process as much as possible, thus some aspects, for example security, are deliberately neglected.

The app provides a remote control and health check for App4hab phone app. The GUI is separated into two views - browsing data send by phone and giving commands (turning on or off modules of the android app) to the phone. To switch between those modes, click App4hab at the top lefthand side of the page.

When the phone app is up and running it asks server for commands every ~10 seconds. Basing on the response it gets it toggles it's modules and changes behavior.

Usage guide

Commands

After accessing the send-command view by clicking App4hab at the top lefthand side of the page, user can see current commands phone gets, and has the possibility to change them. To change commands user has to check needed boxes, enter password and click the button. The password is to prevent other people messing with your settings. If user enters wrong password the change is ignored. To setup the password on server, check the Configuring remote server below.

Data

The main view is used to browse data stored on server. It's divided into 2 parts, list on the left and dashboard on the right. The dashboard displays selected entity from list in JSON format.

Each phone request to the server is logged and accessible under the 'Activites' tab. When the sendPhoto command is set to true, phone will send last taken photo and last sensor measurements to the server. This data can be accessed under Sensors and Photos tabs.

Phone authentication

To identify the phone sending requests to server, a simple HTTP header authentication is used. Each request send by phone has a auth header set to some value, it can be set in the app. The same value should be set on the server. To check how to do this, check the Configuring remote server below. If those two values do not match, the request is ignored.

Development

Requirements

• Maven (How to install)
• Java8
• Server with public IP
• Tomcat

Any server with public IP will work fine, thus linux installation is recommended. We are using the cheapest VPS we could find (about 1$ monthly) and it works fine.

In theory the app should work on any Java servlet container, however it was tested on Tomcat and configuration below is described for Tomcat only, making Tomcat recommended solution.

Local vs deployed environment

You can run the server locally on your development machine, by running a CMD command mvn tomcat7:run in the project directory. It will setup stub temporary Tomcat instance and deploy the image to it. You can use the server by entering http://localhost:8080/app4hab/ in your browser. Your local environment will be most likely not configured for app to work (missing environment variables), thus during app startup default values are assigned to work during local development. These values can be changed in config.java file.

Database

The database schema is generated by Hibernate. To modify the schema all what is needed is a change in models found in entities directory. Note that no data migration is implemented, thus changing database schema will require dropping current schema and loosing stored data.

Deployment

You can manage apps deployed on your Tomcat by accessing http://{your_server_address}/manager/html. If the App4hab server cannot start, check logs and try to find the reason. Check the Troubleshooting at the bottom of this file for more info.

Configuring remote server

To run the app on remote server you need to have Tomcat or any other java servlet container installed (tested only on Tomcat, but in principle it should work in the same way for any other container). Tomcat has to be configured to support the app. The configuration can be done by modifying two files:

• {tomcat_directory}/conf/catalina.properties

Add app4hab.db=/var/app4hab/ to the end of the file. The path specifies the location of the app database files

• {tomcat_directory}/bin/setenv.sh

Create the file if it does not exist, remember to run chmod +x setenv.sh to make it executable by Tomcat. This file sets environment variables avaliable for all apps deployed on Tomcat. The file should contain:

• export APP4HAB_UPLOADS=/var/app4hab/uploads - This path defines where to save images sent to phone
• export APP4HAB_WEBAPP={tomcat_path}/webapps/app4hab - path to deployed app
• export APP4HAB_AUTH={your_authentication_token} - authentication token used for authenticating phone
• export APP4HAB_SECRET={your_secret_for_commands_change} - secrets used to authenticate user during commands change

Firts two entries are required, last two are not required as they will be replaced with default values, but setting them is highly recommended. Default values for them are:

• APP4HAB_AUTH=915e9592-43dd-11e8-842f-0ed5f89f718b
• APP4HAB_SECRET=app4hab

Connecting to remote server using Maven Tomcat Plugin

To simplify the deployment, the Maven Tomcat Plugin is used. It connects to your deployment server and automaticly builds and deploys the app. To set it, you need to modify following section of the pom.xml file in the source server code.

<build>
    <plugins>
        <plugin>
            <!-- Deploy war to remote tomcat server, use goal 'tomcat7:redeploy' -->
            <groupId>org.apache.tomcat.maven</groupId>
            <artifactId>tomcat7-maven-plugin</artifactId>
            <version>2.1</version>
            <configuration>
                <username>{Tomcat_user}</username>
                <password>{Tomcat_user_password}</password>
                <path>/app4hab</path>
                <url>http://{your_server_address}/manager/html</url>
            </configuration>
        </plugin>
        ...

This will tell Maven Tomcat Plugin to deploy the app using Tomcat_user account. To set it up, you need to modify the {tomcat_directory}/conf/tomcat-users.xml file and add the line to the end of the file:

<user username="{Tomcat_user}" password="{Tomcat_user_password}" roles="manager-script, manager-gui"/>

Next, restart Tomcat using sudo service tomcat restart for the changes to apply. To deploy the app to remote server all what is needed is running the mvn tomcat7:redeploy command in source code root folder.

Troubleshoting

Logs from deployed app are stored in {tomcat_directory}/logs. Standard output is saved to localhost.{date}.log. Check this log if something unexpected happens.

Known bugs and fixes

org.hsqldb.HsqlException: Database lock acquisition failure: lockFile [file = HDB.lck, exists=true, locked=false, valid=false, ] method: checkHeartbeat read

App cannot conect to database. You can fix this by removing the HDB.lck file found in database folder, or whole folder containg database. Note that deleting database will cause you to loose all data, so making backup is recommended if database can contain any vaulable data.