EverShelf/docs/wiki/Home-Assistant.md

Home Assistant Integration

EverShelf integrates natively with Home Assistant to bring your pantry data into your smart-home automations.

Capabilities:

• 📡 REST sensors — expose pantry counts as HA sensor entities (expiring, expired, shopping list, total items)
• 🔔 Webhooks — trigger HA automations on pantry events (expiry alerts, shopping additions, stock updates)
• 📣 Push notifications — send alerts to your phone via any HA notify.* service
• 🔊 TTS on smart speakers — read recipe steps aloud on any HA media_player entity
• ⚙️ In-app config panel — configure everything from Settings → 🏠 tab (no need to edit .env manually)

---

Quick Setup

1. Generate a Long-Lived Access Token in Home Assistant:

   • Open HA → your Profile (bottom-left avatar) → Security → Long-Lived Access Tokens → Create Token
   • Copy the generated token — you won't see it again.

2. Open EverShelf Settings → tab 🏠 Home Assistant.

3. Fill in Home Assistant URL (e.g. http://homeassistant.local:8123) and paste the token.

4. Click Test connection — you should see ✅.

5. Enable the features you want (TTS, Webhooks, REST Sensors) and click Save HA settings.

---

REST Sensors

Add EverShelf pantry data as native HA sensor entities that update automatically.

Endpoints

URL	Returns	Sensor
/api/?action=ha_sensor	Items expiring soon (≤HA_EXPIRY_DAYS days)	sensor.evershelf_overview
/api/?action=ha_sensor&sensor=expired	Expired items count	sensor.evershelf_expired
/api/?action=ha_sensor&sensor=shopping	Shopping list item count	sensor.evershelf_shopping
/api/?action=ha_sensor&sensor=total	Total pantry items	sensor.evershelf_total
/api/?action=ha_sensor&sensor=product	Full inventory — all items with complete details	sensor.evershelf_products
/api/?action=ha_sensor&sensor=product&id=42	Full details for inventory row id=42	—
/api/?action=ha_sensor&sensor=product&name=milk	Full details for items whose name contains "milk"	—
/api/?action=ha_sensor&sensor=product&location=frigo	All items in a specific location	—

Generate & Copy YAML

In Settings → 🏠 Home Assistant → REST Sensors card, click Copy YAML to get a ready-to-paste configuration.yaml block that already contains your EverShelf URL.

Manual YAML example

# configuration.yaml
sensor:
  - platform: rest
    name: "EverShelf Overview"
    unique_id: evershelf_overview
    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor"
    scan_interval: 300        # seconds
    value_template: "{{ value_json.state }}"
    json_attributes:
      - expiring_soon
      - expiring_3d
      - expired_items
      - total_items
      - shopping_items
      - expiring_list      # full product details for expiring items
      - expired_list       # full product details for expired items
      - low_stock_list     # full product details for items with quantity ≤ 1
      - next_expiry_name
      - next_expiry_date
      - days_to_next_expiry
      - last_updated
    unit_of_measurement: "items"

  - platform: rest
    name: "EverShelf Shopping Count"
    unique_id: evershelf_shopping
    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor&sensor=shopping"
    scan_interval: 180
    value_template: "{{ value_json.state }}"
    unit_of_measurement: "items"

  # Full product inventory — each item includes all details (location, brand, category, …)
  - platform: rest
    name: "EverShelf Products"
    unique_id: evershelf_products
    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor&sensor=product"
    scan_interval: 600
    value_template: "{{ value_json.state }}"
    json_attributes:
      - items
      - last_updated
    unit_of_measurement: "items"

Restart Home Assistant after editing configuration.yaml.

Every product entry inside expiring_list, expired_list, low_stock_list, and sensor=product responses follows the same schema:

{
  "product_id":       42,
  "inventory_id":     7,
  "name":             "Latte intero",
  "brand":            "Parmalat",
  "category":         "Lattiero-caseari",
  "quantity":         2.0,
  "unit":             "conf",
  "default_quantity": 1000.0,
  "package_unit":     "ml",
  "location":         "frigo",
  "expiry_date":      "2025-06-15",
  "days_remaining":   3,
  "opened_at":        "2025-06-10",
  "vacuum_sealed":    false
}

Field details:

Field	Type	Description
product_id	int	Products table ID
inventory_id	int	Inventory row ID
name	string	Product name
brand	string|null	Brand (if set)
category	string|null	Category (if set)
quantity	float	Current quantity in inventory
unit	string	Unit (conf, g, ml, pz, …)
default_quantity	float	Default package size (e.g. 1000 for 1-litre carton)
package_unit	string|null	Unit of the default package (g, ml)
location	string|null	Storage location (frigo, freezer, dispensa, …)
expiry_date	string|null	ISO date YYYY-MM-DD
days_remaining	int|null	Days until expiry (negative = already expired)
opened_at	string|null	ISO date when the package was opened
vacuum_sealed	bool	Whether the item is vacuum-sealed

---

Webhook Automations

EverShelf fires an HTTP POST to your HA webhook URL when pantry events occur.

Create the HA Webhook Automation

1. HA → Settings → Automations & Scenes → Create Automation
2. Click Add Trigger → choose Webhook
3. HA generates a Webhook ID — copy it
4. Paste the ID into Settings → 🏠 Home Assistant → Webhook ID
5. Select which events should trigger the webhook

Supported Events

Event key	When it fires
expiry	Daily cron — items expiring within HA_EXPIRY_DAYS days
shopping_add	Item added to the shopping list
stock_update	Inventory quantity changed
barcode_scan	(reserved for future use)

Webhook Payload (POST body)

{
  "event": "expiry_alert",
  "timestamp": "2025-06-12T08:00:00+00:00",
  "data": {
    "type": "expiring_soon",
    "count": 3,
    "days": 3,
    "summary": "Milk, Yogurt, Butter",
    "items": [
      {
        "product_id": 42,
        "inventory_id": 7,
        "name": "Milk",
        "brand": "Parmalat",
        "category": "Dairy",
        "quantity": 2.0,
        "unit": "conf",
        "default_quantity": 1000.0,
        "package_unit": "ml",
        "location": "frigo",
        "expiry_date": "2025-06-14",
        "days_remaining": 2,
        "opened_at": "2025-06-10",
        "vacuum_sealed": false
      }
    ]
  }
}

Example: Expiry Alert → Telegram

alias: EverShelf Expiry Alert
trigger:
  - platform: webhook
    webhook_id: "evershelf_webhook_abc123"   # ← your Webhook ID
action:
  - service: notify.telegram_bot
    data:
      message: >
        🥫 EverShelf: {{ trigger.json.data.count }} product(s) expiring soon
        {% for item in trigger.json.data.items %}
        — {{ item.name }}{% if item.brand %} ({{ item.brand }}){% endif %} ·
          {{ item.quantity }} {{ item.unit }} · 📍 {{ item.location }} ·
          expires {{ item.expiry_date }} ({{ item.days_remaining }} days)
        {% endfor %}

Example: Automation on location

You can filter by location in the automation template to only alert for fridge items:

condition:
  - condition: template
    value_template: >
      {{ trigger.json.data.items | selectattr('location','eq','frigo') | list | length > 0 }}

---

Push Notifications

If you prefer to receive push alerts without using webhooks, configure a HA notify service directly:

1. Find your notify service name in HA: Developer Tools → Services → search notify
2. Paste it into Settings → 🏠 → Notify service (e.g. notify.mobile_app_my_phone)
3. Save

EverShelf will call this service from the cron job whenever expiry alerts fire.

---

TTS on Smart Speakers

Read recipe steps aloud on an Amazon Echo, Google Home, Sonos, or any HA media_player.

Configuration

1. Enter the Entity ID of your media player (e.g. media_player.kitchen_display)
   • Find it in HA: Developer Tools → States
2. Click Apply HA preset to TTS tab — this auto-fills the TTS tab with the correct HA endpoint and auth headers
3. Save settings

How it Works

When recipe step TTS is triggered, EverShelf calls:

POST /api/services/tts/speak
Authorization: Bearer <HA_TOKEN>
{
  "entity_id": "media_player.kitchen_display",
  "message": "Add 200 g of flour and mix well."
}

The request is proxied through the EverShelf PHP backend (avoids CORS / mixed-content issues).

---

Environment Variables Reference

All settings are configurable from .env or from the in-app Settings panel.

Variable	Default	Description
HA_ENABLED	false	Master switch for all HA features
HA_URL	(empty)	Base URL of HA instance, no trailing slash
HA_TOKEN	(empty)	Long-Lived Access Token
HA_TTS_ENTITY	(empty)	media_player entity for TTS
HA_WEBHOOK_ID	(empty)	Webhook trigger ID from HA automation
HA_WEBHOOK_EVENTS	expiry,shopping_add,stock_update	Comma-separated list of events
HA_NOTIFY_SERVICE	(empty)	HA notify service (e.g. notify.mobile_app_phone)
HA_EXPIRY_DAYS	3	Days before expiry to trigger the daily alert

---

Troubleshooting

Test shows ❌ "Connection failed"

• Verify the URL is reachable from the EverShelf server (not just your browser)
• If using HTTPS with a self-signed certificate, the server-side cURL request may fail — use HTTP on the local network instead
• Check that port 8123 (or your custom port) is open on the HA host

Test shows ❌ "bad_token"

• The Long-Lived Access Token may have expired or been revoked — generate a new one in HA Profile

Webhook not firing

• Confirm HA_ENABLED=true and the Webhook ID is exactly as shown in HA
• Check the EverShelf cron is running (/api/cron_smart_shopping.php every 5 minutes)
• For shopping/stock events: verify the event name is in HA_WEBHOOK_EVENTS

TTS not speaking

• Ensure the media player entity is online in HA (check its state in Developer Tools)
• Try the "Apply HA preset to TTS tab" button and send a test from the TTS tab
• Check HA logs for tts.speak errors (some platforms require tts_options)

Sensors show unavailable in HA

• The EverShelf URL must be reachable from the HA host
• If running EverShelf behind a reverse proxy, ensure /api/ is accessible
• Use scan_interval ≥ 60 to avoid hammering the server