Skip to main content
Version: Next

Installing Formulus App

Complete guide for installing the Formulus mobile application on Android devices.

Overview

Formulus is available for Android devices through multiple installation methods. Choose the method that best fits your needs:

  • Obtainium (Recommended) - App manager that installs Formulus directly from GitHub releases, including pre-release versions. Install Obtainium via F-Droid or direct download.
  • Direct APK - Download and install the APK file directly from GitHub releases
  • Development Build - For developers who want to build from source

Note: F-Droid is used to install Obtainium, which then installs Formulus. F-Droid does not directly install Formulus.

System Requirements

Before installing, ensure your device meets these requirements:

RequirementMinimum
Android VersionAndroid 7.0 (API level 24) or higher
Storage Space50 MB free space
Internet ConnectionRequired for initial setup and synchronization
PermissionsCamera, Storage, Location (for form features)

Installation Methods

Obtainium is the recommended method for installing Formulus. It allows you to install and update Formulus directly from GitHub releases, including pre-release versions. You can install Obtainium via F-Droid or by downloading it directly.

Step 1: Install Obtainium

You have two options to install Obtainium:

  1. Open your web browser and navigate to f-droid.org
  2. Locate the "DOWNLOAD F-DROID" button on the main page
  3. Tap the "DOWNLOAD F-DROID" button to download the F-Droid APK file
  4. Enable installation from unknown sources:
    • Go to Settings → Security → Unknown Sources (or Apps → Special app access → Install unknown apps on newer Android versions)
    • Select your browser (Chrome, Firefox, etc.) from the list
    • Enable "Allow from this source" toggle switch
    • Read and acknowledge the security warning about installing apps from unknown sources
  5. Return to your browser and open the downloaded F-Droid APK file
  6. Tap "Install" when prompted
  7. Wait for installation to complete, then tap "Open" to launch F-Droid

F-Droid Download Page

  1. Open F-Droid and search for "Obtainium"
  2. Tap on Obtainium in the search results
  3. Tap "Install" to install Obtainium
  4. Wait for installation to complete
Option B: Install Obtainium Directly from GitHub
  1. Download Obtainium from the Obtainium releases page
  2. Enable installation from unknown sources:
    • Go to Settings → Security → Unknown Sources (or Apps → Special app access → Install unknown apps on newer Android versions)
    • Select your browser from the list
    • Enable "Allow from this source" toggle switch
    • Acknowledge the security warning
  3. Install Obtainium by opening the downloaded APK file
  4. Tap "Install" when prompted in the installation confirmation dialog
  5. Wait for installation to complete

Obtainium Installation

Step 2: Add ODE Repository to Obtainium

  1. Open Obtainium on your device
  2. Navigate to the "Add app" tab in the bottom navigation bar (indicated by a "+" icon)
  3. Enter the GitHub repository URL in the "App source URL" field:
    • The field should contain: https://github.com/OpenDataEnsemble/ode
    • Ensure the full URL is entered correctly
  4. Configure GitHub options (important for pre-release versions):
    • Enable "Include prereleases" toggle - This is crucial for installing alpha/beta versions of Formulus
    • Enable "Fallback to older releases" toggle - This allows Obtainium to use older releases if newer ones are unavailable
  5. Tap the "Add" button to save the repository
  6. Wait for Obtainium to fetch the repository information and available releases

Obtainium Add App Screen

Important: Make sure "Include prereleases" is enabled (toggle switched to the right/purple) to see and install pre-release versions like v1.0.0-alpha.12.

Step 3: Install Formulus

  1. Open Obtainium and navigate to the "Apps" tab
  2. Find "ode" in your apps list (it should appear after adding the repository)
  3. Tap on "ode" to open the app details page
  4. Review the app information:
    • App name: ode
    • Developer: OpenDataEnsemble
    • Package: org.opendataensemble.formulus
    • Latest version: v1.0.0-alpha.12 (or current version)
    • Status: Not installed
  5. Tap the "Install" button at the bottom of the screen
  6. Confirm installation when prompted:
    • A dialog will appear showing the Formulus app icon and asking "Do you want to install this app?"
    • Tap "Install" in the confirmation dialog (the "Cancel" button is on the left)
  7. Wait for download and installation to complete
  8. Find Formulus in your app drawer or search for it:
    • Open your app drawer or launcher
    • Search for "Formulus" or "formulu"
    • The app icon shows a yellow giraffe head with a green background and white clipboard
    • Tap on Formulus to launch the app

ODE App Details in Obtainium

Formulus Installation Dialog

Formulus App Search

Automatic Updates

Obtainium will automatically check for updates:

  1. Open Obtainium and navigate to the "Apps" tab
  2. Apps with available updates will be marked
  3. Tap on "ode" to see update details
  4. Tap "Update" or "Install" to install the new version
  5. Confirm the update when prompted
  6. App data is preserved during update

Method 2: Direct APK Installation

If Obtainium is not available or you prefer direct installation:

Step 1: Download the APK

  1. Download the latest APK from the releases page
  2. Save the file to your device's Downloads folder

Step 2: Enable Unknown Sources

  1. Go to Settings → Security (or Apps → Special app access → Install unknown apps on newer Android versions)
  2. Select your browser or file manager from the list (e.g., Chrome, Firefox, Files)
  3. Enable "Allow from this source" toggle switch
  4. Read and acknowledge the security warning:

    "Your phone and personal data are more vulnerable to attack by unknown apps. By installing apps from this source, you agree that you are responsible for any damage to your phone or loss of data that may result from their use."

Enable Unknown Sources

Step 3: Install the APK

  1. Open your file manager or Downloads app
  2. Navigate to the Downloads folder
  3. Tap on the Formulus APK file
  4. Review the permissions requested by the app
  5. Tap "Install" to begin installation
  6. Wait for installation to complete
  7. Tap "Open" to launch the app

Method 3: Development Build

For developers who want to build and install from source, see the Development Installation Guide.

Post-Installation Setup

After installing Formulus, you need to configure it to connect to your Synkronus server:

Initial Configuration

  1. Open Formulus on your device
  2. You'll see the welcome screen with configuration options
  3. Choose your configuration method:
    • QR Code Scan (Recommended) - Scan a QR code with server details
    • Manual Entry - Enter server URL and credentials manually

QR Code Configuration

  1. Tap "Scan QR Code" on the welcome screen
  2. Grant camera permission if prompted
  3. Point the camera at the QR code provided by your administrator
  4. Settings auto-populate with server URL, username, and password
  5. Tap "Connect" to verify and save the configuration

Manual Configuration

  1. Tap "Manual Configuration" on the welcome screen
  2. Enter Server URL: http://your-server-ip:8080 or https://your-server-domain
  3. Enter Username: Your username provided by your administrator
  4. Enter Password: Your password
  5. Tap "Test Connection" to verify connectivity
  6. Tap "Save" to store the configuration

First Login

  1. After configuration, you'll be prompted to log in
  2. Credentials should be pre-filled (if using QR code)
  3. Tap "Login" to authenticate
  4. Wait for authentication - A token is stored locally for future sessions
  5. You'll be redirected to the main app interface

Verification

To verify that Formulus is installed correctly:

  1. Check app icon appears in your app drawer
  2. Open the app and verify it launches without errors
  3. Check Settings to confirm server configuration is saved
  4. Test connection by tapping "Test Connection" in Settings
  5. Verify login by logging in with your credentials

Troubleshooting Installation

Installation Fails

Problem: APK installation fails with "App not installed" error.

Solutions:

  • Ensure you have enough storage space (at least 50 MB free)
  • Check that "Unknown Sources" is enabled for your file manager
  • Try downloading the APK again (file may be corrupted)
  • Ensure your device meets minimum Android version requirements (7.0+)

App Crashes on Launch

Problem: Formulus crashes immediately after opening.

Solutions:

  • Restart your device
  • Clear app data: Settings → Apps → Formulus → Storage → Clear Data
  • Uninstall and reinstall the app
  • Check that your device has sufficient RAM available

Cannot Connect to Server

Problem: App cannot connect to the Synkronus server.

Solutions:

  • Verify server URL is correct (check for typos)
  • Ensure device has internet connection
  • Check that server is running and accessible
  • Verify firewall settings aren't blocking the connection
  • For local development, use 10.0.2.2 instead of localhost on Android emulator

Obtainium Not Finding Updates

Problem: Obtainium doesn't show Formulus updates.

Solutions:

  • Ensure the ODE repository is added correctly in Obtainium
  • Check that "Include prereleases" is enabled if you want pre-release versions
  • Refresh Obtainium: Open the app and wait for it to check for updates
  • Check that Obtainium has internet connection
  • Verify repository URL is correct: https://github.com/OpenDataEnsemble/ode

Updating Formulus

Via Obtainium

  1. Open Obtainium and navigate to the "Apps" tab
  2. Find "ode" in your apps list
  3. Tap on "ode" to see update information
  4. Tap "Install" or "Update" if a newer version is available
  5. Confirm the installation when prompted
  6. App data is preserved during update

Via Direct APK

  1. Download the latest APK from the releases page
  2. Install over existing installation (no need to uninstall)
  3. App data is preserved during update

Uninstalling Formulus

To uninstall Formulus:

  1. Go to Settings → Apps (or Application Manager)
  2. Find Formulus in the app list
  3. Tap on Formulus
  4. Tap "Uninstall"
  5. Confirm uninstallation

Note: Uninstalling will remove all local data, including:

  • Saved observations (not yet synced)
  • App configuration
  • Cached app bundles
  • Local database

Important: Ensure all data is synced to the server before uninstalling.

Finding Formulus After Installation

After installation, you can find and launch Formulus:

  1. Open your app drawer or launcher
  2. Search for "Formulus" or "formulu" using your device's search function
  3. Look for the Formulus icon: A yellow giraffe head with a green background and white clipboard with checkmarks
  4. Tap on the Formulus icon to launch the app

Finding Formulus App