focus-timer-home-assistant-bridge

Mirrors GNOME Focus Timer state into a single Home Assistant helper entity over its REST API. The helper can drive scenes, announcements, and automations.

The bridge listens on the session D-Bus for Focus Timer state changes and pushes a one-word value to the helper on every transition.

flowchart LR
ft[Focus Timer] -- D-Bus --> br([Bridge]) -- REST API --> ha[Home Assistant]

Loading

State values

Value	Meaning
stopped	fully stopped, or Focus Timer not running
paused	timer paused
idle	between cycles: break ended, next pomodoro queued
pomodoro	focus session running
short-break	short break running
long-break	long break running

This is roughly how the bridge picks a new state value on every property change:

flowchart TD
    start([property changed]) --> if_reachable{Focus Timer<br/>reachable?}
    if_reachable -- False --> stopped([stopped])
    if_reachable -- True --> if_paused{Timer.IsPaused?}
    if_paused -- True --> paused([paused])
    if_paused -- False --> if_running{Timer.IsRunning?}
    if_running -- True --> current_state(["Session.CurrentState<br/>(pomodoro | short-break | long-break)"])
    if_running -- False --> if_sess{"Session.CurrentState<br/>== stopped?"}
    if_sess -- True --> stopped
    if_sess -- False --> idle([idle])

Loading

Home Assistant helper

Add this to configuration.yaml:

input_text:
  focus_timer_state:
    name: Focus Timer State
    initial: stopped
    max: 16

Or use an input_select if you prefer a dropdown:

input_select:
  focus_timer_state:
    name: Focus Timer State
    initial: stopped
    options:
      - stopped
      - paused
      - idle
      - pomodoro
      - short-break
      - long-break

Then reload YAML helpers from Developer Tools, or restart HA.

Example HA triggers:

trigger:
  - platform: state
    entity_id: input_text.focus_timer_state
    to: short-break # short break start
  - platform: state
    entity_id: input_text.focus_timer_state
    from: short-break # short break end
  - platform: state
    entity_id: input_text.focus_timer_state
    to: pomodoro # focus session start

Install

# Fedora
sudo dnf install python3-aiohttp python3-dbus-fast just

# Debian / Ubuntu
sudo apt install python3-aiohttp python3-dbus-fast just

just install
$EDITOR ~/.config/focus-timer-home-assistant-bridge/env
just enable

Logs: journalctl --user -fu focus-timer-home-assistant-bridge.service.

Development

Requires uv for dependency management.

uv sync
uv run focus-timer-home-assistant-bridge

Configuration is via environment variables; see env.example.