Skip to content

External Control and Integrations

Jump to bottom
sameerasw edited this page Oct 11, 2026 · 2 revisions

🔌 External Control & Integrations

Essentials provides robust interfaces for external automation apps (like Tasker, MacroDroid, Automate), custom ADB scripts, and system integrations (like Android 16 App Functions) to control settings, toggle features, query state, and trigger workflows programmatically.

🚀 Integration Overview

Method Best For Requirement
Broadcast Intents Tasker, MacroDroid, ADB scripts, Quick shell triggers External Control Permission (com.sameerasw.essentials.permission.EXTERNAL_CONTROL), or an External control token for apps that cannot hold the permission
Content Provider Direct queries, state checking, read/write via content URI Read/Write access via Provider URI
App Functions (Android 16+) System Assistant, AI Agents, App Function Manager android.permission.BIND_APP_FUNCTION_SERVICE

📡 1. Broadcast Intent API

Essentials exposes two exported broadcast receivers for the action com.sameerasw.essentials.action.EXTERNAL_CONTROL. Both accept the same extras. They differ in how the sender is authorised.

Receiver Class Authorisation Use for
Permission receiver com.sameerasw.essentials.external.ExternalActionReceiver Sender must hold com.sameerasw.essentials.permission.EXTERNAL_CONTROL Apps that declare the permission in their manifest
Token receiver com.sameerasw.essentials.external.ExternalTokenActionReceiver token extra must match the External control token Tasker, MacroDroid, Automate and other apps that cannot hold the permission

Receiver Details

  • Action: com.sameerasw.essentials.action.EXTERNAL_CONTROL
  • Package: com.sameerasw.essentials (or com.sameerasw.essentials.debug / com.sameerasw.essentials.foss)
  • Class: one of the two above

⚠️ Automation apps such as Tasker do not request the External Control permission, and it cannot be granted to them. Android silently drops broadcasts from apps that do not hold it, so use the token receiver for them.

Setting up the External control token

  1. Open Essentials ➔ Settings and find External control token.
  2. Tap the refresh button to generate a random token, or type your own.
  3. Tap save. Without a saved token the token receiver ignores every request.
  4. Add the token to your intent as the token extra.

Treat the token like a password. Anyone who knows it can change Essentials settings, and you can replace it at any time to revoke access.

Extras Specification

Extra Key Type Description Values / Examples
path String Target routing path (settings/<key> or location_alarm) settings/island_enabled, location_alarm
action String Action operation to perform update, toggle, start, stop
value String Value to set (for update action) "true", "false", "100", "unlocked"
token String External control token (token receiver only) The token saved in Settings

🛠️ How to Control Settings & Features

Any setting stored in Essentials (SettingsRepository) can be directly updated or toggled.

Path Format

settings/<preference_key>

Common Preference Keys for Popular Features

Feature Key Type Supported Values / Actions
Island island_enabled Boolean update (true/false), toggle
Island Catch-up island_catch_up_enabled Boolean update (true/false), toggle
Island Media island_show_media Boolean update (true/false), toggle
Island Flashlight island_show_flashlight Boolean update (true/false), toggle
Caffeinate caffeinate_running Boolean update (true/false), toggle
Screen Off Lock screen_off_lock Boolean update (true/false), toggle
Notification Lighting notification_lighting_enabled Boolean update (true/false), toggle
Smart Pixels smart_pixels_enabled Boolean update (true/false), toggle
App Lock app_lock_enabled Boolean update (true/false), toggle
Monochrome Mode monochrome_mode_enabled Boolean update (true/false), toggle
Flashlight Pulse flashlight_pulse_enabled Boolean update (true/false), toggle

💡 Finding other keys: Check the full list of setting keys in com.sameerasw.essentials.data.repository.SettingsRepository.

📱 Tasker Setup Guide

Example 1: Enable / Disable Island

  1. In Tasker, add a new action: System ➔ Send Intent.
  2. Configure the action:
    • Action: com.sameerasw.essentials.action.EXTERNAL_CONTROL
    • Package: com.sameerasw.essentials
    • Class: com.sameerasw.essentials.external.ExternalTokenActionReceiver
    • Target: Broadcast Receiver
    • Extra 1: path:settings/island_enabled
    • Extra 2: action:update
    • Extra 3: value:true (or value:false)
    • Extra 4: token:<your External control token>

Example 2: Toggle Island State

  1. In Tasker, add action Send Intent:
    • Action: com.sameerasw.essentials.action.EXTERNAL_CONTROL
    • Package: com.sameerasw.essentials
    • Class: com.sameerasw.essentials.external.ExternalTokenActionReceiver
    • Target: Broadcast Receiver
    • Extra 1: path:settings/island_enabled
    • Extra 2: action:toggle
    • Extra 3: token:<your External control token>

💻 ADB Shell Examples

You can execute these commands directly over USB, Wi-Fi debugging, or via Termux / Shizuku shell.

To use the token receiver instead, add -n com.sameerasw.essentials/.external.ExternalTokenActionReceiver --es token "<your token>" to any of the commands below.

Toggle & Update Settings via ADB

# Enable Island
am broadcast -a com.sameerasw.essentials.action.EXTERNAL_CONTROL \
  --es path "settings/island_enabled" \
  --es action "update" \
  --es value "true"

# Disable Island
am broadcast -a com.sameerasw.essentials.action.EXTERNAL_CONTROL \
  --es path "settings/island_enabled" \
  --es action "update" \
  --es value "false"

# Toggle Island state
am broadcast -a com.sameerasw.essentials.action.EXTERNAL_CONTROL \
  --es path "settings/island_enabled" \
  --es action "toggle"

Location Alarm Actions via ADB

# Start location alarm for a specific alarm ID
am broadcast -a com.sameerasw.essentials.action.EXTERNAL_CONTROL \
  --es path "location_alarm" \
  --es action "start" \
  --es id "<alarm_id>"

# Stop active location alarm
am broadcast -a com.sameerasw.essentials.action.EXTERNAL_CONTROL \
  --es path "location_alarm" \
  --es action "stop"

🗄️ 2. Content Provider API (ExternalControlProvider)

Essentials exposes a Content Provider authority:

content://com.sameerasw.essentials.external

Querying Settings

content query --uri content://com.sameerasw.essentials.external/settings/island_enabled

Returns a cursor with columns key, value, type.

Updating Settings

content update --uri content://com.sameerasw.essentials.external/settings/island_enabled --bind value:s:true

Querying Location Alarms

content query --uri content://com.sameerasw.essentials.external/location_alarm/list

Returns cursor with columns id, name, latitude, longitude, radius, isEnabled, isPaused, lastTravelled, isActive, iconResName.

🤖 3. App Functions Service (Android 16+)

For Android 16 and AI Agent environments, Essentials implements EssentialsAppFunctionService (BaseEssentialsAppFunctionService), providing structured and schema-backed tool calls:

  • toggleFlashlight(enabled: Boolean)
  • toggleCaffeinate(enabled: Boolean)
  • setSoundMode(mode: String) (SOUND, VIBRATE, SILENT)
  • getDeviceStatus()
  • getAlarms(), toggleAlarm(alarmId, enabled)
  • listAutomations(), toggleAutomation(automationId, enabled)
  • getFreezeTags(), freezeTag(tagId), unfreezeTag(tagId)

Clone this wiki locally