Skip to content

Firing Module

Håkon Olav Torvik edited this page Oct 24, 2026 · 1 revision

Firing Module

Part of the Relay design spec. See the contents.

13 · Firing & reliability

Making it actually fire

Built first and tested hardest. Everything that makes noise goes through one module.

The firing module

One controller, parameterized by context. It owns the looping audio, the vibration, the full-screen activity and the notification:

Context Actions
Ring schedule fires Dismiss · Snooze (hidden once max snoozes is reached)
Relay boundary, interaction required Continue · Stop relay
Timer / relay reaches its end Stop · Restart · +1 min
  • If several things ring at once (two timers, or an alarm during a run), they stack on one ringing screen and each is dismissed on its own.
  • Audio: USAGE_ALARM, looping, with audio focus. It plays at alarm volume even when media is muted.

Scheduling

  • setAlarmClock() for Ring schedules. It's the most Doze-proof option and shows the system "next alarm" indicator.
  • setAlarmClock() for every run's next step end too. It's the only API Doze never defers or rate-limits: with plain exact alarms, a relay of 1-minute steps with the screen off would drift by many minutes. The cost is the status-bar alarm icon while a timer runs. UI and notification countdowns are computed from the persisted end timestamp.
  • A seamless boundary advances from the step's scheduled end, not from when the alarm arrived, so a late alarm doesn't stretch the relay.
  • Ring timeout: an unanswered alarm counts as dismissed. A run that times out only goes quiet; it keeps waiting on the Timers pane and in its notification.
  • Reschedule everything (schedules, active runs, widget ticks) on boot, on time change, on time-zone change and on app update.

Permissions

  • USE_EXACT_ALARM. Google Play auto-grants it to apps whose core function is an alarm clock or timer, so no permission screen is needed and the user can't revoke it by accident. v0.5 used SCHEDULE_EXACT_ALARM, which the user must grant in system settings and can revoke.
  • USE_FULL_SCREEN_INTENT, gated by canUseFullScreenIntent() on API 34+, with a heads-up fallback.
  • POST_NOTIFICATIONS, requested at first alarm or timer creation. Battery-optimization exemption, prompted once.
  • Notification channels: ringing alarm, ringing timer, run progress, upcoming alarm, stopwatch, errors. Run progress and stopwatch are default importance with no sound (v1.1): on LOW, Android hid them under "Silent".

Relay · spec v1.0 · clean-restart baseline, update as screens get built

Clone this wiki locally