Skip to content

Home

Jump to bottom
acdcnow edited this page Sep 21, 2026 · 6 revisions

TimeTree Calendar for Home Assistant — Documentation

Welcome to the documentation hub for the TimeTree Calendar custom integration (domain timetree). It imports TimeTree calendars through the official TimeTree web API into Home Assistant — read and write — and can mirror them into a second calendar (for example Google Calendar) with conflict handling that asks before it overwrites anything.

This wiki documents two lines of the integration at the same time. Pick the right document in the table below, or jump straight to Current (2.0.x) or Archived (1.1.3).

🚦 Which documentation do I need?

Your situation Read
You run the pre-release 2.0.0-beta.2 from branch ha2026_09_dev (Home Assistant 2026.9+) Current documentation
You run v1.1.3 from main, or any older release Archived documentation
You want to understand why something is built the way it is Architecture Design Document
You want to understand how it works module by module Software Design Document
You want to see the flows and diagrams Workflow Diagrams
You want to install, configure or troubleshoot the integration README

🟢 Current line — integration 2.0.x

Branch ha2026_09_dev · version 2.0.0-beta.2 (pre-release) · requires Home Assistant 2026.9+

Document Contents
📐 Architecture Design Document (ADD) Requirements, system context, component decomposition, 14 architectural decisions (AD-1…AD-14), cross-cutting concerns, deltas versus 1.1.3, quality attributes, risks, extension points.
🧩 Software Design Document (SDD) Module inventory, structural view, the five interface contracts, component-by-component design, sequence diagrams, data model, error handling matrix, localisation, build/verify/release, traceability.
🗺️ Workflow Diagrams The GitDiagram repository map (generated) plus the authored 2.0.x component map and the setup, polling, range query, write, export, conflict and re-baseline workflows.

What is new in 2.0.x

  • Multi calendar: every calendar of the account becomes its own calendar.* entity and device; calendars can be added or removed later in the options flow.
  • Read and write: calendar.create_event, calendar.update_event and calendar.delete_event are supported (WebSocket API, scripts and automations).
  • Complete import: chunked events/sync cursor, recurrence expansion (EXDATE/RDATE/COUNT/UNTIL), correct all-day semantics, negative timestamps, labels/colours, attendees, optional comments, memos.
  • Export loop: mirror events into any calendar entity (Google Calendar, …) with a selectable interval, window, direction (export_only/two_way) and dry run.
  • Conflict management: a persisted sync snapshot, a decision table, policies (manual, source_wins, target_wins, newest_wins) and manual resolutions (use_timetree, use_export_target, use_newest, skip, ignore_forever).
  • Operational polish: diagnostics with redaction, brand images inside the integration, English/German translations, Home Assistant 2026.9 API conformance.

Fixes that shaped 2.0.x

Issues #1 (views stalled), #2 (rrule did not contain FREQ), #3 (combine() argument 1 must be datetime.date, not None), #5 (write 422, all-day off-by-one), #6 (labels/attendees) and the analysis in PR #7 (recurrence expansion) are addressed on this line — see the archived page for the defect-by-defect comparison and SDD §11 for the traceability matrix.

🗄 Archived line — integration 1.1.3

Branch main · version 1.1.3 · Home Assistant 2025.12 era

Document Notes
🗄️ Design Documentation 1.1.3 (ACD + SDD) The former Developer & Technical Reference Guide, preserved verbatim, plus a list of the defects fixed in 2.0.x.
🗄️ Developer & Technical Reference Guide Old page name, kept as a pointer so existing links keep working.

Migrating from 1.1.3 to 2.0.x is a breaking change: 2.0.x needs Home Assistant 2026.9 or newer and installs curl_cffi. The manifest pins homeassistant: 2026.9.0, so HACS only offers the release to compatible systems. Existing config entries are migrated automatically (single calendar layout), entity ids change because each TimeTree calendar now gets its own device.

🧭 Capability matrix

Capability 1.1.3 2.0.x
Calendars per account 1 all (multi-select)
Create events ❌ broken (issue #3/#5) ✅
Update / delete events ❌ ✅
Recurring events ❌ broke the view (issue #2) ✅ expanded occurrences + rrule
All-day events ❌ off by one (issue #5) ✅ inclusive ⇄ exclusive conversion
Labels / attendees ❌ (issue #6) ✅ (labels, colours, names)
Event comments ❌ ✅ (opt-in)
Export to another calendar ❌ ✅ loop with selectable interval
Conflict handling ❌ ✅ sensor + services + policies
Diagnostics ❌ ✅ redacted dump
Brand images ❌ ✅ shipped in brand/
Minimum Home Assistant 2025.12 2026.9

🔗 Project links
Repository https://github.com/acdcnow/Timetree-Import-for-Home-Assistant
Release branch ha2026_09_dev
Latest pre-release 2.0.0-beta.2
Changelog CHANGELOG.md
Issues https://github.com/acdcnow/Timetree-Import-for-Home-Assistant/issues
Pull requests https://github.com/acdcnow/Timetree-Import-for-Home-Assistant/pulls
README (install, options, services, troubleshooting) README.md

Reference material

This is a community project and is not affiliated with TimeTree.

TimeTree Calendar

🏠 Documentation home

🟢 Current — 2.0.x (branch ha2026_09_dev, HA 2026.9+)

🗄️ Archived — 1.1.3 (branch main)

🔗 Links

Clone this wiki locally