Subscriptions and events

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

subscribeCopy Anchor Link

Subscribe to entity state changes. The filter is validated strictly at subscribe() time (unknown keys throw, aborting installed()/updated()): {} matches any change (state OR attribute delta); from/to fire only on a real state transition; state is a legacy alias of to (never combine the two); attribute.value omitted = any change of that attribute. Mirrors smartAppSubscriptionFilterSchema in

SignatureCopy Anchor Link

function subscribe(target: unknown, filter: { from?: string; to?: string; state?: string; attribute?: { name: string; value?: unknown }; }, handler: unknown): void

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void — Throws when an argument is missing or the host rejects the filter, which aborts the installed() / updated() call that made it.

NotesCopy Anchor Link

• Subscriptions are persisted and restored across hub reboots; you do not re-subscribe on systemStart.
• Call unsubscribe() at the top of updated() before subscribing again, or a changed device picker leaves the old subscription dangling.
• A label is resolved against the entity's domain and device class when the subscription is matched; the filter is stored as you wrote it. { to: 'on' } and { to: 'Open' } on the same handler collapse to one subscription and fire once.

ExamplesCopy Anchor Link

subscribe($g.motionSensor, { state: 'on' }, onMotionDetected);
subscribe($g.motionSensor, { state: 'off' }, onMotionCleared);

subscribe($g.frontDoor, { to: 'Open' }, onDoorOpen);          // binary_sensor/door: 'Open' → on
subscribe($g.panel, { to: 'Armed Away' }, onArmedAway);         // intrusion panel
subscribe($g.garage, { from: 'Closed', to: 'Opening' }, onLeaving);

subscribe($g.light, { attribute: { name: 'brightnessPercent' } }, onBrightness);

function onBrightness(evt) {
  if (evt.newState.context?.actorType !== 'physical') return; // ignore app-driven changes
  console.log('Dimmed by hand to', evt.newState.attributes?.brightnessPercent);
}

See alsoCopy Anchor Link

unsubscribe · EntityChangeEvent · subscription filter · subscriptions and events

unsubscribeCopy Anchor Link

Remove entity subscriptions: everything, everything for one handler, or those on a given target.

SignatureCopy Anchor Link

function unsubscribe(target: unknown, filter?: unknown, handler?: unknown): void

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

ExamplesCopy Anchor Link

$g.updated = function () {
  unsubscribe(undefined); // drop every subscription
  unschedule(undefined);  // and every schedule / timer
  initialize();
};

See alsoCopy Anchor Link

subscribe

matchesStateCopy Anchor Link

Does value name state for this entity? value is the raw token ('on') or the friendly label the app shows ('Open', 'Armed Away'), case- and separator-insensitive. The handler-body twin of entity.is() — pass the event's snapshot, e.g. matchesState(evt.entityId, evt.newState.state, 'open'). Throws on an unknown entity.

SignatureCopy Anchor Link

function matchesState(entityId: string, state: string | null | undefined, value: string): boolean

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

boolean — true when value names state. Throws when the entity is unknown.

NotesCopy Anchor Link

• The handler-body twin of entity.is(): use it on the event snapshot you were handed, because the live state may already have moved on.
• Raw tokens always match themselves; labels are only an input alias. Numeric domains (sensor, input_number, counter) never resolve a label.

ExamplesCopy Anchor Link

function onDoor(evt) {
  if (matchesState(evt.entityId, evt.newState.state, 'Open')) {
    sendPushNotification('Front door opened');
  }
}

See alsoCopy Anchor Link

is · subscribe · subscriptions and events

subscribeToLocationEventCopy Anchor Link

Subscribe to a named location event (e.g. systemStart, fired once per boot after the framework restores schedules + subscriptions). The subscription is persisted and restored across reboots.

SignatureCopy Anchor Link

function subscribeToLocationEvent(eventName: string, handler: unknown): void

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

ExamplesCopy Anchor Link

subscribeToLocationEvent('systemStart', onSystemStart);

function onSystemStart() {
  scheduleAtSunset(onSunset);
}

See alsoCopy Anchor Link

sendLocationEvent · subscriptions and events

sendLocationEventCopy Anchor Link

Fire a named location event. Every smart app subscribed to that name — including other apps — receives it, which makes it the inter-app back-channel.

SignatureCopy Anchor Link

function sendLocationEvent(eventName, data)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

NotesCopy Anchor Link

• Not declared in ambient.d.ts yet, so TypeScript authors need declare function sendLocationEvent(eventName: string, data?: unknown): void;.

ExamplesCopy Anchor Link

sendLocationEvent('house.guestMode', { enabled: true });

See alsoCopy Anchor Link

subscribeToLocationEvent

getEntityIdsCopy Anchor Link

Normalise an entity input to a list of entity ids: one id for a single pick, every id for a multi-select proxy, [] for anything else.

SignatureCopy Anchor Link

function getEntityIds(entity)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string[]

NotesCopy Anchor Link

• Not declared in ambient.d.ts; declare it yourself in TypeScript or use Array.isArray(input) ? input : [input] on the wrappers instead.

ExamplesCopy Anchor Link

const ids = getEntityIds($g.lights); // ['light.kitchen', 'light.hall']