ON AIR 🎙️🚨

ON AIR is an application for turning on a light to signal to my family that I am currently on a video call.

This app deploys a cronjob script that determines whether the light should be ON or OFF, and then sends a signal to the integrated IoT system.

The application can be configured to respond to three triggers:

1. When a specified application(s) is running.
2. When the webcam is active. Webcam activity is determined by:
   • Apple's VDC_Assistant (a USB webcam) is activated.
   • Apple's AppleH13CamIn::setGetPowerStateGated (the onboard camera) is changed.
3. When Apples IOAudioEngineState is equal to 1 (true / enabled).

This application supports integrations with Home Assistant, and Apple HomeKit.

Pre-Requisites

Each supported integration has it's own requirements listed below.

Home Assistant

•  macOS Monterey 12.7+
• Home Assistant
• Home Assistant compatible device (light, outlet, or switch recommended)
  • This device must already be paired with Home Assistant

Apple HomeKit

Note: This app only supports the new HomeKit architecture released in 2023. Read More

•  macOS Ventura 13.3+
• Apple HomeKit
• Apple Shortcuts
• HomeKit compatible device (light, outlet, or switch recommended)
  • This device must already be paired with HomeKit

Dependencies

• homebrew => /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
• pipx => brew install pipx
• poetry => pipx install poetry
  • Note: Do not install poetry using homebrew
• invoke => pipx install invoke
• python 3.11 => brew install [email protected]

Setup

Home Assistant: Setup Entity

1. Add your Server URL to .env as HASS_SERVER_URL.
2. Add the necessary Home Assistant integration for your device.
   • Capture the entity_id you wish to control
   • Add the entity_id to .env as HASS_ENTITY_ID.
3. Create a Home Assistant Long Lived Access Token
   • Add the token to .env as HASS_ENTITY_ID.

HomeKit: Create Apple Shortcuts

Shortcuts can be created on macOS or iOS.

Open the Shortcuts app and create two new shortcuts. One to turn your device ON, and one to turn it OFF.

1. For the action, select the Home App
2. From the list of actions, select Control
3. From the Scenes and Accessories list, select your device or scene
4. Click Next
5. Select your device's state
6. Click Done
7. Name the shortcut and click Done

Add the names of these shortcuts to .env as SHORTCUT_ON and SHORTCUT_OFF.

Install

1. Install project dependencies and create .env
   • inv project-setup
2. Write convenience scripts and bash aliases
   • inv app-install
3. Setup the cronjob (if desired)
   • #cron-scheduler

Configuration

The application is configured via the .env file.

Variable	Type	Usage
TRIGGER_APPS	List ["str"]	Process name(s) to trigger the device
ENABLE_VIDEO	Boolean	Enable trigger for webcam activation
ENABLE_AUDIO	Boolean	Enable trigger for microphone activation
SMART_HOME_TYPE	String	The IoT system to integrate
DEVICE_CACHE	String	device cache filename
VIDEO_CACHE	String	video cache filename
HASS_SERVER_URL	String	http://hass.server:8123
HASS_API_TOKEN	String	Home Assistant Long Lived Access Token
HASS_ENTITY_ID	String	switch.identifier
SHORTCUT_ON	String	name of Homekit shortut for device on
SHORTCUT_OFF	String	name of Homekit shortut for device off

Trigger Apps

1. Open the application(s) that you want to turn on the light.
2. Run the following command to find the application's process name.
   • inv discover-process-names -q {app-name}
3. Find the process name in the output.

Note: when searching for app-name, try using a short keyword like "code" rather than "Visual Studio Code"

Sometimes, a process name is shortened to "vscode" which would not show up with a multi word query.

If you are unable to successfully query for the process, run the command without -q {app-name} to view all running processes.

Manual Usage

A cool party trick is being able to turn the light on or off from the command line. After running the install steps, you can manually control the light with the onair and offair commands. These commands do not override the cron process.

Automation

To automate your ON AIR light, schedule a cron job to run the script ./run-app-status-light.sh

Cron Scheduler (Recommended)

Use the builtin scheduler to write your crontab entry.

• inv manage-cron [options]

The scheduler accepts the options below:

Options:
  # the action to perform. Must be "add", "list" or "remove"
  -a STRING, --action=STRING
  # run every N minutes. Use 0 for every minute => only for action=add
  -i INT, --interval-min=INT
  # starting at hour (24H) => only for action=add
  -s INT, --start-hour=INT
  # ending at hour (24H) => only for action=add
  -e INT, --end-hour=INT
  # line number to remove => only for action=remove
  -l INT, --line-num=INT

Examples:

• inv manage-cron --action add --interval-min 5 --start-hour 7 --end-hour 15
• inv manage-cron --action remove --line-num 3
• inv manage-cron --action list

Manually (Legacy)

1. Open crontab list with crontab -e
2. Add your cron schedule to the crontab list
3. Save and Exit vim with :wq

Sample cron schedules have been provided in the in the ./cronjobs/ directory.

• Every 5th Minute, MON-FRI 9am-5pm
• Every Minute, Every Day

Need help with cron scheduling? Check out crontab.guru

Uninstall

1. Remove convenience scripts and bash aliases
   • inv app-uninstall
2. Remove the crontab entry, if applicable
   • inv manage-cron --action list
   • inv manage-cron --action remove --line-num {N}