Somtoday for Home Assistant – school schedules and calendar export

Share your Projects! Custom Integrations
1

Hi everyone,

I got frustrated I wasn’t able to get my son’s schedule in my own (Google) calendar. So I’ve created an unofficial Somtoday integration for Home Assistant.

Features

  • School selection and Somtoday browser login
  • Support for multiple children on one Somtoday account
  • A calendar entity containing all individual lessons
  • A separate calendar entity with one event covering the entire school day, from the first lesson until the last lesson
  • Export school-day events to a writable calendar
  • Export individual lessons to a separate calendar
  • Export every published school holiday as one multi-day, all-day event
  • Separate destinations and title templates per child
  • Google Calendar and generic Home Assistant calendar actions
  • Configurable look-ahead period and update interval
  • Reauthentication, Repairs notifications and privacy-safe diagnostics
  • Protection against duplicate events when a calendar provider is slow to return newly created appointments

Calendar titles support placeholders such as:

  • {student} – the child’s first name
  • {holiday} – the holiday name published by Somtoday

The integration only lists available calendars that advertise both create and delete support. Actual write permissions must also be enabled at the calendar provider. Google Calendar and Google Workspace require read/write authorization.

I recommend initially configuring Days ahead = 1 and checking the created appointments before increasing the period.

Installation

Add the following repository to HACS as a custom repository in the Integration category:

Install the latest release, restart Home Assistant and add Somtoday through Settings → Devices & services.

Important login note

Somtoday redirects the browser to a somtoday:// callback URL after authentication. Browsers usually don’t display this URL directly. The README explains how to retrieve it safely through the browser’s Network developer tools.

Current limitations

  • This is an unofficial integration and the Somtoday API may change.
  • Calendar integrations must support creating, deleting and querying events with stable UIDs.
  • Apple/iCloud through Home Assistant’s built-in CalDAV integration currently does not expose all functionality required for reliable full synchronization.
  • Only active timetable appointments are exported as lessons.
  • Changing or disabling a destination does not remove events previously written to the old calendar.
  • Availability of holidays and some appointment metadata may differ between schools and account types.

The integration has automated Home Assistant, HACS and translation validation, but additional real-world testing across schools and calendar providers would be very valuable.

Feedback, bug reports and contributions are welcome through GitHub:

2 Likes
SOMToday integration HA
2

Works perfect, thanks you very much :ok_hand:

1 Like
3

That’s great! Thank you for the feedback.

If you have any recommendations, let me know.

Next week I’ll test the vacations as there still pretty far ahead

4

Nice integration! But I tried the logging in, but it only shows redirects to https://inloggen.somtoday.nl/?auth=, not to somtoday://

I also have a Somtoday, but the config doesn’t accept that.

Also: should I login with the parent or child account?

Stupid me, needed to use the url in the popup :sweat_smile:

1 Like
5

Wow, so nice, thanks!

A recommendation: It would be nice if tasks/homework would be available in a ‘shoppinglist / todo list’

1 Like
6

Thanks!

I was thinking about homework. Still figuring out how to shape it though. It can become a pretty long list adding all homework to a todo list.

I’m adding tests as well as a separate calendar item.

7

Update: Assessment support added

The Somtoday integration now exports tests as calendar events:

  • Tests are added as separate calendar events.
  • Exact lesson times are used when available.
  • If Somtoday only provides a date, the test is shown as an all-day event.

Available now in the latest production release. Feedback is welcome!

8

Hi @ErikWie ,

There’s a new beta available (0.9.0-beta.1)⁠ if you’d like to test homework synchronization with an HA to-do list. You can choose a list per child and test task creation, due dates and completion status.

Please create a separate, empty to-do list first — it created 107 tasks in my case!

There’s also an optional setting to mark homework as completed in Somtoday from HA. This didn’t work with my parent account. It might work with a student account, but I haven’t tested that yet.

I’d love to hear your feedback!

9

I tried the beta, but i don’t get any tasks. It also says ‘Unavailable’ in the entities-screen.

10

Did you enable the option in the integration settings?

11

Yes, i created a todo-list first and then changed the settings and pointed to the todo-list.

Other small thing: if I create a local calender and point the classes to there, it still inserts the student-name, while I removed that from the setting.

12

Hi @ErikWie,

Thanks for testing! Beta 0.9.0-beta.2 is now available.

I fixed the issue with clearing the lesson title prefix. Existing exported lessons should also be updated during the next successful sync.

For the missing homework, I’ve added clearer diagnostics. This doesn’t yet confirm the underlying cause, but should help us identify it.

After updating and restarting HA, could you share:

  • Which exact entity shows Unavailable?

  • The attributes of the Homework sync sensor.

  • Any related Somtoday error in the HA logs.

Thanks again for your feedback!

13

image
image1702×356 10.2 KB

image
image1136×1176 55.4 KB

I don’t see any log-values (with debug-loggin on), only:
2026-09-15 17:00:28.706 DEBUG (MainThread) [custom_components.somtoday.coordinator] Finished fetching somtoday data in 0.504 seconds (success: True)

14

Hi @ErikWie, thanks! The success: True message doesn’t necessarily mean the homework requests succeeded.

Could you open Tools > States, find the Homework sync sensor and copy its attributes, especially reasons? Your screenshot shows its history, but the attributes should tell us which step is failing.

15

Here you go:

mode: waiting
created: 0
updated: 0
unchanged: 0
waiting: 1
errors: 0
source_updated: 0
homework_found: 0
reasons: 
homework_source_unavailable: 1

icon: mdi:clipboard-check-outline
friendly_name: Homework sync
1 Like
16

Hi @ErikWie,

Beta 0.9.0-beta.3 adds detailed diagnostics and fixes handling of certain empty responses.

Could you update, restart HA, reproduce the issue, and share:

  • Parent or student account?
  • Are homework and tests visible in Somtoday’s app/website using that same account?
  • Which school/organization you are connecting to.
  • What to-do integration are you using?
  • The diagnostics file: Settings > Devices & services > Somtoday > ⋮ > Download diagnostics.

The file includes versions, results/errors per source, task-list capabilities and sync status, without names, tokens or homework contents. This should help distinguish empty results from failed requests.

Thanks for testing!

17

In beta 3 it works!

1 Like
18

That’s great news! Let me know your thoughts.
I think it needs some refactoring still.

Also a write back test with a child account isn’t yet done.

19

I like it very much.

I could think of two more additions:

  • add the homework to the schedule-item description (if you can match it)
  • if you can match, put an empty or checked (textbased) box in the schedule-item title
20

A new beta is available: v0.9.0-beta.5.

A new beta is available: v0.9.0-beta.6.

It adds an option in the config to include homework in lesson descriptions, both in the HA timetable and exported lesson events. Homework is only added when the subject and lesson start time match unambiguously.

I’m not sure what to do with daily and weekly homework.

Feedback is welcome!

Edit:
There was a bug when a day ended with a break, it was added to the schoolday event. Also the homework formatting has been improved. This is now solved beta 6