# Automation Bridge

Automation Bridge allows Yasan Launcher and third-party apps such as Tasker to communicate through Android broadcasts.

This is a step-by-step setup guide for Automation Bridge. You can also use the [llms.txt](https://yasan.glass/yasan-launcher/automation-bridge/llms.txt) file for AI-assisted setup.

## Available Functionalities

- **Outgoing Broadcasts**: sending events to other apps
  - **Broadcast Space Changes**: Notifying other apps when the active Space changes
  - **Broadcast Gestures**: Notifying other apps when you perform a gesture

- **Incoming Commands**: receiving commands from other apps
  - **Update Space**: Other apps changing the active Space
  - **Update Settings**: Other apps changing global or Space-specific settings

## Outgoing Broadcasts

### Broadcast Space Changes

To enable Space change broadcasts, follow the steps below:

1. Open **Settings > Advanced > Automation Bridge**
1. Enable **Broadcast Space Changes**
1. Make sure your automation app is [whitelisted](https://yasan.glass/yasan-launcher/automation-bridge/#whitelist)
1. Now the whitelisted apps receive a broadcast whenever the active Space changes

To listen to these broadcasts, follow the steps below:

**General Guide**

1. Listen for `yasan.space.mnml.ai.launcher.action.ACTIVE_SPACE_CHANGED` broadcast actions
1. Read the broadcast's extras to get the details of the change, listed below

**Tasker Guide**

1. Open Tasker
1. Open **Profiles** tab
1. Tap the **plus (+)** button
1. Create a new **Event**
1. Select **System Event** category
1. Select **Intent Received** event
1. Set **Action** to `yasan.space.mnml.ai.launcher.action.ACTIVE_SPACE_CHANGED`
1. The extras below are available as local variables named after them, e.g. `%space_id`

The `ACTIVE_SPACE_CHANGED` broadcast contains these extras:

| Extra | Meaning | Possible values |
| --- | --- | --- |
| `space_id` | New active Space ID | `home`, `commute`, `away`, `active`, `school`, `work`, `focus`, `morning`, `night` |
| `set_by` | How the Space was activated | `user`, `time`, `location_enter`, `location_exit`, `external` |
| `changed_at` | Change time | Unix time in milliseconds |
| `previous_space_id` | Previously active Space ID | `home`, `commute`, `away`, `active`, `school`, `work`, `focus`, `morning`, `night` |
| `previous_set_by` | How the previous Space was activated | `user`, `time`, `location_enter`, `location_exit`, `external` |
| `previous_changed_at` | When the previous Space became active (if available) | Unix time in milliseconds |

### Broadcast Gestures

To enable gesture broadcasts, follow the steps below:

1. Open **Settings > Advanced > Automation Bridge**
1. Enable **Allow Broadcasting Gestures**
1. Make sure your automation app is [whitelisted](https://yasan.glass/yasan-launcher/automation-bridge/#whitelist)
1. Open **Settings > Gestures**
1. Tap the gesture you want to broadcast and select **Broadcast** action
1. Now the whitelisted apps receive a broadcast when this gesture is triggered

To listen to these broadcasts, follow the steps below:

**General Guide**

1. Listen for `yasan.space.mnml.ai.launcher.action.GESTURE_TRIGGERED` broadcast actions
1. Read the `gesture_id` extra to identify the gesture, listed below

**Tasker Guide**

1. Open Tasker
1. Open **Profiles** tab
1. Tap the **plus (+)** button
1. Create a new **Event**
1. Select **System Event** category
1. Select **Intent Received** event
1. Set **Action** to `yasan.space.mnml.ai.launcher.action.GESTURE_TRIGGERED`
1. The `%gesture_id` local variable lets you identify the gesture, listed below

The `gesture_id` value identifies the gesture:

| Gesture | ID |
| --- | --- |
| 1-finger swipe down | `swipe_down` |
| 2-finger swipe down | `two_finger_swipe_down` |
| 3-finger swipe down | `three_finger_swipe_down` |
| 1-finger swipe up | `swipe_up` |
| 2-finger swipe up | `two_finger_swipe_up` |
| 3-finger swipe up | `three_finger_swipe_up` |
| 1-finger swipe left | `swipe_left` |
| 2-finger swipe left | `two_finger_swipe_left` |
| 3-finger swipe left | `three_finger_swipe_left` |
| 1-finger swipe right | `swipe_right` |
| 2-finger swipe right | `two_finger_swipe_right` |
| 3-finger swipe right | `three_finger_swipe_right` |
| Double tap | `double_tap` |

### Whitelist

Broadcast Whitelist allows you to select which apps should receive the broadcasts from Yasan Launcher. It appears when either **Broadcast Space Changes** or **Allow Broadcasting Gestures** is enabled, and the same list applies to both.

1. Open **Settings > Advanced > Automation Bridge**
1. Open **Broadcast Whitelist**
1. Select apps you want to whitelist for broadcasts
1. Now only these whitelisted apps receive the broadcasts

#### Notes

- The whitelisted apps are matched using the package name and their signature. This means if you whitelist a trusted app, and later it is replaced with an app that has the same package name but a different signature, the whitelist is no longer valid and that app will not receive the broadcasts.
- Yasan Launcher verifies the signature of the official [Tasker](https://play.google.com/store/apps/details?id=net.dinglisch.android.taskerm) and [Automate](https://play.google.com/store/apps/details?id=com.llamalab.automate) apps based on the signature of their Play Store release. If the signature does not match, a warning is shown about the app possibly being modified and unsafe to use.

## Incoming Commands

### Update Space

To enable updating spaces in other apps, follow the steps below:

1. Open **Settings > Advanced > Automation Bridge**
1. Enable **Accept External Commands**

To send space update commands to Yasan Launcher, follow the steps below:

**General Guide**

1. Send a broadcast to the `yasan.space.mnml.ai.launcher` package with action `yasan.space.mnml.ai.launcher.action.SET_ACTIVE_SPACE`
1. Include the extra `password`, set to your [password](https://yasan.glass/yasan-launcher/automation-bridge/#password)
1. Include the extra `space_id`, set to one of the Space IDs listed below

**Tasker Guide**

1. Open Tasker
1. Open **Tasks** tab
1. Tap the **plus (+)** button
1. Name your task as you wish, e.g. "Update Yasan Launcher Space"
1. Confirm the task name which opens the **Task Edit** screen
1. Tap the **plus (+)** button
1. Select **System** category
1. Select **Send Intent** action
1. Set **Target** to **Broadcast Receiver**
1. Set **Package** to `yasan.space.mnml.ai.launcher`
1. Set **Action** to `yasan.space.mnml.ai.launcher.action.SET_ACTIVE_SPACE`
1. Add extra `password:<YourPassword>`, your [password](https://yasan.glass/yasan-launcher/automation-bridge/#password)
1. Add extra `space_id:<space>`, one of the Space IDs listed below

Set `space_id` to one of these values:

| Space | ID |
| --- | --- |
| Home | `home` |
| Commute | `commute` |
| Away | `away` |
| Active | `active` |
| School | `school` |
| Work | `work` |
| Focus | `focus` |
| Morning | `morning` |
| Night | `night` |

#### Notes

- The space must be enabled, otherwise the command is ignored.
- The Morning & Night Spaces are special spaces that are automatically disabled outside their predefined schedule. [This is planned to change soon](https://github.com/yasanglass/yasan-launcher-issues/issues/50).

### Update Settings

To enable updating settings in other apps, follow the steps below:

1. Open **Settings > Advanced > Automation Bridge**
1. Enable **Accept External Commands**

To send setting update commands to Yasan Launcher, follow the steps below:

**General Guide**

1. Send a broadcast to the `yasan.space.mnml.ai.launcher` package with action `yasan.space.mnml.ai.launcher.action.SET_SETTING`
1. Include the extra `password`, set to your [password](https://yasan.glass/yasan-launcher/automation-bridge/#password)
1. Include the extra `setting_id`, set to the setting to change, listed below
1. Include the extra `value`, set to the new value as text
1. Include the extra `space_id` only when changing a setting that supports a Space-specific override

**Tasker Guide**

1. Open Tasker
1. Open **Tasks** tab
1. Tap the **plus (+)** button
1. Name your task as you wish, e.g. "Update Yasan Launcher Setting"
1. Confirm the task name which opens the **Task Edit** screen
1. Tap the **plus (+)** button
1. Select **System** category
1. Select **Send Intent** action
1. Set **Target** to **Broadcast Receiver**
1. Set **Package** to `yasan.space.mnml.ai.launcher`
1. Set **Action** to `yasan.space.mnml.ai.launcher.action.SET_SETTING`
1. Add extra `password:<YourPassword>`, your [password](https://yasan.glass/yasan-launcher/automation-bridge/#password)
1. Add extra `setting_id:<setting>`, one of the settings listed below
1. Add extra `value:<value>`, the new value as text
1. Add extra `space_id:<space>` only when changing a setting that supports a Space-specific override

Send all values as text. Send `value` as an empty string to reset the setting.

#### Supported settings

A checked box means the setting supports a Space-specific override.

| Setting | `setting_id` | Supports Space | Accepted values |
| --- | --- | --- | --- |
| Streamer Mode | `streamer_mode` | [ ] | `true`, `false` |
| Notification Dots | `notification_dots` | [x] | `true`, `false` |
| Notification Dot Color | `notification_dot_color` | [x] | `content`, `information`, `caution`, `danger`, `success` |
| Show Wallpaper | `show_wallpaper` | [x] | `true`, `false` |
| Auto Adaptive Icons | `auto_adaptive_icons` | [x] | `true`, `false` |
| Theme Grayscale | `theme_grayscale` | [x] | `true`, `false` |
| Icon Pack | `icon_pack` | [x] | `system` or the package name of an installed icon pack app |
| Orientation | `orientation` | [ ] | `system`, `portrait`, `landscape` |
| Icon Shape | `icon_shape` | [x] | `system`, `circle`, `rounded_square`, `square`, `squircle` |
| Primary Theme | `theme_palette` | [x] | A [Theme ID](https://yasan.glass/yasan-launcher/automation-bridge/#supported-themes), or `system` when set globally (without `space_id`) |
| Light Theme | `theme_light_palette` | [ ] | A [Theme ID](https://yasan.glass/yasan-launcher/automation-bridge/#supported-themes) |
| Dark Theme | `theme_dark_palette` | [ ] | A [Theme ID](https://yasan.glass/yasan-launcher/automation-bridge/#supported-themes) |

##### Notes

- Setting `theme_palette` to `system` means the **Follow System** theme setting is enabled; the active theme switches between `theme_light_palette` and `theme_dark_palette` depending on the system dark mode.
- Setting a theme setting to `system` is only accepted for the global primary theme setting. Space-specific settings do not support changing based on system dark mode.

#### Supported Themes

| Theme | ID |
| --- | --- |
| Light | `light` |
| Dark | `dark` |
| Black | `black` |
| Solarized Dark | `solarized-dark` |
| Solarized Light | `solarized-light` |
| Catppuccin Frappé | `catppuccin-frappe` |
| Catppuccin Latte | `catppuccin-latte` |
| Catppuccin Macchiato | `catppuccin-macchiato` |
| Catppuccin Mocha | `catppuccin-mocha` |
| Gruvbox Dark | `gruvbox-dark` |
| Gruvbox Light | `gruvbox-light` |

These themes are from [Kepko](https://github.com/yasanglass/kepko), the open-source design system Yasan Launcher uses.

### Password

All commands sent to Yasan Launcher need to include a valid password, otherwise they are rejected.

1. Open **Settings > Advanced > Automation Bridge**
1. Copy the auto-generated password by tapping the **Copy Password** button

Include this password in every incoming command:

**General Guide**

1. Include the extra `password`, set to the copied password

**Tasker Guide**

1. Add extra `password:<YourPassword>`

#### Notes

- You can regenerate the password from the Automation Bridge settings using the **Regenerate Password** button. This will invalidate the previous password, and you will have to update all your automations to use the new password.
- This password is only stored on-device and is encrypted.

## Footnotes

- At the moment, these APIs are experimental and may change without backwards compatibility.
- Additional features such as logs to ease debugging, and additional commands are [planned for the future](https://yasan.glass/yasan-launcher/roadmap/).
- Automation Bridge is publicly available from Yasan Launcher 26.32-4576.
- If you are having issues with Automation Bridge or have feedback, feel free to open an issue on the official [issue tracker](https://github.com/yasanglass/yasan-launcher-issues).