Home Assistant integration for EPG (Electronic Program Guide) sensors, using the open-epg.com EPG guide. This integration provides real-time program guide data as sensors within Home Assistant, allowing you to display current and upcoming TV programming.
The integration now uses open-epg.com as its EPG data source. This change was implemented because bevy.be, the previous provider, has transitioned their services. This update is seamless for users and requires no configuration changes.
- Retrieve EPG data from open-epg.com to create program guide sensors in Home Assistant.
- Supports creating custom EPG files with specific channels for personalized tracking.
- Easy integration with Home Assistant's Lovelace UI to display TV programming data.
- Home Assistant: Ensure you have Home Assistant installed.
- HACS: Home Assistant Community Store (recommended for easy installation).
- open-epg.com Account: Required if using custom EPG files.
- Open HACS in your Home Assistant dashboard.
- Search for "HomeAssistant-EPG" in HACS and install it.
- Download the repository.
- Copy the
custom_components/EPGfolder into your Home Assistant configuration directory undercustom_components.
The integration now uses Home Assistant's UI configuration flow, making it easier to set up and manage. Follow these steps to configure:
-
Go to Settings > Devices & Services in Home Assistant.
-
Click Add Integration and search for "EPG".
-
Follow the prompts:
-
File Name: Enter the file name or generated file code from open-epg.com.
-
Track Full Schedule: Enable this option if you want to track the full schedule (2 days). Note that enabling this may increase database size significantly.
-
Generated File Code: Specify if you're using a custom file.
-
-
Select the channels you want to track from the dynamically fetched list.
-
Complete the setup to create sensors for the selected channels.
open-epg.com allows the creation of custom EPG files with selected channels. To create a custom file:
- Register for a free account at open-epg.com.
- Select channels to include in your custom EPG file.
- Once generated (updated daily), use the unique file ID (e.g., 122DjgdtAA), visible in the generated URL.
You can integrate the EPG information with Home Assistant's assist feature using the following automation. Please note that this is a basic implementation example and can be considered a "hack" to expose EPG sensor data to the Assist conversation agent. You are free to modify the command triggers, the id of the automation, and even use a different conversation agent_id if you have other agents configured.
To add this automation to your Home Assistant configuration, you can either:
- Use the Automation UI: Go to Settings > Automations & Scenes, click on the + button to create a new automation, and then click on the three dots in the top right corner to select "Edit in YAML". Paste the YAML code below and save.
- Use configuration.yaml: Add the automation directly to your
automations.yamlfile (or include it from yourconfiguration.yaml).
alias: TV Guide Information
description: Provides TV program information by querying EPG entities.
id: your_unique_automation_id
triggers:
- trigger: conversation
command:
- what's on {channal}
- what's on {channal} at {time}
- what is playing on {channal}
- what is the program on {channal}
- tell me what's on {channal}
- what is next on {channal}
- what's playing next on {channal}
- when is {program_title} on
- when is {program_title} playing
- what time is {program_title} on
- is {program_title} on today
- is {program_title} on tomorrow
conditions: []
actions:
- action: conversation.process
metadata: {}
data:
agent_id: conversation.google_generative_ai
text: >-
'{{trigger.user_input.text }}? answer based on following information: {%
for entity in integration_entities("epg") %}{{ state_attr(entity,
"friendly_name") }} : current: {{ states(entity) }} {{state_attr(entity,
"today") }} {%- endfor %}'
response_variable: result
- set_conversation_response: "{{ result.response.speech.plain.speech }}"
mode: singleThe following services are implemented by the component:
Service Name: epg.update_channels
Description: Force update Guide file.
Fields:
| Name | Description | Required | Selector Type |
|---|---|---|---|
entry_id |
The ID of the config_entry to update | true | Config Entry (filtered by 'epg' integration) |
Example Service Call: You can call this service from the Developer Tools -> Services menu in Home Assistant.
service: epg.update_channels
data:
entry_id: a9dcc3edcdd1e421c62ea735a9747cd6 # Replace with the actual ID of your EPG config entryService Name: Search EPG Program
Description: Searches for a program title across configured EPG channels and returns matching schedules directly in the response.
Fields:
| Name | Description | Required | Example | Selector Type |
|---|---|---|---|---|
title |
The program title to search for (case-insensitive,supports regex). | true | "News at Ten" | Text input |
channel_name |
(Optional) Filter results to only this specific channel name (exact match, case-sensitive from guide data). | false | "BBC One HD" | Text input |
date_filter |
(Optional) Filter results by date. 'any' includes 'today' and 'tomorrow'. | false | 'today' | Select input |
Example Service Call:
service: epg.search_program
data:
title: "Good Men"
channel_name: "AMC - Canada HD" #Optional
date_filter: "today" #Optional
Example Service Response:
The service will return a list of matching programs with their details.
results:
- channel_name: AMC - Canada HD
title: A Few Good Men
description: >-
Navy lawyers (Tom Cruise, Demi Moore) defend two Marines accused of
killing a private at the naval station at Guantanamo Bay, Cuba. Starring
Tom Cruise, Jack Nicholson, Demi Moore.
start_time: "14:30"
end_time: "17:30"
date: "2025-04-27"
start_datetime_iso: "2025-04-27T14:30:00"
Recommended: For a more visually appealing and feature-rich display of your EPG data, it's highly recommended to use the Lovelace EPG Card. This custom card is specifically designed to work seamlessly with the HomeAssistant-EPG integration and provides a dynamic timeline view of your TV programming.
)
Alternative (Basic Markdown Example): If you prefer a simpler approach, you can use the following example to display today’s programming on a Lovelace card using Markdown:
type: markdown
content: |
{% for time in states.sensor.epg_an_hui_wei_shi.attributes.today -%}
{% set program=states.sensor.epg_an_hui_wei_shi.attributes.today[time] %}
<details>
<summary>{{time}}: {{ program.title}}</summary>
{{ program.desc}}
</details>
{%- endfor %}.
title: today
- Full Schedule Error: If using full_schedule: true, you may encounter size limit issues in Home Assistant’s database. If so, set full_schedule: false.
- Missing Channels: Ensure you’re using the correct file ID, especially for custom files.
If you encounter any problems or need assistance, you can open an issue on the GitHub repository. To help us debug the issue, please enable debug logging for the integration and provide relevant logs:
-
Enable debug in the UI or add the following to your
configuration.yamlfile:logger: default: warning logs: custom_components.epg: debug -
Restart Home Assistant to apply the changes.
-
Reproduce the issue and check the logs in Settings > System > Logs or the
home-assistant.logfile in your configuration directory.
When opening an issue, include:
-
A detailed description of the problem.
-
Steps to reproduce the issue.
-
Relevant logs from Home Assistant with debug mode enabled for the integration.
If you find it helpful or interesting, consider supporting me by buying me a coffee or starring the project on GitHub! ☕⭐ Your support helps me improve and maintain this project while keeping me motivated. Thank you! ❤️