Time, location and units

Global functions available to smart-app code. Call them by bare name; there is no object to import.

getSunTimesCopy Anchor Link

Today's sunrise / sunset for the hub's location, as ISO strings. available is false when the hub has no location fix (no monitoring address) — treat sun-anchored logic as unavailable in that case rather than trusting (0, 0) sun times. Unlike scheduleAtSunrise/Sunset (which fire a handler at the event), this queries the times so a smart app can evaluate sun-anchored time windows at decision time. Pair with formatDateParts(new Date(iso), getHomeTimeZone()) to convert an event to local minutes-since-midnight.

SignatureCopy Anchor Link

function getSunTimes(): { available: boolean; sunriseIso?: string; sunsetIso?: string; }

ParametersCopy Anchor Link

None.

ReturnsCopy Anchor Link

{ available: boolean; sunriseIso?: string; sunsetIso?: string } — Today’s sunrise and sunset as ISO instants; available: false when the hub has no location fix.

ExamplesCopy Anchor Link

const sun = getSunTimes();
if (sun.available) {
  const { hour, minute } = formatDateParts(new Date(sun.sunsetIso), getHomeTimeZone());
  console.log(`Sunset at ${hour}:${minute} local`);
}

See alsoCopy Anchor Link

formatDateParts · getHomeTimeZone

getHomeTimeZoneCopy Anchor Link

The home's IANA timezone (e.g. 'America/New_York'), read from the hub's monitoring address — the SAME zone scheduled cron jobs fire in. The isolate's new Date() reflects the edge-runtime PROCESS timezone (often UTC), which is NOT the home's. Any time-of-day or day-of-week logic that must line up with schedule()/runDaily() fires has to evaluate "now" in this zone instead — combine with formatDateParts(new Date(), getHomeTimeZone()). Falls back to 'UTC' when the hub has no location fix yet.

SignatureCopy Anchor Link

function getHomeTimeZone(): string

ParametersCopy Anchor Link

None.

ReturnsCopy Anchor Link

string — IANA zone such as America/New_York; UTC until the hub has a location.

ExamplesCopy Anchor Link

const now = formatDateParts(new Date(), getHomeTimeZone());
if (now.hour >= '22' || now.hour < '06') { /* night */ }

See alsoCopy Anchor Link

formatDateParts · scheduling

getUnitPreferencesCopy Anchor Link

The location's presentation units (Hubitat model): unitSystem is 'imperial' or 'metric', and temperatureScale is the derived '°F' or '°C' token. Every temperature entity state/attribute you read is ALREADY in this system (the hub normalizes on the way out), and any setTemperature value you send is interpreted in it — so use this only to LABEL values or choose unit-aware defaults, never to convert.

SignatureCopy Anchor Link

function getUnitPreferences(): { unitSystem: 'imperial' | 'metric'; temperatureScale: '°C' | '°F'; }

ParametersCopy Anchor Link

None.

ReturnsCopy Anchor Link

{ unitSystem: 'imperial' \| 'metric'; temperatureScale: '°C' \| '°F' }

ExamplesCopy Anchor Link

const { temperatureScale } = getUnitPreferences();
sendPushNotification(`Set to ${target}${temperatureScale}`);

formatDatePartsCopy Anchor Link

Format an instant into wall-clock parts in the given IANA timezone. Backed by the host's Intl.DateTimeFormat (the isolate has no Intl). Fields are zero-padded strings; weekday is the en-US short name ('Sun'..'Sat'). hour is 24-hour with midnight normalized to '00'.

SignatureCopy Anchor Link

function formatDateParts(date: Date, timeZone: string): { year: string; month: string; day: string; hour: string; minute: string; second: string; weekday: string; }

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

{ year, month, day, hour, minute, second, weekday } — Zero-padded strings; weekday is Sun…Sat; hour is 24-hour with midnight as 00.

NotesCopy Anchor Link

• Backed by the host’s Intl.DateTimeFormat — the isolate itself has no Intl.

See alsoCopy Anchor Link

getHomeTimeZone