Overview

HArvest creates two categories of entities in Home Assistant.

Global entities exist for the lifetime of the integration. Per-token entities are created when a token is created and become unavailable when the token is permanently deleted.

Global sensors

These sensors reflect the state of the entire HArvest integration, not any specific token. They are created when the integration loads and removed when it unloads.

binary_sensor.harvest_running

Goes off if the integration fails to start, hits a fatal error, or is reloaded. Useful for an alert automation that notifies you if HArvest stops unexpectedly after a HA update or restart.

sensor.harvest_active_sessions

A session is counted from the moment auth_ok is sent until the WebSocket closes. Useful for monitoring live traffic and verifying that a token revocation dropped all expected sessions.

sensor.harvest_active_tokens

A token is counted as active if its status is active AND it has not expired AND the current time is within its schedule window (if one is set). Paused tokens are not counted.

sensor.harvest_commands_today

Counts accepted service calls (turn_on, set_brightness, etc.) from widget visitors. Rejected commands - rate-limited or permission-denied - are not counted. Resets at midnight.

sensor.harvest_errors_today

Counts authentication rejections - invalid tokens, denied origins, failed HMAC signatures, and similar. A low background count is normal (bots probe any public endpoint). A sudden spike may indicate a misconfigured widget or a probing attempt. Resets at midnight.

sensor.harvest_db_size

The harvest_activity.db SQLite file size. The automatic retention policy (default 30 days, configurable in Settings) prevents unbounded growth. Useful on long-running or high-traffic installations where you want to keep an eye on storage.

Per-token sensors

For each token, HArvest creates four sensors. Entity IDs are derived from the token's label, converted to a slug:

sensor.harvest_{label_slug}_{metric}

For example, a token labelled "Bedroom Widgets" produces:

sensor.harvest_bedroom_widgets_sessions
sensor.harvest_bedroom_widgets_last_seen
sensor.harvest_bedroom_widgets_last_origin
sensor.harvest_bedroom_widgets_commands_today

If two tokens produce the same slug, HA appends a numeric suffix to disambiguate. The exact entity IDs for any token are shown in the panel widget detail screen under Diagnostics.

sensor.harvest_{label}_sessions

Number of visitors currently connected using this token. Updates immediately when a session opens or closes.

sensor.harvest_{label}_last_seen

ISO 8601 timestamp of the most recent successful auth for this token. Device class: timestamp. Shows unknown if the token has never been used. Updates immediately on successful auth.

sensor.harvest_{label}_last_origin

The HTTP Origin header value from the most recent successful connection. Useful for verifying that traffic is coming from the expected website. Updates immediately on successful auth.

sensor.harvest_{label}_commands_today

Commands sent by visitors using this specific token since midnight. Updates immediately when a command is processed.

Global control entities

These let automations and scripts act on the entire integration.

switch.harvest_kill_switch

Turning it on closes every active WebSocket session immediately and refuses all new auth attempts until turned back off. It stays in sync with the kill switch toggle in the panel Settings screen - changes in either place are reflected in both. Useful for away-mode automations or quickly suspending all widget access without revoking any tokens.

button.harvest_close_all_sessions

Unlike the kill switch, this button does not block new connections - sessions close and then reconnect automatically when visitors next interact with a widget. Useful for forcing a clean reconnect after a network change or kicking stale sessions on a schedule.

Per-token control entities

switch.harvest_{label}_paused

Turning it on pauses the token - new auth attempts are rejected and existing sessions are closed on the next keepalive tick. Turning it off resumes the token without any other changes. This is non-destructive: the token is not revoked, its configuration is unchanged, and it can be unpaused at any time.

One switch is created per token. The entity ID follows the same slug convention as the sensors: switch.harvest_{label_slug}_paused.

Lifecycle

Update frequency

Per-token sensors are event-driven and always current. Global aggregate sensors (active sessions, commands today, etc.) may lag up to 30 seconds behind the actual state.

Automation examples

Suspend access when leaving home

automation:
  alias: "HArvest - suspend on departure"
  trigger:
    - platform: state
      entity_id: person.your_name
      to: "not_home"
  action:
    - service: switch.turn_on
      target:
        entity_id: switch.harvest_kill_switch

Resume access on arrival

automation:
  alias: "HArvest - resume on arrival"
  trigger:
    - platform: state
      entity_id: person.your_name
      to: "home"
  action:
    - service: switch.turn_off
      target:
        entity_id: switch.harvest_kill_switch

Pause a token on a schedule

automation:
  alias: "HArvest - pause bedroom token overnight"
  trigger:
    - platform: time
      at: "22:00:00"
  action:
    - service: switch.turn_on
      target:
        entity_id: switch.harvest_bedroom_widgets_paused

automation:
  alias: "HArvest - unpause bedroom token at 7am"
  trigger:
    - platform: time
      at: "07:00:00"
  action:
    - service: switch.turn_off
      target:
        entity_id: switch.harvest_bedroom_widgets_paused

Alert if HArvest stops running

automation:
  alias: "HArvest stopped"
  trigger:
    - platform: state
      entity_id: binary_sensor.harvest_running
      to: "off"
      for:
        minutes: 2
  action:
    - service: notify.notify
      data:
        title: "HArvest is not running"
        message: >
          HArvest stopped at {{ now().strftime('%H:%M') }}.
          Check the HA logs and reload the integration if needed.

Alert on error spike

automation:
  alias: "HArvest error spike"
  trigger:
    - platform: numeric_state
      entity_id: sensor.harvest_errors_today
      above: 50
  action:
    - service: notify.notify
      data:
        title: "HArvest: high error count"
        message: >
          {{ states('sensor.harvest_errors_today') }} auth errors today.
          Check the HArvest activity log for details.

Alert on unexpected sessions for a token

automation:
  alias: "HArvest unexpected traffic"
  trigger:
    - platform: numeric_state
      entity_id: sensor.harvest_bedroom_widgets_sessions
      above: 5
  action:
    - service: notify.notify
      data:
        title: "Unexpected HArvest traffic"
        message: >
          {{ states('sensor.harvest_bedroom_widgets_sessions') }} active sessions
          on Bedroom Widgets. Last origin:
          {{ states('sensor.harvest_bedroom_widgets_last_origin') }}.

Dashboard examples

Global status glance card

type: glance
title: HArvest Status
entities:
  - entity: binary_sensor.harvest_running
    name: Running
  - entity: sensor.harvest_active_sessions
    name: Sessions
  - entity: sensor.harvest_active_tokens
    name: Tokens
  - entity: sensor.harvest_commands_today
    name: Commands today
  - entity: sensor.harvest_errors_today
    name: Errors today

Per-token status card

type: entities
title: Bedroom Widgets Token
entities:
  - entity: sensor.harvest_bedroom_widgets_sessions
    name: Active sessions
  - entity: sensor.harvest_bedroom_widgets_last_seen
    name: Last visitor
  - entity: sensor.harvest_bedroom_widgets_last_origin
    name: Last origin
  - entity: sensor.harvest_bedroom_widgets_commands_today
    name: Commands today
  - entity: switch.harvest_bedroom_widgets_paused
    name: Paused

Alert card when HArvest is not running

type: conditional
conditions:
  - entity: binary_sensor.harvest_running
    state: "off"
card:
  type: markdown
  content: >
    **HArvest is not running.** Check the HA logs and reload the
    integration under Settings > Devices & Services.