# System Event

Trigger `desktopcomputer`

trigger.system_event

Fires on macOS system events like sleep, wake, lock, network, volume, or Bluetooth device changes. This trigger lets you react to operating system-level events that affect your entire Mac.

Select the specific system event to monitor. Different events provide different output variables — for example, the dark mode event includes the current dark mode state, while network events include connection type and status.

## Ports

Direction | Name | Data Type | Description
--- | --- | --- | ---
Outlet | Output | Any | Payload emitted when the system event occurs

## Configuration

Field | Type | Default | Description
--- | --- | --- | ---
Event | `Dropdown` | Wake | System event type: Sleep, Wake, Screen Lock, Screen Unlock, Dark Mode Changed, Network Changed, Volume Mount, Volume Unmount, Bluetooth Device Connected, or Bluetooth Device Disconnected
Device Name Filter | `Text` | — | Shown for Bluetooth Device Connected. Only fire when the device name contains this text (case-insensitive substring). Leave empty to fire for all devices.
Device Name Filter | `Text` | — | Shown for Bluetooth Device Disconnected. Same case-insensitive substring match, applied independently of the connected filter.
Paired Devices Only | `Boolean` | On | Shown for Bluetooth Device Connected. When on, only devices paired with this Mac fire — matching what the Bluetooth menu shows. Turn off to also catch unpaired devices (route them with a Condition on `isPaired` or `transport`).
Paired Devices Only | `Boolean` | On | Shown for Bluetooth Device Disconnected. Same paired-only gate, applied independently of the connected toggle.
Custom Arguments | `Key-Value` | — | Additional key-value pairs included in the output payload

## Output Variables

Variable | Type | Description
--- | --- | ---
`event` | String | Event type that fired
`timestamp` | String | ISO 8601 timestamp
`isDarkMode` | Boolean | Current dark mode state (dark_mode event)
`networkType` | String | Network type: wifi / cellular / wired / other (network_changed event)
`isConnected` | Boolean | Whether network is connected (network_changed event)
`isExpensive` | Boolean | Whether network is expensive/metered (network_changed event)
`volumeName` | String | Name of mounted/unmounted volume (volume events)
`volumePath` | String | Path of mounted/unmounted volume (volume events)
`deviceName` | String | Name of the Bluetooth device (bluetooth events)
`deviceAddress` | String | MAC address of the device, e.g. ac-88-fd-ee-30-66 (bluetooth events)
`deviceKind` | String | Device type: headphones, audio, keyboard, mouse, gamepad, phone, computer, or unknown (bluetooth events)
`transport` | String | Bluetooth transport: classic or ble (bluetooth events)
`isPaired` | Boolean | Whether the device is paired with this Mac (bluetooth events)
`deviceClass` | Number | Raw Bluetooth class-of-device integer; 0 for BLE devices (bluetooth events)
`vendorID` | String | HID vendor ID as a string; omitted when unavailable (bluetooth events)
`productID` | String | HID product ID as a string; omitted when unavailable (bluetooth events)

## Bluetooth Event Behavior

- Permission: the first time you arm a flow with a Bluetooth event, macOS shows a one-time Bluetooth permission prompt. If access is denied, the trigger stays unarmed until you enable it in System Settings → Privacy & Security → Bluetooth.
- Disconnect debounce: disconnect events fire after a 3-second settle window. A device that reconnects within the window (AirPods auto-switching between your Apple devices) emits nothing; a genuine disconnect fires about 3 seconds after the device drops.
- Wake and radio-on reconnects fire: devices that reconnect when your Mac wakes from sleep, or when Bluetooth is turned back on, emit real connect events on purpose — "when my AirPods connect, set the volume" should run on wake too. Use the Device Name Filter (or combine with the Wake event in a condition) if you want fewer fires.
- Classic and BLE both supported: classic Bluetooth devices (AirPods, speakers, phones) and BLE devices (most modern keyboards and mice) both fire. BLE devices report `deviceClass` 0 and `transport` "ble".
- Paired Devices Only (default on): some devices maintain a second, unpaired low-energy link alongside their main connection — AirPods, for example, briefly open one when stowed in their case, which would otherwise fire a phantom "connected" event under the same device name. The default suppresses these so events match what the Bluetooth menu shows. Turn the toggle off to observe every link — useful for "alert me when an unknown device connects" flows — and route with a Condition on `isPaired` or `transport`.
- Device names: the OS-cached personalized name ("Greg's AirPods Pro") is used while connected; a disconnect may report the generic advertised name ("AirPods Pro") because the link is already torn down. Name filters match both (substring), but exact-match conditions should prefer `deviceAddress`.
- deviceKind values: headphones, audio, keyboard, mouse, gamepad, phone, computer, or unknown — derived from the device class, with an HID fallback for BLE devices.

## Example

Show a notification when dark mode is activated: