Skip to content

About

alternative Zeiten for home assistant.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

451 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Alternative Time Systems for Home Assistant

hassfest HACS validation Python checks hacs_badge GitHub Release GitHub Activity License Version

A comprehensive Home Assistant integration providing 45 alternative time systems from science, science fiction, fantasy, history, religion, and various cultures.

๐ŸŽฏ Overview

  • ๐ŸŒ™ Lunar Time (Relativistic Moon time based on LTE440 ephemeris)
  • โญ Stellar Distances (Real-time distances to stars & pulsars with accuracy data)
  • ๐Ÿช Solar System Tracker (Real-time planetary positions with visual maps)
  • ๐Ÿš€ Science Fiction (Star Trek, Star Wars, EVE Online, Warhammer 40K)
  • ๐Ÿง™ Fantasy Worlds (Tolkien, Elder Scrolls, Discworld, Warcraft)
  • ๐Ÿ›๏ธ Historical Calendars (Maya, Egyptian, Attic, Roman)
  • ๐Ÿ”ด Mars Colonization (Darian Calendar, Mars Time Zones)
  • ๐ŸŒ Cultural Calendars (Islamic, Thai, Taiwanese, Chinese, Japanese, Hindu, Ethiopian)
  • ๐Ÿ’ป Technical Formats (Unix, Hexadecimal, Julian Date, Swatch, TAI, UT1)
  • ๐ŸŽ–๏ธ Military Systems (NATO DTG in multiple formats)

โœจ New in Version 2.5.2.180

๐ŸŒ™ Lunar Coordinate Time (TCL)

Actual lunar clock time based on the LTE440 Lunar Time Ephemeris.

Parameter Value
Display 14:30:45 TCL (actual Moon time)
Daily Drift ~56.7 ยตs/day (Moon clock runs faster)
Accumulated ~1-2 ms since J2000.0 epoch
Accuracy <0.15 ns until 2050
Scientific Basis JPL DE440, IAU 2024 Resolution II

Features:

  • Shows actual TCL time (what a clock on the Moon would show)
  • Multiple display formats: Time, DateTime, Time+Drift, Drift only
  • Relativistic calculation (general + special relativity)
  • 13 periodic variation terms from orbital mechanics
  • Based on peer-reviewed research (Lu, Yang & Xie, A&A 704, A76, 2025)

Reference: DOI: 10.1051/0004-6361/202557345


๐ŸŒŸ Available Time Systems

๐ŸŒ™ Lunar Time

Lunar Coordinate Time (TCL) ๐Ÿ†•

  • ID: lunar_tcl
  • Format: 14:30:45 TCL or 2026-01-24 14:30:45 TCL
  • Features:
    • Actual lunar clock time (UTC + relativistic drift)
    • Relativistic time dilation between Earth and Moon
    • Based on LTE440 ephemeris (JPL DE440)
    • Daily drift ~56.7 ยตs (Moon clock runs faster)
    • Accumulated difference since epoch (currently ~1-2 ms)
    • IAU 2024 Resolution II compliant
    • Scientific reference: Lu, Yang & Xie (2025), A&A 704, A76
  • Display options: TCL Time, TCL DateTime, TCL+Drift, Daily Drift (ยตs), Accumulated (ms)
  • Update: Every 60 seconds

ESA Lunar Time (LTC)

  • ID: lunar_time
  • Format: LTC 14:30:45 | ๐ŸŒ“ Day 8
  • Features:
    • ESA's proposed Lunar Time Coordinated system
    • Lunar timezones (Apollo, Chang'e, Luna landing sites)
    • Moon phase display
    • Time dilation indicator (56 ยตs/day)
  • Update: Every 60 seconds

โญ Stellar Distances

Stellar Distance Calculator

Real-time distances to notable stars and pulsars with measurement accuracy.

7 Stars:

Star Distance Accuracy Note
Proxima Centauri 4.24 ly ยฑ0.006% Nearest star
Barnard's Star 5.95 ly ยฑ0.007% Fastest proper motion (10.3"/yr)
Scholz's Star 22.2 ly ยฑ0.17% Passed Oort Cloud 70,000 years ago
Ross 248 10.3 ly ยฑ0.27% Will be nearest in 36,000 years
Gliese 710 62.5 ly ยฑ0.05% Collision course - 10,600 AU in 1.35 Myr
Polaris 433 ly ยฑ1.5% North Star
Betelgeuse 723 ly ยฑ18% Supernova candidate

6 Nearest Pulsars:

Pulsar Distance Accuracy Note
PSR J0437-4715 511 ly ยฑ0.06% Nearest millisecond pulsar (173 rot/sec)
PSR J0108-1431 424 ly ยฑ13% Oldest nearby (166 Myr)
Vela Pulsar 932 ly ยฑ6% Brightest radio pulsar
Geminga 815 ly ยฑ32% First gamma-ray pulsar
PSR B0656+14 940 ly ยฑ10% "Three Musketeers" pulsar
PSR B0950+08 906 ly ยฑ8% Old pulsar in Leo (17.5 Myr)

Features:

  • Real-time distance calculation using parallax + radial velocity
  • Measurement uncertainty (ยฑ%) for each object
  • Distance range (min-max) based on parallax error
  • Accuracy ratings: excellent / very good / good / moderate / uncertain
  • Data sources: Gaia DR3, VLBI parallax, Pulsar Timing

๐Ÿช Solar System

Solar System Tracker

  • Features: Real-time planetary positions, visual orbit maps, visibility and retrograde motion as seen from Earth

  • Update: Every 5 minutes

  • Attributes: positions per planet plus the paths of the map files. The map itself is not copied into the attributes; entity_picture points at the SVG file.

  • Map image: The plugin writes the rendered orbit map to config/www/alternative_time/ as both solar_system_map.svg and solar_system_map.png. To embed it in a dashboard, use the /local/ URL with a cache-busting query parameter so updates are picked up by the browser:

    type: picture
    image: /local/alternative_time/solar_system_map.svg?v={{ now().timestamp() | int }}

    The ?v=... suffix is required โ€” without it Home Assistant's aggressive /local/ caching will keep showing the old image. Use solar_system_map.png instead if you prefer the raster version. After the www/ folder is created for the first time, Home Assistant must be restarted once before /local/ URLs become available.

๐Ÿš€ Science Fiction

Stardate (Star Trek TNG)

  • Format: [41]XXX.X (e.g., [41]986.0)
  • Features: TNG-style calculation, configurable year offset
  • Update: Every 10 seconds

Star Wars Galactic Calendar

  • Format: 35:3:21 GrS | Taungsday | Expansion Week
  • Features: Galactic Standard Calendar, 10 months, 7 weeks, 5 days per week, 368-day year
  • Update: Hourly

EVE Online Time

  • Format: YC 127.03.15 14:30:45
  • Features: New Eden Standard Time, YC dating
  • Update: Every second

Warhammer 40K Imperial Dating

  • Format: 0.523.025.M42
  • Features: Check number, year fraction, millennium designation
  • Update: Every 5 minutes

๐Ÿง™ Fantasy Calendars

Middle-earth Collection

  • Shire Calendar: Hobbit time with 7 meals
  • Calendar of Imladris: Elvish 6-season year
  • Calendar of Gondor: Nรบmenรณrean system

Elder Scrolls (Tamriel)

  • Format: 4E 201, 17 Last Seed (Fredas)
  • Features: 8-day weeks, Divine blessings, Daedric influence
  • Update: Hourly

Discworld Calendar

  • Format: Century of the Anchovy, UC 25, 32 Offle
  • Features: Impossible dates (32nd of months), Guild influences, L-Space anomalies
  • Update: Hourly

World of Warcraft Calendar

  • Format: Year 35, Day of the Wisp, 4th of Deepwood
  • Features: Azeroth dates, seasonal events, moon phases
  • Update: Hourly

๐Ÿ›๏ธ Historical Calendars

Ancient Egyptian

  • Format: Dynasty 1 Year 25, ๐“Š– 15 Thoth
  • Features: Hieroglyphic numbers, 3 seasons, Nile status
  • Update: Hourly

Maya Long Count

  • Format: 13.0.12.1.15 | 8 Ahau | 3 Pop
  • Features: Long Count, Tzolk'in, Haab calendars
  • Update: Hourly

Roman Calendar

  • Format: a.d. XVII Kal. Ian. MMDCCLXXVIII A.U.C.
  • Features: Kalends, Nones, Ides system, Roman numerals, A.U.C. dating
  • Update: Hourly

Attic Calendar

  • Format: 5 histamenou Hekatombaion | Ol.700.2
  • Features: Archon years, Olympiad counting
  • Update: Hourly

โ˜ช๏ธ Religious Calendars

Islamic (Hijri) Calendar

  • Format: 15 Ramadan 1447 AH
  • Features: Tabular calculation, Arabic month names, Islamic holidays
  • Update: Hourly

Chinese Calendar

  • Format: ็”ฒ่พฐๅนด ๅๆœˆ ๅไบ” | Wood Dragon
  • Features: Lunar calendar, Zodiac animals, Heavenly stems & Earthly branches
  • Update: Hourly

๐ŸŒ Cultural Calendars

Suriyakati (Thai Buddhist)

  • Format: เน’เน• เธ˜เธฑเธ™เธงเธฒเธ„เธก เน’เน•เน–เน˜
  • Features: Buddhist Era (BE = CE + 543), Thai numerals
  • Update: Hourly

Minguo (Taiwan/ROC)

  • Format: ๆฐ‘ๅœ‹114ๅนด ๅไบŒๆœˆ ไบŒๅไบ”ๆ—ฅ
  • Features: Republic Era (Year 1 = 1912 CE)
  • Update: Hourly

Japanese Era Calendar

  • Format: ไปคๅ’Œ7ๅนด1ๆœˆ24ๆ—ฅ
  • Features: Imperial era names, Japanese holidays, Rokuyou
  • Update: Hourly

Hindu Panchang

  • Features: Tithi, Nakshatra, Yoga, Karana, festivals
  • Update: Hourly

Ge'ez (Ethiopian) Calendar

  • Format: 15 แˆ˜แˆตแŠจแˆจแˆ 2017 or แฒแญ แˆ˜แˆตแŠจแˆจแˆ แณแปแฒแฏ
  • Features: 13-month calendar, native Ge'ez script and numerals
  • Update: Hourly

๐Ÿ”ด Mars Time Systems

Darian Calendar

  • Format: 13 Rishabha 214 (Sol Veneris) (the day Curiosity landed)
  • Features: 24 months, 668 or 669 sols per year, years counted from 1609
  • Update: Hourly

Mars Time with Zones

  • Format: 14:25:30 Olympus Mons | Sol 234/MY36
  • Features: 24 Mars timezones, mission sol tracking
  • Update: Every 30 seconds

๐Ÿ’ป Technical Formats

Unix Timestamp

  • Format: 1735689600
  • Update: Every second

Swatch Internet Time

  • Format: @500.00
  • Features: 1000 .beats per day
  • Update: Every second

Hexadecimal Time

  • Format: A.F3.C8
  • Update: Every 5 seconds

Julian Date

  • Format: 2460678.50000
  • Update: Every 30 seconds

TAI (International Atomic Time)

  • Format: 2026-01-24T00:36:52 TAI
  • Features: Continuous atomic timescale, leap second history
  • Update: Every second

UT1 (Universal Time 1)

  • Format: 2026-01-24T00:43:31.767 UT1
  • Features: Earth rotation time, IERS API integration
  • Update: Configurable (5 min to 24 hours)

๐ŸŽ–๏ธ Military Systems

NATO Date-Time Group

  • German Format: 241530AJAN26
  • US/UK Format: 241530Z JAN 26
  • Features: Multiple timezone designators, configurable formats

๐Ÿ“ฆ Installation

Via HACS (Recommended)

  1. Open HACS in your Home Assistant
  2. Click the three dots โ†’ "Custom repositories"
  3. Add URL: https://github.com/Lexorius/alternative_time
  4. Select "Integration" as category
  5. Click "Add"
  6. Search for "Alternative Time Systems" and install
  7. Restart Home Assistant

Manual Installation

  1. Download the alternative_time folder from the repository
  2. Copy to /config/custom_components/
  3. Restart Home Assistant

โš™๏ธ Configuration

Via User Interface (Config Flow 2.5)

  1. Go to Settings โ†’ Devices & Services
  2. Click Add Integration
  3. Search for Alternative Time Systems
  4. Follow the configuration wizard:
    • Step 1: Name your instance
    • Step 2: Select categories (Technical, Historical, Cultural, Space, etc.)
    • Step 3: Choose calendars from each category
    • Step 4: Configure calendar-specific options

Excluding from Recorder / History

These sensors are clocks: their history is worthless and, for the second-resolution ones, expensive (a states row per change). Two things keep them out of your database:

1. Attributes are never recorded (automatic since v2.6.2). Every sensor declares _unrecorded_attributes = MATCH_ALL, so the recorder stores only the state string. Attributes stay live for dashboards and templates โ€” they just don't accumulate in state_attributes (the Solar System map alone was ~23 KB per row).

2. Exclude the states with one glob (recommended). All sensors use the stable entity_id sensor.alternative_time_<calendar_id> (e.g. sensor.alternative_time_solar_system), independent of the instance name you chose, so a single line covers everything:

recorder:
  exclude:
    entity_globs:
      - sensor.alternative_time_*

To also drop existing history for these sensors after enabling the exclusion, call the service recorder.purge_entities once:

service: recorder.purge_entities
data:
  entity_globs:
    - sensor.alternative_time_*

Entities created by older versions kept the entity_id they were originally given (e.g. sensor.beats_swatch_internet_time) and are not matched by the glob. Open the integration entry โ†’ Configure โ†’ Migrate entity IDs to sensor.alternative_time_* โ€” it previews every rename, applies them in the entity registry and posts a notification with the old โ†’ new list. Dashboards and automations that reference the old IDs must be updated by you (HA does not rewrite them). Opt-in and one-shot; nothing changes unless you confirm. The same step also fixes ids like sensor.<area>_alternative_time_โ€ฆ that newer Home Assistant versions created before this integration set the id itself.

Home Assistant offers no way for an integration to exclude an entity's state from the recorder โ€” that is user configuration only. Ten calendars are genuine second-resolution clocks (unix, tai, eve, decimal, hexadecimal, sidereal, julian_date, timezone, ut1, mass_effect) and will write a row per change until you set the glob above.


๐ŸŽจ Architecture

Standardized Calendar Format

Each calendar follows the unified CALENDAR_INFO structure:

  • Metadata: ID, version, icon, category, accuracy
  • Multi-language: Names and descriptions in 12 languages
  • Calendar Data: Months, weeks, special dates, events
  • Configuration Options: Customizable per calendar
  • Update Intervals: Optimized for each calendar type

Tests

tests/ runs without a Home Assistant installation โ€” homeassistant.* is stubbed in tests/conftest.py. The suite runs every calendar on every day of a leap year and compares the calendar maths with published values (Julian Dates, Mars landing sols, Darian dates of Mars missions, moon phases, Chinese New Year, religious holidays). It also covers discovery, setup and entity ids, scheduling and error paths, recorder churn and the translations, in a few seconds:

pip install pytest aiohttp
python -m pytest tests -q

tests_ha/ is the second suite: it runs the integration inside a real Home Assistant core (via pytest-homeassistant-custom-component, Linux or WSL). It sets up every calendar and checks the entity ids the registry hands out, clicks through the whole setup wizard in five languages, and uses the options dialog and the entity id migration:

pip install pytest-homeassistant-custom-component LunarCalendar
python -m pytest tests_ha -q

Run the two directories in separate pytest calls โ€” tests/ replaces homeassistant with stubs.

CI runs both suites in python-checks.yml; release.yml only builds a release when hassfest, HACS validation and the Python checks are green on the tagged commit.

Shared maths lives in astro.py (Julian Dates, real new and full moons, Sun and Moon longitude, the lunisolar calendar, Mars Sol Date and season); calendars import it instead of carrying their own copies.

Supported Languages

๐Ÿ‡ฌ๐Ÿ‡ง English (en) | ๐Ÿ‡ฉ๐Ÿ‡ช Deutsch (de) | ๐Ÿ‡ช๐Ÿ‡ธ Espaรฑol (es) | ๐Ÿ‡ซ๐Ÿ‡ท Franรงais (fr) | ๐Ÿ‡ฎ๐Ÿ‡น Italiano (it) | ๐Ÿ‡ณ๐Ÿ‡ฑ Nederlands (nl) | ๐Ÿ‡ต๐Ÿ‡ฑ Polski (pl) | ๐Ÿ‡ต๐Ÿ‡น Portuguรชs (pt) | ๐Ÿ‡ท๐Ÿ‡บ ะ ัƒััะบะธะน (ru) | ๐Ÿ‡ฏ๐Ÿ‡ต ๆ—ฅๆœฌ่ชž (ja) | ๐Ÿ‡จ๐Ÿ‡ณ ไธญๆ–‡ (zh) | ๐Ÿ‡ฐ๐Ÿ‡ท ํ•œ๊ตญ์–ด (ko)

Categories

  • space: Lunar TCL, ESA Lunar Time, Solar System, Stellar Distances, Mars calendars
  • technical: Unix, Swatch, Hexadecimal, Decimal, TAI, UT1
  • historical: Egyptian, Maya, Roman, Attic
  • cultural: Thai, Taiwan, Chinese, Japanese, Ethiopian
  • religious: Islamic, Hindu Panchang, Ge'ez (Ethiopian)
  • fantasy: Middle-earth, Tamriel, Discworld
  • scifi: Star Trek, Star Wars, EVE, Warhammer

๐Ÿš€ Performance Optimization

Category Update Interval Calendars
Real-time 1 second Unix, Swatch, TAI
Near real-time 5-10 seconds Hexadecimal, Stardate
Time-based 30-60 seconds Mars Time, Julian Date, Lunar Time
Date-based 1 hour Calendar systems, Stellar Distances
Event-based 5 minutes Warhammer 40K

๐Ÿ“ˆ Version History

v2.7.0 (Current)

  • ๐Ÿ› Wrong values fixed in a dozen calendars: Swatch (one hour off all summer), Julian Date (half a day low), Mars Sol Date and season, Darian (year 85 instead of 221), Islamic weekday, Thai zodiac, lunar illumination, Solar System visibility and retrograde, and real moon maths for Hindu Panchang, the Japanese lunar calendar, Thai holy days and the sexagenary year.
  • ๐Ÿ› Seven calendars ignored all their options (stardate, discworld, eve, islamic, rivendell, shire, tamriel); the Warcraft calendar crashed on 52 days a year; Migrate entity IDs crashed whenever there was something to migrate.
  • ๐Ÿ•’ 25 calendars used the operating-system clock (UTC in a container); they now use Home Assistant's time zone.
  • ๐Ÿ†” New sensors get sensor.alternative_time_<calendar> set explicitly, so newer Home Assistant versions no longer put device and area names in front. Existing entities keep their id.
  • ๐Ÿ—„๏ธ Solar System: the map is no longer stored three times in the attributes. Removed attributes: solar_system_map_svg, solar_system_map_png, observer_location โ€” use local_svg_path, local_png_path or entity_picture.
  • ๐Ÿงน One calendar discovery instead of three, shared astronomy in astro.py, dead code and stale files removed; requirements are down to LunarCalendar (pytz, tzlocal and Pillow dropped). translations/zh.json is now zh-Hans.json.
  • ๐Ÿงช Tests: 80 โ†’ 175 with published reference values, plus tests_ha/, which runs the integration inside a real Home Assistant core in CI.
  • ๐ŸŽจ Brand assets ship with the integration (brand/, contributed by frenck).

v2.6.3

  • ๐Ÿงช Test suite (tests/, 80 tests, no HA install needed) wired into CI; releases are now gated on hassfest, HACS validation and the Python checks passing on the tagged commit.
  • ๐Ÿ—„๏ธ Two more recorder-row sources found by the new tests and removed: stellar_distances.last_calculated (a microsecond timestamp duplicating HA's last_updated) and cosmic_speedometer.fun_fact (was random.choice per update; now rotates hourly).
  • ๐Ÿงน .gitignore added.

v2.6.2.1

  • ๐Ÿ› hassfest: the migration dialog text contained <calendar>, which the translation validator rejects as HTML (and the frontend may swallow). Now [calendar] in all 13 string files. No code changes.

v2.6.2

  • ๐Ÿ—„๏ธ Attributes are no longer recorded (_unrecorded_attributes = MATCH_ALL on the base class). Solar System alone wrote ~23 KB of SVG per state row; now only the state string is stored. Attributes stay live.
  • ๐Ÿ—„๏ธ Attribute churn fixed in dtg, german_rescue_dtg (60ร— fewer recorder rows), swatch (86ร— fewer) and stardate (~6ร— fewer): attributes now change only when the displayed value changes.
  • โœจ Entity-ID migration under Configure โ†’ Migrate entity IDs: renames pre-2.6.0.7 entities to sensor.alternative_time_<calendar> so the single recorder glob covers them; previews, then posts an old โ†’ new notification.
  • ๐Ÿ› Fix: five calendars raised AttributeError on every update (chinese_lunar, mars, mass_effect, warcraft, warhammer40k_imperial called a never-defined _get_plugin_options). Invisible until 2.6.1 made failures visible.
  • ๐Ÿงน translations/ps.json removed (Polish text under the Pashto code); dead recorder-exclusion stub removed.

v2.6.1

  • ๐Ÿ› Fix: every entity was updated twice โ€” should_poll returned True, so HA polled every sensor every 30 s on top of the plugin's own timer. Now False; the timer is the only scheduler, and a tick is skipped while the previous one is still running.
  • โœจ Options changes apply immediately โ€” an update_listener now reloads the entry after saving under Configure (previously required a restart).
  • ๐Ÿ‘๏ธ Failed updates are visible โ€” first failure of a streak logs a WARNING, entity becomes unavailable after 3 consecutive failures and recovers automatically.
  • ๐ŸŒ ut1: shared aiohttp session + exponential backoff (60 s โ†’ 1 h) instead of retrying the IERS API every second while it is down.
  • ๐Ÿงน _CONFIG_ENTRIES cleaned on unload; __init__.py no longer swallows platform setup errors; dead async_reload_entry removed.

v2.6.0.7

  • ๐Ÿ› Fix: three calendars never created a sensor โ€” julian_date, minguo_taiwan, suriyakati_thai were selectable but silently skipped at setup (id โ‰  file name). Discovery now records the module name per id.
  • ๐Ÿ› Fix: sensor.alternative_time_* entity_id prefix actually works now. The 2.6.0.4 change used a non-existent _attr_; replaced by a proper suggested_object_id property override. Still applies to newly registered entities only.
  • ๐Ÿ› Fix: options of dtg, german_rescue_dtg, julian_date now appear in the setup wizard (wrong CALENDAR_INFO key). Two malformed selects in those plugins repaired.
  • ๐Ÿงน test_debug.py no longer ships or shows up as a calendar.
  • ๐Ÿ“ฆ tzlocal declared as requirement; hacs.json now requires HA โ‰ฅ 2024.12.

v2.6.0.6

  • ๐Ÿ› Fix: formatjs MISSING_VALUE in the options dialog ({title} placeholder is now supplied from the instance name).
  • โœจ Real options flow: clicking Configure on the integration entry now lets you pick a configured calendar and edit its options (previously only showed a placeholder toggle).
  • ๐Ÿ› Fix: plugin options had no effect: sensors read options from data["plugin_options"] while the config flow stored them under data["calendar_options"]. Sensors now read the correct key (with legacy fallback). Plugin options set in the setup wizard now actually apply.

v2.6.0.5

  • ๐Ÿ› Fix: 500 Internal Server Error when opening the integration's options under Home Assistant โ‰ฅ 2024.12 (OptionsFlow.config_entry became a read-only property in newer HA; the constructor no longer tries to set it).

v2.6.0.4

  • ๐Ÿ‡ฑ๐Ÿ‡ฐ New plugin: Sri Lankan Buddhist Calendar (sri_lanka_buddhist.py) โ€” Buddhist Era year, the twelve Sinhala Poya (full-moon) days with religious significance, Sinhala/Tamil New Year countdown, and Sinhala weekday names. Poya dates use Meeus astronomy + the Sri Lankan moonrise rule and reproduce all 11 officially proclaimed Poya days 2023โ€“2026 exactly.
  • ๐ŸŽฏ Stable entity_id prefix for Recorder filtering: every plugin sensor now gets sensor.alternative_time_<calendar_id> as suggested entity_id, regardless of the instance name picked in the config flow. A single glob sensor.alternative_time_* in recorder.exclude now matches all of them. (Existing entities keep their previous IDs.)
  • ๐Ÿ“š README: new section Excluding from Recorder / History under Configuration.

v2.6.0.2

  • ๐Ÿšฆ CI workflows split: the previous validate.yml was split into hassfest.yml, hacs.yml, and python-checks.yml so each check has its own status badge (visible at the top of this README)
  • ๐Ÿท๏ธ Status badges: hassfest, HACS validation, and Python checks badges added to the README header

v2.6.0.1

  • ๐Ÿงน Code cleanup: all calendar plugin files are now ruff-clean (E, F, W, I โ€” --ignore E501)
  • ๐Ÿ› Bare excepts in dtg.py, german_rescue_dtg.py, mars.py, hindu_panchang.py, japanese_era.py, japanese_lunar.py, stellar_distances.py replaced with except Exception:
  • ๐Ÿ—‘๏ธ Dead variables removed in geez.py, japanese_lunar.py, lunar_tcl.py, maya.py, solar_system.py, star_wars.py
  • ๐Ÿ”‘ Duplicate dict key "holidays" in star_wars.py resolved
  • ๐Ÿ“ฆ Unused import Lunar removed from chinese_lunar.py
  • โœ‚๏ธ One-line if/else statements in stellar_distances.py split into multi-line form
  • ๐Ÿ”ง scripts/bump-version.sh: now supports 4-component versions (x.y.z.b) and a new build subcommand that increments only the 4th component

v2.5.2.180

  • ๐ŸŒ™ Lunar Coordinate Time (TCL): New plugin lunar_tcl.py showing actual lunar clock time
  • ๐Ÿ• TCL Time Display: Shows what time it would be on the Moon (14:30:45 TCL)
  • โฑ๏ธ LTE440 Ephemeris: Based on JPL DE440, scientific accuracy <0.15 ns until 2050
  • ๐Ÿ“Š Daily drift: ~56.7 ยตs/day (Moon clock faster than Earth)
  • ๐Ÿ“ˆ 13 periodic terms: Annual (~1.65 ms), monthly (~126 ยตs), and 11 minor terms
  • ๐Ÿ”ฌ Scientific basis: Lu, Yang & Xie (2025), Astronomy & Astrophysics 704, A76
  • ๐Ÿ“ IAU compliant: IAU 2024 Resolution II (LCRS/TCL standard)
  • ๐ŸŒ™ ESA Lunar Time: Updated config options with emoji labels for landing sites
  • ๐Ÿ› ๏ธ Config Flow Fix: Fixed dropdown labels for select options

v2.5.2.170

  • โญ Stellar Distances Calculator: Real-time distances to 7 stars & 6 pulsars
  • ๐Ÿ“Š Measurement Accuracy: Uncertainty percentages for all objects
  • ๐Ÿ“ Distance Ranges: Min-max based on parallax errors
  • ๐ŸŽฏ Accuracy Ratings: excellent/very good/good/moderate/uncertain
  • ๐Ÿ“ก Data Sources: Gaia DR3, VLBI, Pulsar Timing

v2.5.2.165

  • ๐Ÿ• TAI: International Atomic Time
  • ๐ŸŒ UT1: Universal Time 1 with IERS API
  • โœ๏ธ Ge'ez Calendar: Ethiopian calendar with native script
  • ๐Ÿช Solar System: Improved positioning

v2.5.0

  • โšก Complete Architecture Rewrite
  • ๐ŸŽจ Standardized Calendar Format
  • ๐ŸŒ Multi-language Support (12 languages)
  • ๐Ÿ“ Category-based Organization
  • โš™๏ธ Enhanced Config Flow with plugin options

Previous Versions

  • v1.6.0: Tamriel, Egyptian, Discworld calendars
  • v1.5.0: EVE Online, Shire, Imladris calendars
  • v1.4.0: Mars time systems
  • v1.3.0: Asian calendars, Attic calendar
  • v1.2.0: NATO time formats
  • v1.1.0: Maya calendar, async improvements
  • v1.0.0: Initial release

๐Ÿ› ๏ธ Development

Adding a New Calendar

  1. Create calendars/your_calendar.py
  2. Follow the standardized format (see existing calendars)
  3. Include CALENDAR_INFO dictionary with all metadata
  4. Implement sensor class extending AlternativeTimeSensorBase
  5. Test thoroughly

Minimal Calendar Template

CALENDAR_INFO = {
    "id": "your_calendar",
    "version": "1.0.0",
    "icon": "mdi:calendar",
    "category": "technical",
    "update_interval": 3600,
    "name": {
        "en": "Your Calendar",
        "de": "Dein Kalender",
        # ... other languages
    },
    "description": {
        "en": "Calendar description",
        "de": "Kalenderbeschreibung",
        # ... other languages
    },
    "config_options": {
        "option_key": {
            "type": "boolean",
            "default": True,
            "label": {"en": "Option Label", "de": "Optionsbeschriftung"},
            "description": {"en": "Option description", "de": "Optionsbeschreibung"}
        }
    }
}

๐Ÿ” CI / Validation

Four GitHub workflows guard the repository โ€” three validation workflows that run on every push/PR (each with its own status badge at the top of this README), plus the release workflow.

.github/workflows/hassfest.yml โ€” push & pull-request to main/master

Job What it checks
Home Assistant hassfest Official HA integration validation (home-assistant/actions/hassfest)

.github/workflows/hacs.yml โ€” push & pull-request to main/master

Job What it checks
HACS validation HACS compliance (hacs/action, category integration); brands, topics, description are currently in the ignore list and can be removed once they're set on the GitHub repo

.github/workflows/python-checks.yml โ€” push & pull-request to main/master

Two jobs. Python checks (Python 3.12, no Home Assistant installed):

Step Purpose
Compile-check python -m compileall -q custom_components/ โ€” fails on any syntax error
Manifest-Check bash scripts/check-manifest.sh โ€” required keys + hassfest-compatible key order
Ruff ruff check custom_components/ tests/ tests_ha/ --select E,F,W,I --ignore E501 โ€” E501 (line-too-long) is intentionally ignored because of multilingual description strings in 12 languages
Tests python -m pytest tests โ€” the stub-based suite
JSON lint json.loads() over every *.json file outside .git/
YAML lint yaml.safe_load() over every *.yml / *.yaml file
Version-Konsistenz If CHANGELOG.md exists, manifest.json's version must appear as a ## [version] heading; missing CHANGELOG.md only emits a warning, a missing version entry is a hard error

Tests gegen Home Assistant (Python 3.13): installs pytest-homeassistant-custom-component and runs python -m pytest tests_ha โ€” the integration inside a real Home Assistant core.

.github/workflows/release.yml โ€” push of a v* tag (or manual workflow_dispatch)

Step Purpose
Tag und Version ermitteln Derives version from the tag (v2.6.0.1 โ†’ 2.6.0.1)
manifest.json muss zum Tag passen Fails if manifest.json version doesn't match the tag โ€” the bump must be committed before tagging
ZIP-Asset bauen Packs the contents of custom_components/alternative_time/ into alternative_time.zip (excluding __pycache__ and *.pyc)
Release-Notes aus CHANGELOG ziehen Extracts the ## [version] section from CHANGELOG.md if present; otherwise falls back to Release <version>
GitHub-Release erstellen Creates the GitHub release with the ZIP attached; tags containing - (e.g. v2.6.0.1-rc1) are marked as prerelease

๐Ÿ› Troubleshooting

Calendar Not Appearing

  • Check Home Assistant logs for errors
  • Verify the calendar file is in the correct directory
  • Ensure CALENDAR_INFO['id'] matches the filename

Options Not Saving

  • Check that your calendar has config_options defined
  • Verify the option types are supported (text, number, boolean, select)
  • Review logs for configuration errors

Wrong Language Displayed

  • Check Home Assistant language settings
  • Verify translations exist for your language
  • Fallback to English if translation missing

๐Ÿ“„ License

MIT License - See LICENSE file for details.


๐Ÿ“ฎ Support

  • Bug Reports: GitHub Issues
  • Feature Requests: Open a GitHub issue with [Enhancement] tag

๐Ÿ”— Links

About

alternative Zeiten for home assistant.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages