Entity and EntityWrapper
The device handle every entity input hydrates to.
EntityWrapper
Definition
class EntityWrapper { constructor(entityId: string); readonly entityId: string; /** Current state value of this entity, looked up synchronously * through the host bridge. Throws if the entity isn't registered * or has no cached state — callers that want to gate on missing * entities should wrap in try/catch. */ getState(): unknown; /** Current attributes bag, looked up synchronously through the * host bridge. Throws on a missing entity (same semantics as * `getState`). */ getAttributes(): Record<string, unknown>; /** Convenience for `getAttributes()[attributeName]`. Throws if the * attribute isn't on the entity. */ getAttribute(attributeName: string): unknown; /** True when the live state is `value` — the raw token (`'on'`) or the * friendly label the app shows for this entity (`'Open'`, `'armed * away'`), case- and separator-insensitive. A raw token always matches * itself. `state` / `getState()` stay the raw string. Throws on an * unknown entity (same as `getState`). */ is(value: string): boolean; /** `!is(value)`. */ isNot(value: string): boolean; }Members
| Name | Type | Optional | Description |
|---|---|---|---|
entityId | string | no | — |
getState() | unknown | no | Current state value of this entity, looked up synchronously through the host bridge. Throws if the entity isn't registered or has no cached state — callers that want to gate on missing entities should wrap in try/catch. |
getAttributes() | Record<string, unknown> | no | Current attributes bag, looked up synchronously through the host bridge. Throws on a missing entity (same semantics as getState). |
getAttribute() | unknown | no | Convenience for getAttributes()[attributeName]. Throws if the attribute isn't on the entity. |
is() | boolean | no | True when the live state is value — the raw token ('on') or the friendly label the app shows for this entity ('Open', 'armed away'), case- and separator-insensitive. A raw token always matches itself. state / getState() stay the raw string. Throws on an unknown entity (same as getState). |
isNot() | boolean | no | !is(value). |
apps/edge-runtime/src/core/smartapp/builtin/ambient.d.ts:297
Entity
Convenience alias for the actual runtime shape of an entity input. The EntityWrapper proxy intercepts every property access and returns a callable that dispatches a callService host command — so bare names like light.turnOn() work at runtime. Modelling that as an index signature on the class itself would force entityId to also be a (...args) => Promise<void>, so we keep the class clean and expose the dynamic surface via this intersection.
Definition
type Entity = EntityWrapper & {
[serviceName: string]: (data?: Record<string, unknown>) => Promise<void>;
};apps/edge-runtime/src/core/smartapp/builtin/ambient.d.ts:359
Members
getState
Current state value of this entity, looked up synchronously through the host bridge. Throws if the entity isn't registered or has no cached state — callers that want to gate on missing entities should wrap in try/catch.
Signature
getState(): unknownParameters
None.
Returns
unknown — The entity’s current state value (for example "on", "locked", 21.5).
Examples
if ($g.door.getState() === 'unlocked') { /* … */ }getAttributes
Current attributes bag, looked up synchronously through the host bridge. Throws on a missing entity (same semantics as getState).
Signature
getAttributes(): Record<string, unknown>Parameters
None.
Returns
Record<string, unknown>
getAttribute
Convenience for getAttributes()[attributeName]. Throws if the attribute isn't on the entity.
Signature
getAttribute(attributeName: string): unknownParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
attributeName | string | yes | — | Attribute key, e.g. brightnessPercent. |
Returns
unknown
is
True when the live state is value — the raw token ('on') or the friendly label the app shows for this entity ('Open', 'armed away'), case- and separator-insensitive. A raw token always matches itself. state / getState() stay the raw string. Throws on an unknown entity (same as getState).
Signature
is(value: string): booleanParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
value | string | yes | — | A raw token ('on') or the friendly label the app shows for this entity ('Open', 'Detected', 'armed away'), any case; spaces, hyphens and underscores are interchangeable. |
Returns
boolean — true when the live state is value. Throws when the entity is unknown, like getState().
Notes
getState()and.statestill return the raw token; only the comparison understands labels.- Resolution goes through the entity's domain and device class, so
'Open'meansonfor a door sensor andopenfor a cover.
Examples
if ($g.door.is('Open') && $g.panel.is('Armed Away')) {
sendPushNotification('Door open while armed away', 'Security', true);
}See also
isNot · matchesState · getState
isNot
The negation of is(value).
Signature
isNot(value: string): booleanParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
value | string | yes | — | A raw token or friendly label, as for is(). |
Returns
boolean
Examples
if ($g.lock.isNot('Locked')) $g.lock.lock();See also
entityId
The entity id this wrapper targets, e.g. light.kitchen.
Signature
readonly entityId: stringParameters
None.
Returns
string
state
Available at runtime but not declared in ambient.d.ts; add your own declare line when authoring in TypeScript.
Getter alias of getState().
Signature
stateParameters
None.
Notes
- Not declared in the TypeScript types; prefer
getState().
attributes
Available at runtime but not declared in ambient.d.ts; add your own declare line when authoring in TypeScript.
Getter alias of getAttributes().
Signature
attributesParameters
None.
Notes
- Not declared in the TypeScript types; prefer
getAttributes().
describe
Available at runtime but not declared in ambient.d.ts; add your own declare line when authoring in TypeScript.
Debug string naming the wrapped entity.
Signature
describe()Parameters
None.
toJSON
Available at runtime but not declared in ambient.d.ts; add your own declare line when authoring in TypeScript.
Serialises to { entityId, type: "EntityWrapper" }, so wrappers can be logged or stored in state safely.
Signature
toJSON()Parameters
None.
Generated from docs-bundle v0.1.0, novon-platform 9ce3486c (2026-10-09).