State Capture Device - Smart (Components) Toolkit for Homey

What is a State Capture Device?

While the regular State Device stores fixed values defined during setup, the State Capture Device lets you dynamically capture the current values of devices at runtime.

Think of it as a "template" that defines which devices and capabilities to capture, without storing the actual values until you explicitly capture them.

Key Differences from State Device

Feature	State Device	State Capture Device
Values	Fixed at setup	Captured at runtime
Named States	One per device	Multiple named slots
Stack Operations	No	Yes (push/pop/peek)
Use Case	Predefined scenes	Dynamic state management

Advantages and Limitations

✓ Advantages

• Multiple named states on a single device
• Dynamic capture at runtime
• Stack for temporary "undo" operations
• Homey tokens for dynamic state names

⚠ Limitations

• Cannot be activated like a regular device
• Requires a flow to capture/apply states
• State must be saved before it can be used

⚠ Important: Two Separate Systems

The State Capture Device has two completely separate storage systems that do NOT interact with each other:

📁 Named States (Persistent)

Permanent storage with explicit names.

• Capture state as "name"
• Apply captured state "name"
• Delete captured state "name"

Persists until deleted. Survives restarts.

📚 Stack (Transient)

Temporary LIFO storage for quick save/restore.

• Push current state to stack
• Pop and apply from stack
• Peek (apply without removing)

For temporary operations. No names.

These systems are NOT interchangeable!

❌ You cannot "pop" a named state
❌ You cannot "apply" something from the stack by name
❌ You cannot "push" to a named slot

⚠ Critical: Named States Must Be Saved First

A named state must be saved in a separate flow before you can apply it. You cannot save and apply a named state in the same flow. This does not apply to stack operations (push/pop), which work within the same flow.

❌ Will NOT Work

WHEN: Button pressed
THEN: Capture state as "my_scene"
THEN: Apply captured state "my_scene"
       ↑ FAILS - not yet available!

✓ Correct Approach

FLOW 1 - Save:
WHEN: "Save" button pressed
THEN: Capture state as "my_scene"

FLOW 2 - Apply (later):
WHEN: "Apply" button pressed
THEN: Apply captured state "my_scene"

Why?

The state is saved asynchronously. The "Apply" action runs before the save completes.

Use Cases

Temporary Interruptions

Save current lighting state before a doorbell ring, turn on all lights, then restore after.

WHEN: Doorbell rings
THEN: Push current state
THEN: Set all lights to 100%
THEN: Wait 5 minutes
THEN: Pop state (restore previous)

Named Scene Snapshots

Capture and name the current state when users are happy with their lighting setup.

WHEN: "Save Scene" button pressed
THEN: Capture state as "[[scene_name]]"

WHEN: "Apply Scene" triggered
THEN: Apply captured state "[[scene_name]]"

Undo Functionality

Push state before any major change. Users can "undo" by popping the stack.

Nested State Changes

Stack supports multiple levels - push before each change, pop in reverse order to unwind.

Setting Up a State Capture Device (Template)

1

Select Scope

Choose which zones (rooms) contain devices you want to capture.

2

Select Devices

Choose which devices from the selected zones should be included.

3

Select Capabilities

For each device, select which capabilities to capture (e.g., onoff, dim).

4

Review & Create

Review the generated template and create your device.

Flow Cards: Named States

Named states are key-value storage for captured device states.

Capture state to name

Action

Reads current values and stores them under the given name.

Apply captured state

Action

Retrieves a named state and applies all stored values.

Delete captured state

Action

Removes a named state from storage.

State exists

Condition

Check if a named state has been captured.

Backup & Restore Named States

Export all named states as JSON for backup, or import them to restore or transfer states between devices.

Export named states

Action

Exports all named states as a JSON string. Use the json_data token to store or send the backup.

Import named states

Action

Imports named states from a JSON string. States with the same name will be overwritten.

JSON Structure

The exported JSON contains all named states (not stack data):

{
  "states": {
    "movie_night": {
      "captured_at": "2025-01-15T20:30:00.000Z",
      "values": {
        "device-uuid-1": { "onoff": true, "dim": 0.3 },
        "device-uuid-2": { "onoff": false }
      }
    },
    "morning_routine": {
      "captured_at": "2025-01-15T07:00:00.000Z",
      "values": { ... }
    }
  }
}

Import overwrites existing states!

If you import a state with a name that already exists, the existing state will be replaced with the imported one.

Use Case: Backup to Timeline

Use the export action and send the json_data token to a Timeline notification for safekeeping.

Flow Cards: Stack Operations

LIFO storage for temporary state management. Perfect for "save and restore" patterns.

Push state to stack

Action

Captures current values and pushes them onto the stack.

Pop state from stack

Action

Removes the most recent state and applies it to devices.

Peek and apply state

Action

Applies the most recent state without removing it.

Clear stack

Action

Removes all states from the stack.

Stack is empty / Stack depth

Condition

Check if stack is empty or compare depth.

Flow Cards: Triggers

State was captured / applied

Trigger

Fires when a state is captured or applied. Token: state_name

Capture/Apply error occurred

Trigger

Fires on errors. Tokens: error, state_name

Storage Limits

Max named states	50 per device
Max stack depth	20 per device

States are stored persistently. They survive app restarts but are removed when the device is deleted.

Error Handling

Device not found: Skipped during capture/apply. Other devices continue normally.

Capability not found: Skipped. The error trigger fires with details.

State not found: Applying a non-existent state or popping an empty stack triggers an error.