Docs

Android Worker Guide

This page covers everything needed to set up, build, and operate the CROWDio Android mobile worker.

---

Overview

The Android app lets a smartphone or tablet join the CROWDio worker pool. It executes Python task functions on-device using the Chaquopy Python interpreter embedded in the APK.

---

Prerequisites

Requirement	Details
Android Studio	Recent stable version (AGP 8.x support)
Android SDK	Compile target API 36, min SDK API 27
Java toolchain	Java 11
Device/Emulator	Android 8.1+ (API 27+)
Network	Device must reach CROWDio Foreman (same network or VPN)

---

Build the APK

Clone and Open

git clone https://github.com/your-org/CROWDio-Android.git
cd CROWDio-Android

Open the project in Android Studio and let Gradle sync.

Command-Line Build

=== “Linux / macOS” bash ./gradlew assembleDebug

=== “Windows PowerShell” powershell .\gradlew.bat assembleDebug

Install directly to a connected device:

./gradlew installDebug

---

Runtime Setup

1. Launch the App

Install and open the CROWDio app on your device.

2. Configure Foreman Connection

Navigate to Settings and enter:

Setting	Value
Foreman IP	IP address of the machine running the Foreman (e.g. 192.168.1.50)
HTTP API Port	8000 (default)
Worker WebSocket Port	9000 (default)
Artifact Transfer Port	8001 (optional, default when enabled)

3. Start the Worker

Go to the Tasks tab and tap Start Worker.

The app will:

1. Start a foreground service.
2. Connect to the Foreman via WebSocket.
3. Send worker_ready with device capabilities.
4. Begin the 30-second heartbeat loop.
5. Display status as Online in the Tasks tab.

---

Dashboard Monitoring

The Dashboard tab displays real-time information fetched from the Foreman REST API:

• Connected worker list.
• Active and completed jobs.
• Throughput and failure metrics.

---

Task Controls

While a task is running, the following controls are available from the Tasks tab:

Control	Action
Pause	Signals the Python execution context to pause at the next checkpoint
Resume	Resumes a paused execution
Kill	Terminates the current task immediately and reports a task_error

---

Worker Identity and Naming

Each app installation generates a persistent worker_id (stored via WorkerIdManager). You can optionally set a custom worker name in Settings for easy identification in the Foreman dashboard.

---

Operational Characteristics

Behavior	Details
Foreground service	START_STICKY — restarts after process kill
Reconnection	Exponential backoff with jitter via ReconnectionManager
Task queueing	Tasks received while busy are queued in memory
Task timeout	10 minutes per task by default
Heartbeat interval	30 seconds
Oversized results	Automatically uploaded via HTTP; token sent in task_result
Memory pressure	Low-memory hooks trigger model and execution cleanup

---

Battery Optimization Warning

!!! warning “Android Battery Saver” Android’s battery optimization may suspend or kill background services. To keep the worker reliable:

1. Go to **Settings → Apps → CROWDio → Battery**.
2. Select **Unrestricted** battery usage.
3. Or whitelist the app in your battery saver exclusions.

---

Supported Python Packages (On-Device)

The following packages are bundled in the APK via Chaquopy:

Package	Use Case
textblob	NLP / sentiment analysis
nltk	Natural language processing
vaderSentiment	Lexicon-based sentiment scoring
numpy	Numerical computation
requests	HTTP client
aiohttp	Async HTTP
Pillow	Image processing
tflite-runtime	TensorFlow Lite model inference

To add more packages, update the chaquopy block in app/build.gradle.kts.

---

Verifying Worker is Registered

After starting the worker, verify from the Foreman:

curl http://localhost:8000/api/workers

Look for an entry with "type": "android_kotlin" and "status": "online".