Skip to content

Commit 623fa7a

Browse files
Ayush0ChaudharyAyush0Chaudhary
authored
Merge pull request #247 from Ayush0Chaudhary/add-docs-for-trigger
📄 for the trigger system
2 parents 3642a25 + 7c3da29 commit 623fa7a

File tree

1 file changed

+127
-0
lines changed

1 file changed

+127
-0
lines changed

‎docs/TRIGGER_SYSTEM.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Trigger System
2+
3+
## Overview
4+
The Trigger System allows Panda to be initiated from various entry points, enabling proactive and automated task execution. Instead of waiting for a direct voice command, users can configure triggers, such as a specific time of day or an incoming notification from another app, to launch a Panda task. This infrastructure is designed to be flexible and extensible for future trigger types.
5+
6+
## Features
7+
8+
### Multiple Trigger Types
9+
- **Scheduled Time**: Execute tasks at a precise time. Supports day-of-the-week selection (e.g., only on weekdays).
10+
- **Notification**: Execute tasks when a notification is received from a user-specified application.
11+
12+
### Robust Scheduling
13+
- **Exact Alarms**: Uses Android's `setExactAndAllowWhileIdle` to ensure time-based triggers fire precisely when scheduled, even in low-power modes.
14+
- **Persistent Scheduling**: A `BootReceiver` automatically reschedules all active alarms after the device reboots, ensuring no triggers are missed.
15+
16+
### Seamless Integration
17+
- **Direct Task Execution**: Triggers directly invoke the `AgentService` to perform tasks without needing to go through the conversational UI.
18+
- **Centralized Management**: A `TriggerManager` handles all trigger-related logic, including creation, storage, and scheduling.
19+
20+
### User-Friendly UI
21+
- **Intuitive Flow**: A dedicated screen allows users to choose the type of trigger they want to create from a list of cards.
22+
- **Easy Configuration**: Simple UI for setting the time, selecting days of the week, or choosing an application to monitor.
23+
- **Unified List**: A single screen to view, enable/disable, and delete all configured triggers.
24+
- **Permission Handling**: The UI includes dialogs to guide the user in granting the necessary special permissions for exact alarms and notification listening.
25+
26+
## How It Works
27+
28+
### 1. Trigger Creation
29+
1. The user navigates to the "Triggers" screen from `MainActivity`.
30+
2. Tapping the "+" button opens `ChooseTriggerTypeActivity`, where the user selects the trigger type (e.g., "Scheduled Time").
31+
3. This opens `CreateTriggerActivity`, which displays the relevant configuration options.
32+
* For a **Scheduled Time** trigger, the user sets a time and selects the days of the week.
33+
* For a **Notification** trigger, the user selects an application from a list of installed apps.
34+
4. The user provides the task instruction (e.g., "send a good morning text to Mom").
35+
5. Upon saving, the new `Trigger` object is passed to the `TriggerManager`.
36+
37+
### 2. Trigger Management
38+
- The `TriggerManager` saves the trigger configuration to `SharedPreferences` (as a JSON string).
39+
- If it's a scheduled trigger, the `TriggerManager` uses the `AlarmManager` to schedule a one-time exact alarm for the next valid trigger time.
40+
- If it's a notification trigger, no alarm is scheduled. The `PandaNotificationListenerService` is responsible for monitoring it.
41+
42+
### 3. Trigger Execution
43+
#### For Scheduled Triggers:
44+
1. The `AlarmManager` fires a `PendingIntent` at the scheduled time.
45+
2. The `Intent` is received by the `TriggerReceiver`.
46+
3. The `TriggerReceiver` starts the `AgentService`, passing the task instruction.
47+
4. It then immediately calls the `TriggerManager` to reschedule the alarm for the next valid day.
48+
49+
#### For Notification Triggers:
50+
1. The `PandaNotificationListenerService` is constantly running in the background (once enabled by the user).
51+
2. When a notification is posted by any app, the service's `onNotificationPosted` method is called.
52+
3. The service checks if the notification's source package name matches any enabled notification triggers stored in the `TriggerManager`.
53+
4. If a match is found, it fires an `Intent` to the `TriggerReceiver`.
54+
5. The `TriggerReceiver` starts the `AgentService` with the corresponding task instruction.
55+
56+
## Technical Implementation
57+
58+
### Key Components
59+
60+
#### `Trigger` (data class)
61+
- **Purpose**: A flexible data class to hold the configuration for any trigger type.
62+
- **Key Fields**: `id`, `type` (enum: `SCHEDULED_TIME`, `NOTIFICATION`), `instruction`, `isEnabled`, and nullable fields for type-specific data (`hour`, `minute`, `daysOfWeek`, `packageName`, `appName`).
63+
64+
#### `TriggerManager` (singleton)
65+
- **Purpose**: The central brain for all trigger-related logic.
66+
- **Responsibilities**:
67+
- CRUD operations (add, remove, update, get) for triggers.
68+
- Persistence using `SharedPreferences` and `Gson`.
69+
- Scheduling and canceling exact alarms via `AlarmManager`.
70+
- Calculating the next valid trigger time for scheduled alarms based on selected days.
71+
72+
#### `TriggerReceiver` (BroadcastReceiver)
73+
- **Purpose**: A single entry point for all trigger events.
74+
- **Responsibilities**:
75+
- Receives `Intent` broadcasts from both `AlarmManager` and `PandaNotificationListenerService`.
76+
- Extracts the task instruction.
77+
- Starts the `v2.AgentService` to execute the task.
78+
- Calls back to the `TriggerManager` to reschedule a time-based alarm after it has fired.
79+
80+
#### `BootReceiver` (BroadcastReceiver)
81+
- **Purpose**: Ensures scheduled triggers persist across device reboots.
82+
- **Responsibilities**:
83+
- Listens for the `ACTION_BOOT_COMPLETED` system broadcast.
84+
- Calls the `TriggerManager` to reschedule all active, time-based triggers.
85+
86+
#### `PandaNotificationListenerService` (NotificationListenerService)
87+
- **Purpose**: Listens for system-wide notifications.
88+
- **Responsibilities**:
89+
- Compares the package name of incoming notifications against stored notification triggers.
90+
- Broadcasts an `Intent` to the `TriggerReceiver` when a match is found.
91+
92+
#### UI Activities
93+
- **`TriggersActivity`**: Displays a list of all configured triggers. Handles enabling/disabling and deleting triggers.
94+
- **`ChooseTriggerTypeActivity`**: A new screen that provides a card-based UI for selecting a trigger type.
95+
- **`CreateTriggerActivity`**: A dynamic screen that shows the correct configuration UI based on the type chosen in the previous step.
96+
97+
### File Structure
98+
```
99+
app/src/main/java/com/blurr/voice/triggers/
100+
├── ui/
101+
│ ├── AppAdapter.kt
102+
│ ├── AppInfo.kt
103+
│ ├── ChooseTriggerTypeActivity.kt
104+
│ ├── CreateTriggerActivity.kt
105+
│ ├── TriggerAdapter.kt
106+
│ └── TriggersActivity.kt
107+
├── BootReceiver.kt
108+
├── PandaNotificationListenerService.kt
109+
├── PermissionUtils.kt
110+
├── Trigger.kt
111+
├── TriggerManager.kt
112+
└── TriggerReceiver.kt
113+
114+
app/src/main/res/
115+
├── layout/
116+
│ ├── activity_choose_trigger_type.xml
117+
│ ├── activity_create_trigger.xml
118+
│ ├── activity_triggers.xml
119+
│ ├── item_app.xml
120+
│ └── item_trigger.xml
121+
└── ...
122+
```
123+
124+
### Permissions
125+
- `android.permission.RECEIVE_BOOT_COMPLETED`: Required for the `BootReceiver` to function.
126+
- `android.permission.SCHEDULE_EXACT_ALARM`: Required to schedule precise alarms on modern Android versions.
127+
- `android.permission.BIND_NOTIFICATION_LISTENER_SERVICE`: Required for the `PandaNotificationListenerService` to read notifications. This permission must be granted manually by the user in system settings.

0 commit comments

Comments
 (0)