Skip to content

Services and Background

Jump to bottom
sameerasw edited this page Aug 9, 2026 · 1 revision

⚙️ Services & Background

Essentials relies on several Android background services, workers, and receivers to power its features. This page documents each one and what it's responsible for.

Core Services

ScreenOffAccessibilityService

The master accessibility service — a single service that handles all accessibility-based features to avoid requiring multiple separate services.

Features powered by this service:

  • Screen off widget (global action LOCK_SCREEN)
  • Button remap (intercepts KeyEvents)
  • Dynamic night light (monitors window state changes)
  • App lock (intercepts app foreground changes)
  • Notification lighting coordination
  • Smart pixels overlay
  • Pocket mode (proximity/orientation events)
  • Flashlight handler (torch control via camera)

Key handlers inside the service:

  • FlashlightHandler — camera torch control
  • ButtonRemapHandler — key event interception and action dispatch

Design note: The service itself is not modified per-feature. Feature logic is in separate Handler classes that the service delegates to. This prevents one feature's code from affecting others.

NotificationListener

Monitors all notifications on the device. At ~60,000 lines it is the most complex service in the app.

Features powered by this service:

  • Notification lighting (triggers edge lighting on new notifications)
  • Flashlight pulse (pulses torch for notifications)
  • Call vibrations (monitors call state notifications)
  • Essentials on Display (reads Now Playing / media metadata)
  • App Freezing (monitors app launch notifications to auto-unfreeze)
  • Maps power saving (monitors Google Maps navigation notification)
  • Snooze system notifications (intercepts and cancels system heads-ups)

CaffeinateWakeLockService

A foreground service that holds an SCREEN_BRIGHT_WAKE_LOCK to keep the display on.

State managed by: CaffeinateController (singleton) and CaffeinateViewModel

Behavior:

  • Acquires a timed wake lock
  • Posts a foreground notification with timer and quick-stop action
  • Releases the lock when timer expires or user stops it

BatteryNotificationService

Monitors battery events from the system and connected Bluetooth devices.

Monitored events:

  • ACTION_BATTERY_CHANGED — phone battery level
  • ACTION_BATTERY_LOW / ACTION_BATTERY_OKAY
  • BT device battery via BluetoothDevice battery level APIs

LocationReachedService

A foreground service using FusedLocationProviderClient for background GPS monitoring.

Behavior:

  • Periodically polls current location
  • Compares against saved destination coordinates using Haversine formula
  • Fires USE_FULL_SCREEN_INTENT notification on arrival
  • Stops itself after arrival notification

NotificationLightingService

Renders the edge lighting overlay above other apps when notifications arrive.

Behavior:

  • Creates a TYPE_APPLICATION_OVERLAY window
  • Draws an animated light sweep around the screen perimeter using Canvas
  • Reads notification color from the notification accent color or app icon
  • Respects silent notifications filter setting

InputEventListenerService

Listens for hardware input events (volume/power buttons) for the Button Remap feature.

LiveWallpaperService

Renders the live wallpaper engine for animated wallpapers configured from the Wallpaper feature.

EssentialsConditionProvider

Extends ConditionProviderService — evaluates DIY automation rule conditions and triggers rule execution.

WearOS Services

EssentialsWearableListenerService

Extends WearableListenerService — handles two-way Wearable Data Layer communication:

  • onMessageReceived() — handles commands from the watch (/lock_phone, /toggle_watch_adb_wifi)
  • onDataChanged() — processes data sync from watch
  • DeviceInfoSyncManager.forceSync() — pushes phone state (battery, sound mode, location) to watch

WorkManager Workers

Worker Schedule Purpose
CalendarSyncWorker Periodic (configured) Syncs phone calendars to WearOS watch
DailyWallpaperWorker Periodic (configured) Rotates wallpaper on schedule
AppUpdateWorker Periodic (daily) Checks GitHub for app updates

Quick Settings Tile Services (33 tiles)

All tile services extend BaseTileService, which provides:

  • getTileState() — Current active/inactive state
  • getTileSubtitle() — Dynamic subtitle (e.g., timer remaining for Caffeinate)
  • getTileIcon() — Dynamic icon (e.g., torch on/off icon for Flashlight)
Service Tile
UiBlurTileService UI Blur
AlwaysOnDisplayTileService AOD
AppFreezingTileService App Freezing
AppLockTileService App Lock
AdaptiveBrightnessTileService Adaptive Brightness
BubblesTileService Bubbles
CaffeinateTileService Caffeinate
ChargeQuickTileService Charge Optimization
ColorPickerTileService Color Picker
DeveloperOptionsTileService Developer Options
DynamicNightLightTileService Dynamic Night Light
FlashlightPulseTileService Flashlight Pulse
FlashlightTileService Flashlight
LockdownTileService Lockdown
MapsPowerSavingTileService Maps Power Saving
MonoAudioTileService Mono Audio
NfcTileService NFC
NotificationLightingTileService Notification Lighting
PocketModeTileService Pocket Mode
PrivateDnsTileService Private DNS
PrivateNotificationsTileService Sensitive Content
RefreshRateTileService Refresh Rate
RestartSystemUiTileService Restart SystemUI
ScaleAnimationsTileService Scale Animations
ScreenLockedSecurityTileService Screen Locked Security
SoundModeTileService Sound Mode
StayAwakeTileService Stay Awake
TapToWakeTileService Tap to Wake
UsbDebuggingTileService USB Debugging

Broadcast Receivers

Located in services/receivers/:

  • Listens for BOOT_COMPLETED to restart services on reboot
  • Listens for SCREEN_ON / SCREEN_OFF for relevant feature triggers
  • Listens for BATTERY_CHANGED, ACTION_POWER_CONNECTED, ACTION_POWER_DISCONNECTED
  • Listens for BLUETOOTH_CONNECTION_STATE_CHANGED

Clone this wiki locally