Cultivating Mass

Version: 0.0.1a1

Batch provisioning tool for ATAK + Ditto on Android devices.

Written in Python for easy customization—modify the script to fit your needs in the field.

What It Does

Connect multiple Android devices via USB, run the script, and it will:

1. Detect all connected devices automatically
2. Uninstall old versions (optional, with automatic backup)
3. Install your APKs in the correct order
4. Push license files and preferences
5. Grant all required permissions
6. Launch ATAK to confirm success

Devices can be hot-swapped—plug in new devices and they'll be provisioned automatically.

Quick Start

# 1. Clone the repo
git clone https://github.com/getditto/mass-adb-cultivator.git
cd mass-adb-cultivator

# 2. Add your files
#    - Put APKs in apk-to-install/
#    - Put Ditto license (.pdl) in licenses/
#    - Put ATAK prefs (.xml) in prefs/

# 3. Connect devices via USB (enable USB debugging first)

# 4. Run
./cultivating-mass.py

Directory Structure

mass-adb-cultivator/
├── apk-to-install/     # Your APKs go here
│   ├── ATAK-5.6.0.9-civ-release.apk
│   ├── ATAK-Plugin-ditto-edgesync-1.0.5-civ-release.apk
│   └── other-apps.apk
├── licenses/           # Ditto license file
│   └── your-license.pdl
├── prefs/              # ATAK default preferences
│   └── defaults.xml
├── config.yaml         # Configuration (optional)
├── dump-pouch/         # Backed up APKs (auto-created)
└── cultivating-mass.py # The script

Install Order: The script installs APKs in a specific order:

1. ATAK main app (files starting with ATAK-)
2. Other apps
3. Plugins (files containing plugin in the name)

Command-Line Options

Basic Usage

Flag	Description
--version, -v	Show version number and exit
--help, -h	Show help message and exit

Installation Modes

Flag	Description
--uninstall	Remove existing ATAK/Ditto apps before installing. Matches package prefixes defined in config.yaml. APKs are backed up to dump-pouch/ first.
--dry-run	Preview what would happen without actually doing it. Useful for testing.

Device Selection

Flag	Description
--serial SERIAL, -s SERIAL	Only provision this specific device (by serial number).
--skip-emulators	Ignore Android emulators, only provision physical devices.
--wait-for-device [SERIAL]	Wait for a device to connect before starting. Optionally specify which serial to wait for.

Data Management

Flag	Description
--clear-data	Delete /sdcard/atak folder before provisioning. Removes all ATAK data, maps, etc.
--keep-data	When uninstalling, keep app data (uses pm uninstall -k).
--no-dump-pouch	Skip backing up APKs before uninstalling. By default, APKs are saved to dump-pouch/ for recovery.
--force-stop	Force stop ATAK before any operations.

Information & Debugging

Flag	Description
--app-info	Show installed ATAK/Ditto versions on all devices and exit. Also lists other third-party apps.
--bugreport FOLDER	Generate bug reports (logcat, screenshot, device info) to the specified folder and exit.
--quiet, -q	Minimal output. Only show errors.
--debug	Verbose output. Show detailed debug information.

Configuration File

The config.yaml file lets you customize behavior without changing the script.

# Packages to uninstall when --uninstall is used
# Matches any installed package starting with these prefixes
uninstall_packages:
  - com.atakmap
  - com.dittofederal
  - io.ditto

# Where to backup APKs before uninstalling
dump_pouch: dump-pouch

# How many devices to provision at once (default: 16)
max_parallel_devices: 16

# App to launch when provisioning completes
# Set to false to disable
launch_on_complete: com.atakmap.app.civ

# Permissions to grant after installation
# Each app can have permissions, appops, and battery whitelist settings
com.atakmap.app.civ:
  permissions:
    - android.permission.ACCESS_FINE_LOCATION
    - android.permission.ACCESS_BACKGROUND_LOCATION
    - android.permission.CAMERA
    - android.permission.RECORD_AUDIO
    - android.permission.READ_EXTERNAL_STORAGE
    - android.permission.WRITE_EXTERNAL_STORAGE
    # Add more as needed
  appops:
    MANAGE_EXTERNAL_STORAGE: allow
  battery_whitelist: true

Configuration Options

Option	Default	Description
uninstall_packages	ATAK, Ditto prefixes	Package prefixes to remove with --uninstall
dump_pouch	dump-pouch	Directory for APK backups
max_parallel_devices	16	Max simultaneous device provisioning
launch_on_complete	com.atakmap.app.civ	App to launch after provisioning (or false to disable)

Installation

Option 1: Run Directly (Recommended for Field Use)

git clone https://github.com/getditto/mass-adb-cultivator.git
cd mass-adb-cultivator
./cultivating-mass.py

Option 2: Install via pip

# Install with all optional dependencies
pip install cultivating-mass[all]

# Then run from any directory
cultivating-mass

Option 3: Install from Source

git clone https://github.com/getditto/mass-adb-cultivator.git
cd mass-adb-cultivator
pip install -e .[all]

Requirements

• Python 3.10+
• ADB installed and in your PATH
• USB debugging enabled on target devices

Optional Dependencies

Package	Purpose	Install
rich	Better terminal UI with live dashboard	pip install rich
pyyaml	Config file support	pip install pyyaml

Install both with: pip install rich pyyaml

Features

• Auto-detection: Finds all connected ADB devices automatically
• Hot-swap: Plug in new devices anytime—they'll be provisioned
• Parallel processing: Provision up to 16 devices simultaneously
• Smart install order: ATAK first, then apps, then plugins
• APK backup: Saves existing APKs before uninstalling
• Permission grants: Automatically grants required Android permissions
• Retry on reconnect: Failed devices retry when reconnected
• Dry-run mode: Preview operations before executing
• Bug reports: Generate logcat, screenshots, and device info
• Live dashboard: Visual status with the rich library

Recommended Hardware

For provisioning many devices at once:

• Cambrionix 16-port USB hubs - Industrial quality, handles high power draw
• Any powered USB hub with enough ports for your needs

Security Notice

This tool is not a replacement for MDM (Mobile Device Management).

• USB debugging must be enabled on devices, which has security implications
• Only use on trusted networks with physical device security
• Consider disabling ADB after provisioning in production
• The dump-pouch/ folder may contain sensitive APKs—secure accordingly

About

This tool targets ATAK (Android Team Awareness Kit) deployments. Learn more at tak.gov.

Contact

For inquiries about Ditto's public sector solutions:

Email: team-publicsector-sales@ditto.com

License

MIT License - see LICENSE for details.