diff --git a/README.md b/README.md index c157ecb..39b3053 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,152 @@ Configuration is done via the UI: Webhooks let Clockify push timer changes to Home Assistant instantly instead of the integration having to poll the Clockify API on a schedule, which keeps API usage low and avoids hitting Clockify's rate limits, even on a free-tier. +## Entities + +Each configured project gets a device named `Clockify - ` with these entities (shown for a project called "My Project"): + +| Entity | Description | +| --- | --- | +| `switch.clockify_my_project_timer` | Start/stop the Clockify timer for the project | +| `sensor.clockify_my_project_timer_status` | `Running` or `Idle` | +| `sensor.clockify_my_project_hours_today` | Hours logged today, in decimal hours (e.g. `3.25`) | +| `sensor.clockify_my_project_hours_this_week` | Hours logged this week | +| `sensor.clockify_my_project_hours_this_month` | Hours logged this month | +| `sensor.clockify_my_project_hours_this_year` | Hours logged this year | + +The hours sensors refresh every 5 minutes, and immediately when a timer starts or stops. + +## Examples + +Replace `my_project`, `your_phone`, `person.you` and `zone.work` with your own entities. + +### Live timer notification on your phone + +Shows a notification with a running stopwatch while the timer is on, starting from the hours already logged today, plus a second notification with a **Stop timer** button. The stopwatch ticks on the device, so Home Assistant sends no repeated updates. Requires the Home Assistant Companion app on a version that supports live update notifications. + +```yaml +alias: "Clockify: Live timer notification" +triggers: + - trigger: state + entity_id: switch.clockify_my_project_timer + to: "on" + # Give the hours sensor a moment to refresh after the timer starts + for: + seconds: 10 + id: start + - trigger: state + entity_id: switch.clockify_my_project_timer + to: "off" + id: stop + - trigger: event + event_type: mobile_app_notification_action + event_data: + action: clockify-stop-timer + id: action-stop +actions: + - choose: + - conditions: + - condition: trigger + id: start + sequence: + - variables: + elapsed_seconds: >- + {{ (states('sensor.clockify_my_project_hours_today') | float(0) * 3600) | int }} + - action: notify.mobile_app_your_phone + data: + title: Clockify — My Project + message: "Today: {{ states('sensor.clockify_my_project_hours_today') }} h" + data: + tag: clockify_timer_activity + live_update: true + chronometer: true + when: "{{ -1 * elapsed_seconds }}" + when_relative: true + notification_icon: mdi:timer-play-outline + notification_icon_color: "#03A9F4" + color: "#03A9F4" + # Live notifications can't show action buttons, so the stop button gets its own notification + - action: notify.mobile_app_your_phone + data: + title: Clockify + message: The timer is running. + data: + tag: clockify_timer_active + actions: + - action: clockify-stop-timer + title: Stop timer + - conditions: + - condition: trigger + id: stop + sequence: + - action: notify.mobile_app_your_phone + data: + message: clear_notification + data: + tag: clockify_timer_activity + - action: notify.mobile_app_your_phone + data: + message: clear_notification + data: + tag: clockify_timer_active + - conditions: + - condition: trigger + id: action-stop + sequence: + - action: switch.turn_off + target: + entity_id: switch.clockify_my_project_timer +mode: queued +max: 10 +``` + +### Start and stop the timer when you arrive at and leave work + +Starts the timer two minutes after you enter the work zone (so driving past doesn't count) and stops it when you leave, then sends you the hours logged today. + +```yaml +alias: "Clockify: Track time at work" +triggers: + - trigger: zone + entity_id: person.you + zone: zone.work + event: enter + id: enter + - trigger: zone + entity_id: person.you + zone: zone.work + event: leave + id: leave +actions: + - choose: + - conditions: + - condition: trigger + id: enter + sequence: + - delay: + minutes: 2 + # Skip if you already left again during the delay + - condition: zone + entity_id: person.you + zone: zone.work + - action: switch.turn_on + target: + entity_id: switch.clockify_my_project_timer + - conditions: + - condition: trigger + id: leave + sequence: + - action: switch.turn_off + target: + entity_id: switch.clockify_my_project_timer + - action: notify.mobile_app_your_phone + data: + title: Clockify stopped + message: >- + You worked {{ states('sensor.clockify_my_project_hours_today') }} hours today. +mode: restart +``` + ## License See [LICENSE](LICENSE).