beste.schule for Home Assistant

Home Assistant integration for beste.schule timetables, absences, homework, exams, school notices, school time and grade averages.

This custom integration connects Home Assistant to beste.schule with a Personal Access Token. It creates calendar entries for lessons, absences, homework, exams and school-wide notices, exposes the current school-time state and adds grade average sensors per subject.

Features

• Timetable calendar with lessons from beste.schule
• Timetable history keeps past lessons from the setup day onward
• Absence calendar with all-day absence events
• Homework calendar from visible journal notes
• Exams calendar from visible journal notes
• School notices calendar for day-wide substitution notes
• Homework to-do list from visible journal notes
• School time binary sensor
• Current lesson and next lesson sensors
• Grade average sensors per subject
• Grade averages use beste.schule calculation rules and collection weights when available
• Class sensor
• Timetable JSON sensor for fabel-smith/stundenplan-card
• Options to enable or disable calendars and the homework to-do list
• Translations for English, German, Turkish, Polish and other common Home Assistant languages
• Support for multiple children in one beste.schule account

Installation with HACS

1. Open the HACS repository link above.
2. Confirm that the repository is added as an integration.
3. Install beste.schule from HACS.
4. Restart Home Assistant.
5. Go to Settings -> Devices & services -> Add integration.
6. Search for beste.schule.
7. Paste your beste.schule Personal Access Token.

Manual HACS repository setup

If the button does not work:

1. Open Home Assistant.

2. Go to HACS -> Integrations.

3. Open the three-dot menu and choose Custom repositories.

4. Add this repository URL:

   https://github.com/RF1705/beste-schule
   

5. Select Integration as the category.

6. Install beste.schule, restart Home Assistant and add the integration from Devices & services.

Personal Access Token

Create a token in your beste.schule user account:

1. Sign in to beste.schule.
2. Open your user account from your name in the top right corner.
3. Select API in the left menu.
4. Create a new token under Personal Access Token.
5. Copy the token and paste it into the Home Assistant setup dialog.

Entities

The integration currently creates:

• calendar: timetable
• calendar: absences
• calendar: homework
• calendar: exams
• calendar: notices
• todo: homework
• binary_sensor: school time
• sensor: current lesson
• sensor: next lesson
• sensor: class
• sensor: timetable card data
• sensor: grade average per subject

stundenplan-card compatibility

The 0.4 releases are compatible with fabel-smith/stundenplan-card through JSON source. This is a nice way to show the beste.schule timetable as a compact visual table in a Home Assistant dashboard.

Use the Timetable card sensor from this integration in the card:

type: custom:stundenplan-card
source_type: sensor
source_entity: sensor.<child>_stundenplan_card
source_attribute: plan
source_time_key: Stunde

The sensor exposes a single plan attribute for the current Monday-Friday week. The week changes automatically based on the current date. Cancelled lessons are included as Ausfall: <subject> cells.

Old test entities from early versions may remain in Home Assistant's entity registry after an update. They can be removed from Settings -> Devices & services -> Entities when they are no longer provided by the integration.

Multiple children

Starting with 0.6, one beste.schule token can create separate Home Assistant devices for multiple children from the same account. Each child gets its own calendars, sensors and homework to-do list.

Roadmap

• More robust substitution details as the API shapes become clearer

Support

This project is community-maintained and not affiliated with beste.schule.

If the integration helps you, you can support development here: buymeacoffee.com/rf1705.

License

MIT