Hack your Productivity! Setup a Pomodoro Timer in Home Assistant

Personally, I’m not a normally fan of Productivity ‘hacks’.
In most cases, they just don’t work for me, and I learnt in April 2023 – at the tender young age of 41 – that it’s most likely because I have ADHD.

That said, Several years ago – Well and truly before my ADHD Diagnosis -I came across the Pomodoro Technique.
Developed by an Francesco Cirillo in the late 1980’s it breaks work up into manageable time blocks called “Pomodoros”.

The name “Pomodoro” is the italian word for “Tomato”. Allegedly from the Tomato Kitchen Timer Cirillo used when developing the Technique while he was studying at University and finding it difficult to stay focused.

Somehow, the Pomodoro Technique DID help me to focus my work and improve my productivity.

How does it work?

The Pomodoro Technique divides work up into easy time-blocks of 25 minutes work, followed by a 5 minute break. After completing 4 Pomodoros, you take a longer 20-30 minute break.

Boiled down to 6 Steps:

1. Select a Task from your To-Do List
2. Start a 25-minute Timer
3. Work on your Chosen Task – and ONLY your Chosen task – until the timer goes off.
4. Take a 5-minute break (it’s best to time these
5. Repeat steps 1 to 4 until you’ve completed 4 “Pomodoros”
6. After completing 4 Pomodoro’s, take a longer 20-30 minute break.

But there’s a Caveat

Cirillo and other proponents of the Pomodoro Technique recommend implementing a decidely LOW TECH method of using the technique involving a Mechanical Timer, a pencil, and paper.

In researching for the video, I found some suggestion that the auditory stimulus of the ticking timer may assist with entering a “flow-state” – That feeling of being on a roll and unstoppable.

However, There’s a couple of reasons I wanted to set this up in Home Assistant:

• When I’d previously made use of the Technique, I found I would easily lose track of how many Pomodoros I’d completed, and by extension, how long a break to take after finishing the current Pomodoro.
• I like to work with Headphones on listening to music. Not just any Headphones, but full over-ear Active Noise Cancelling headphones that drown out the outside world to not much more than a low hum. So I ALSO wanted a Visual indication for the end of the timer, like changing the colour of my Desk lamp, or flashing the LED Strip I have on my desk on and off.
• On days when I’m working in the office, I’m sure my colleagues wouldn’t be particularly pleased with me taking out a Kitchen timer and having it go off every 25 minutes.

There ARE Apps that can do the tracking for you, just search Pomodoro in the App Store of your choice and I guarantee you’ll find a bunch of them. I even made my own as part of the “100 Days of Code – Python” Challenge I set myself at the start of last year.
The problem with these apps is that they don’t have control of my Desk lamp or LED Strips, not to mention, installing one of the Desktop apps on my work computer would likely not meet with the “Acceptable Use” policy for my work laptop.

Planning

With any workflow setup, it’s important to plan out how we want it to work before even opening up our Home Assistant interface, to properly understand what it is that we’re trying to acheive and the steps and decision points of how we’re going to get there.

I find it can be helpful to create a Flow Chart of the workflow. Below is the most basic flowchart I came up with designing this setup

Setting Up the “Helper” Entities

We’re going to need to setup a handful of Helper Entities in Home Assistant to make our Pomodoro Timer. We’ll need some Automations too, but we’ll get to those later.

Obviously, we’re going to need a Timer Entity.
To setup your a Timer Entity, in Home Assistant, go to “Settings” -> “Devices and Services” and select the “Helpers” Tab, then click “Add Helper” and select the “Timer” Helper.
Name the Timer something easily Identifiable like “Pomodoro Timer”. It’s not important, but I also setup the timer with a default setting of 25 minutes.

We’re also going to need a Counter Entity.
To set this up, much like the Timer Entity, in the “Helpers” page, we’ll click “Add Helper” and select “Counter”.
Name the Counter Entity something relevant – in this case – “Completed Pomodoros”, and because we get to 4 completed pomodoros and then take a longer break, I also set the “Maximum” in my Counter to 4.

I also chose to setup a second Counter with no Maximum called “Total Pomodoros” to count how many Pomodoro’s I complete in a day.

We also need a “Dropdown” or “Input Select” Entity Which we’ll call “Pomodoro – NEXT Task” with 3 options:

• Pomodoro
• Short Break
• Long Break

You also need to have a way to start the timer.
I chose to set this up more than one way to do this because I want it to be easily accessible when I’m at my Work From Home Desk, but also a way to trigger it from the Home Assistant UI or another method when I’m not at my desk. i.e. Working in the office or out in the workshop. So I also setup a “Button” Helper Entity called “Pomodoro Button”

Making it work with Automations

Now that we’ve got the entities setup, we’re going to need to setup at least 2 Automations to handle the Pomodoro Timer. One to start the timer when the button gets pressed, and one to do something when the timer ends.

Starting the Timer

Trigger

For the Trigger, I added a Zigbee Button single press, and also “changes to any state” with the Button Helper we created before.

Conditions

In this case, we don’t need Conditions for our Automation, because we’re going to handle all the Conditions in the Actions section of the Automation.

Actions

I start with an “If – Then” Block in Actions, and the “Condition” I want to check for is whether the timer is “Idle” or not.
If it IS idle, then, we’re going to create another 3 “If-Then” blocks in the “Actions” where we’re looking for the value of the “Next Task” Dropdown in each of those “If-Then” blocks.

For the First one, if the Next Task is “Pomodoro” the Action will be to start the timer for 25 minutes

The Second: if the Next Task is “Short Break” start the Timer for 5 minutes

and the Third: The Task is “Long Break” and the Action is to start the timer for 30 minutes.

Lastly in the OUTER “If-Then” Block – where we check if the timer is Idle – we’ll add an “Else” section, where we’ll add an action to Cancel the Timer.

Here’s the YAML Code for MY Automation:

alias: Pomodoro - Start Timer
description: ""
trigger:
  - device_id: e68ee9bed4b7fac4c1a0015048cdcd40
    domain: zha
    platform: device
    type: remote_button_short_press
    subtype: remote_button_short_press
  - platform: state
    entity_id:
      - input_button.pomodoro_start_timer
    to: null
condition: []
action:
  - if:
      - condition: state
        entity_id: timer.pomodoro_timer
        state: idle
    then:
      - if:
          - condition: state
            entity_id: input_select.pomodoro_next_task
            state: Pomodoro
        then:
          - service: timer.start
            metadata: {}
            data:
              duration: "00:25:00"
            target:
              entity_id: timer.pomodoro_timer
      - if:
          - condition: state
            entity_id: input_select.pomodoro_next_task
            state: Short Break
        then:
          - service: timer.start
            metadata: {}
            data:
              duration: "00:05:00"
            target:
              entity_id: timer.pomodoro_timer
      - if:
          - condition: state
            entity_id: input_select.pomodoro_next_task
            state: Long Break
        then:
          - service: timer.start
            metadata: {}
            data:
              duration: "00:30:00"
            target:
              entity_id: timer.pomodoro_timer
    else:
      - service: timer.cancel
        metadata: {}
        data: {}
        target:
          entity_id: timer.pomodoro_timer
mode: single

At the End of the Timer

For the second Automation, We need to define the behaviour when the timer ends:

Trigger

For The Trigger, we’re looking for the Entity State of the Timer to change from Any State, to “Idle”.
In testing, any time the timer stops, it returns to an Idle state.

Conditions

Again, we’re not handling Conditions here, we’ll handle them in “If-Then” blocks in the Actions section

Action

Again, in the Action section, I Started with an “If-Then” block.

We’re checking if the “Next Task” Helper value is “Pomodoro”, and if it is, We increment our Counters

We then add another “If-Then” Action after incrementing the Counters to check if the “Completed Pomodoros” Counter has a “Numeric State” less than 4.

If it is less than 4, we’ve not completed 4 Pomodoros yet, so we only get a short break, so for the action in this If-Then block, we set the Input Select for “Next Task” to “Short Break.

We’ll also add an “Else” block to this If-Then Action, because if our Counter is NOT less than 4, it will be 4, meaning we’ve completed 4 Pomodoros, and get a long break.
So our “Else” Action will be to set the Input Select for our “Next Task” helper to “Long Break”

I’m also going to add another action into the “Else” section here to reset the “Completed Pomodoros” Counter back to zero so as soon as we’ve completed our 4th Pomodoro, the counter gets reset, and we take a long break. When we come back from the break, we count up from Zero again.

This is also why I created the “Total Pomodoros” counter so we can track how many we do over the course of a day.

In this OUTER IF-Then block – where we decided whether the “Next Task” was Pomodoro or not, if it’s NOT Pomodoro, it has to be one of the “Breaks” and the only place we can go from one of the breaks, is into a Pomodoro, so we setup an “Input Select” action to set “Next Task” to Pomodoro.

FINALLY in this Automation we need a way to alert us that our Timer has finished. I opted for more than one mechanism in my case, and I put them in a “Run in parallel” block so they happen concurrently.
I’m sending a Notification to my Home Assistant Mobile app, and I’m also turning on a WLED controlled light strip on my Desk, but ONLY if I’m at Home.

For the Notification to my Mobile App, I’m using Templating in the message to show what the value of “Next Task” is to prompt me as to what my next action needs to be, and I’m sending it as a “Critical” notification so that it makes a sound regardless of my phone being on silent or not.

The Full Code for this Automation is here:

alias: Pomodoro - Timer End
description: ""
trigger:
  - platform: state
    entity_id:
      - timer.pomodoro_timer
    from: null
    to: idle
condition: []
action:
  - if:
      - condition: state
        entity_id: input_select.pomodoro_next_task
        state: Pomodoro
    then:
      - service: counter.increment
        metadata: {}
        data: {}
        target:
          entity_id:
            - counter.pomodoro_completed_pomodoros
            - counter.pomodoro_total_pomodoros
      - if:
          - condition: numeric_state
            entity_id: counter.pomodoro_completed_pomodoros
            below: 4
        then:
          - service: input_select.select_option
            metadata: {}
            data:
              option: Short Break
            target:
              entity_id: input_select.pomodoro_next_task
        else:
          - service: input_select.select_option
            metadata: {}
            data:
              option: Long Break
            target:
              entity_id: input_select.pomodoro_next_task
          - service: counter.reset
            metadata: {}
            data: {}
            target:
              entity_id: counter.pomodoro_completed_pomodoros
    else:
      - service: input_select.select_option
        metadata: {}
        data:
          option: Pomodoro
        target:
          entity_id: input_select.pomodoro_next_task
  - parallel:
      - if:
          - condition: state
            entity_id: person.stuart
            state: home
        then:
          - service: light.turn_on
            metadata: {}
            data:
              rgb_color:
                - 255
                - 0
                - 0
            target:
              entity_id: light.wled_2
      - service: notify.mobile_app_stuey_s_iphone
        data:
          message: >-
            Your Pomodoro Timer has finished. Time for a {{
            states('input_select.pomodoro_next_task') }}
          title: POMODORO
          data:
            push:
              sound:
                name: default
                critical: 1
                volume: 0.5
mode: single

Optional, but kinda not?

Lastly, I’ll setup a 3rd Automation, and this one is just going to reset the counters to Zero, and the “Next Task” to Pomodoro.

Trigger

For the Trigger, I’ll set it to a “Time” Trigger of “midnight” every night, and I also setup a “Double Press” of my Zigbee Button to also trigger the automation

Conditions

We’re not setting Conditions on this Automation

Actions

We just need 2 actions in this Automation:

1. Reset both the “Completed Pomodoros” and “Total Pomodoros” counters to Zero
2. Set the “Next Task” to “Pomodoro” with the input select Action.

For the full code of the Automation:

alias: POMODORO - Reset Counters at Midnight
description: ""
trigger:
  - platform: time
    at: "00:00:00"
  - device_id: e68ee9bed4b7fac4c1a0015048cdcd40
    domain: zha
    platform: device
    type: remote_button_double_press
    subtype: remote_button_double_press
condition: []
action:
  - service: counter.reset
    metadata: {}
    data: {}
    target:
      entity_id:
        - counter.pomodoro_total_pomodoros
        - counter.pomodoro_completed_pomodoros
  - service: input_select.select_option
    metadata: {}
    data:
      option: Pomodoro
    target:
      entity_id: input_select.pomodoro_next_task
mode: single

All done!

So that’s it, We’ve setup a Pomodoro Timer in Home Assistant.
I’ve been using this a little bit since releasing the video, and in fact I used it a few times while writing up this Blog Post.
It’s already proven to be helpful, and I’m going to try to integrate it even more into my workflows to help keep me on track and being productive when my ADHD has other plans.