Skip to main content

​
Overview

The FERAL Node Android app turns your phone into a FERAL edge node. It connects to the Brain via WebSocket, forwards Health Connect data, and runs a foreground service for persistent connectivity.

​
Requirements

  • Android 8.0+ (API 26), targeting API 34
  • Android Studio Hedgehog+
  • Health Connect app installed (for health data)

​
Setup

  1. Open feral-nodes/android-bridge/ in Android Studio (the root Gradle project).
  2. The :app module maps to feral-nodes/android-app/.
  3. Sync Gradle, then Run on a device or emulator.
The app requests the following Health Connect permissions:
Record TypePermission
HeartRateRecordhealth.READ_HEART_RATE
OxygenSaturationRecordhealth.READ_OXYGEN_SATURATION
SleepSessionRecordhealth.READ_SLEEP
StepsRecordhealth.READ_STEPS
ActiveCaloriesBurnedRecordhealth.READ_ACTIVE_CALORIES_BURNED
On first run, the user is prompted to grant these permissions in the Health Connect app.

​
Foreground Service

The app runs FeralForegroundService to maintain the Brain connection in the background. Required permissions in AndroidManifest.xml:
PermissionPurpose
FOREGROUND_SERVICEBase foreground service permission
FOREGROUND_SERVICE_HEALTHHealth data relay
FOREGROUND_SERVICE_MICROPHONEVoice commands
FOREGROUND_SERVICE_CONNECTED_DEVICEBLE device bridge
POST_NOTIFICATIONSNotification channel (Android 13+)
BLUETOOTH_CONNECTBLE glasses pairing

​
Doze Mode & Battery Optimization

The foreground service keeps the app alive during Doze. However:
  • WebSocket connections may be dropped during deep Doze on some OEMs.
  • The service auto-reconnects when connectivity resumes.
  • Users should exempt the app from battery optimization: Settings → Apps → FERAL Node → Battery → Unrestricted.
  • On OEMs with aggressive battery management (Samsung, Xiaomi, Huawei), users may need to add the app to “Don’t optimize” lists.

​
QR Pairing

  1. On the Brain dashboard, click Add Device → QR Code.
  2. In the Android app, go to Settings → Scan QR Code to Pair.
  3. Expected QR format: {"host":"...","port":9090,"token":"..."}

​
Running Tests

​
Unit Tests (JVM)

./gradlew :app:test
Tests in src/test/java/ai/feral/node/:
  • HealthConnectManagerTest — callback data format, time ranges, permission matrix

​
Instrumented Tests (device/emulator)

./gradlew :app:connectedAndroidTest
Tests in src/androidTest/java/ai/feral/node/:
  • MainActivityTest — Compose UI: 3-tab navigation, health metrics display, settings form
  • QRScannerActivityTest — QR JSON parsing, edge cases

​
Troubleshooting

  • Health data empty — Install the Health Connect app and grant permissions.
  • Service killed — Exempt from battery optimization; some ROMs aggressively kill background services.
  • QR scan fails — Ensure camera permission is granted and the QR contains host + token keys.
  • Build errors — Run from the android-bridge/ root; :app depends on :bridge.