Skip to main content
Version: 1.0

Installing Formulus for Development

Complete guide for developers to install Formulus on physical devices or emulators using ADB or development builds.

Overview

Developers can install Formulus on Android devices or emulators using several methods:

  • ADB Installation - Install APK directly via Android Debug Bridge
  • Android Emulator - Run and test on virtual devices
  • Development Build - Build and run from source with hot reload

This guide covers cross-platform commands for Linux, macOS, and Windows.

Prerequisites

Before installing, ensure you have:

RequirementDescription
Android SDKAndroid SDK Platform Tools (includes ADB)
ADBAndroid Debug Bridge (part of SDK Platform Tools)
USB DriversDevice-specific USB drivers (for physical devices)
Developer OptionsEnabled on Android device (for physical devices)
USB DebuggingEnabled on Android device (for physical devices)

Installing Android SDK Platform Tools

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install android-tools-adb android-tools-fastboot

# Fedora
sudo dnf install android-tools

# Arch Linux
sudo pacman -S android-tools

# Verify installation
adb version

Method 1: ADB Installation on Physical Device

Step 1: Enable Developer Options

  1. Open Settings on your Android device
  2. Navigate to About Phone (or About Device)
  3. Find "Build Number" (usually at the bottom)
  4. Tap "Build Number" 7 times until you see "You are now a developer!"

Step 2: Enable USB Debugging

  1. Go back to Settings
  2. Open Developer Options (now visible in Settings)
  3. Enable "USB Debugging"
  4. Accept the warning about USB debugging

Step 3: Connect Device

  1. Connect your device to your computer via USB cable
  2. On your device, you may see a prompt: "Allow USB debugging?"
  3. Check "Always allow from this computer" (optional but recommended)
  4. Tap "Allow"

Step 4: Verify Device Connection

adb devices

Expected output:

List of devices attached
ABC123XYZ456    device

If you see "unauthorized", check your device and accept the USB debugging prompt.

Step 5: Install Formulus APK

Option A: Install from Local APK File

# Navigate to directory containing APK
cd /path/to/formulus/android/app/build/outputs/apk/debug

# Install APK
adb install app-debug.apk

Option B: Install from Remote URL

# Download and install in one command
curl -L https://github.com/OpenDataEnsemble/ode/releases/download/v1.0.0/formulus.apk -o /tmp/formulus.apk
adb install /tmp/formulus.apk

Step 6: Verify Installation

# Check if app is installed
adb shell pm list packages | grep formulus

# Launch the app
adb shell am start -n com.opendataensemble.formulus/.MainActivity

Method 2: Android Emulator Installation

Step 1: Set Up Android Emulator

Using Android Studio

  1. Install Android Studio from developer.android.com
  2. Open Android Studio → Tools → Device Manager
  3. Create Virtual Device → Select a device (e.g., Pixel 5)
  4. Select System Image (e.g., Android 11, API 30)
  5. Finish and start the emulator

Using Command Line (Linux/macOS)

# Install emulator via SDK Manager
sdkmanager "emulator" "platform-tools" "platforms;android-30"

# List available system images
sdkmanager --list | grep system-images

# Create AVD (Android Virtual Device)
avdmanager create avd -n formulus_emulator -k "system-images;android-30;google_apis;x86_64"

# Start emulator
emulator -avd formulus_emulator &

Step 2: Verify Emulator Connection

# Wait for emulator to boot (may take 1-2 minutes)
adb devices

# Should show emulator
List of devices attached
emulator-5554    device

Step 3: Install Formulus on Emulator

# Build APK first (if not already built)
cd formulus
npm run android

# Install on emulator
adb -s emulator-5554 install android/app/build/outputs/apk/debug/app-debug.apk

Step 4: Important Notes for Emulator

When configuring Formulus on an emulator to connect to a local server:

  • Use 10.0.2.2 instead of localhost - This is the special IP that the emulator uses to access the host machine
  • Example server URL: http://10.0.2.2:8080
  • For network servers: Use the actual IP address or domain name

Method 3: Development Build with Hot Reload

Prerequisites

  • Node.js 18+ and npm
  • React Native CLI or Expo CLI
  • Java Development Kit (JDK) 11 or higher
  • Android Studio with Android SDK

Step 1: Install Dependencies

cd formulus
npm install

Step 2: Start Metro Bundler

# In formulus directory
npm start

Keep this terminal open. Metro is the JavaScript bundler for React Native.

Step 3: Build and Run on Device/Emulator

# For Android device (connected via USB)
npm run android

# For Android emulator (must be running)
npm run android

This command will:

  1. Build the Android app
  2. Install it on your device/emulator
  3. Start the app
  4. Connect to Metro bundler for hot reload

Step 4: Development Features

With development build, you get:

  • Hot Reload - Changes reflect immediately
  • Fast Refresh - React components update without losing state
  • Debug Menu - Shake device or press Ctrl+M (Windows/Linux) or Cmd+M (macOS)
  • React Native Debugger - Debug JavaScript code in Chrome DevTools

Common ADB Commands

Useful Commands for Development

List connected devices:

adb devices

Install APK:

adb install path/to/app.apk

Uninstall app:

adb uninstall com.opendataensemble.formulus

Reinstall app (uninstall + install):

adb install -r path/to/app.apk

View app logs:

# All logs
adb logcat

# Filter for Formulus only
adb logcat | grep -i formulus

# Clear logs
adb logcat -c

Pull file from device:

adb pull /path/on/device /path/on/computer

Push file to device:

adb push /path/on/computer /path/on/device

Open app:

adb shell am start -n com.opendataensemble.formulus/.MainActivity

Stop app:

adb shell am force-stop com.opendataensemble.formulus

Clear app data:

adb shell pm clear com.opendataensemble.formulus

Troubleshooting

Device Not Detected

Problem: adb devices shows no devices.

Solutions:

  • Check USB cable connection
  • Try a different USB port
  • Install device-specific USB drivers (Windows)
  • Enable USB debugging on device
  • Accept USB debugging prompt on device
  • Restart ADB server: adb kill-server && adb start-server

Installation Fails

Problem: adb install fails with error.

Solutions:

  • Uninstall existing version first: adb uninstall com.opendataensemble.formulus
  • Use -r flag to reinstall: adb install -r app.apk
  • Check device has enough storage
  • Verify APK is not corrupted
  • Check device is in file transfer mode (not charging only)

Emulator Connection Issues

Problem: Cannot connect to local server from emulator.

Solutions:

  • Use 10.0.2.2 instead of localhost for server URL
  • Check firewall isn't blocking connections
  • Verify server is running and accessible
  • Use actual IP address instead of localhost

Permission Denied Errors

Problem: ADB commands fail with permission errors.

# Add user to plugdev group
sudo usermod -a -G plugdev $USER

# Create udev rules
sudo nano /etc/udev/rules.d/51-android.rules
# Add: SUBSYSTEM=="usb", ATTR{idVendor}=="####", MODE="0664", GROUP="plugdev"

# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# Log out and log back in