State Trigger

The state trigger enables you to execute actions in response to state changes of entities within Home Assistant. This trigger mechanism allows you to monitor and react to any state changes in your smart home system. It implements the same functionality as the Home Assistant state trigger, providing a seamless integration between SmartBeans and Home Assistant.

tip

For entities with numeric states (such as temperature sensors), it is recommended to utilize a numeric state trigger for better precision and control.

Annotating Methods

The @OnStateTrigger annotation allows you to invoke any SmartBean method when a state change occurs. You can define specific trigger conditions using the annotation's properties.

public class ASampleBean implements SmartBean {
  
  private SmartBeans sb;

  @OnStateTrigger(entity = "binary_sensor.movement_kitchen", to = "on")
  public void onMovementInTheKitchen() {
    sb.log("There is movement in the kitchen!");
  }
}

Advanced Features

The state trigger supports several advanced features from Home Assistant, providing fine-grained control over when your actions are executed:

• from: The state to transition from
• to: The state to transition to
• notFrom: Exclude specific source states
• notTo: Exclude specific target states
• _for: Time duration the state must remain unchanged

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnStateTrigger(
      entity = "device_tracker.elvis", 
      from = "home", 
      notTo = "unavailable", 
      _for = @Interval(seconds = 30)
  )
  public void onPersonLeft() {
    sb.log("Elvis has left the building!");
  }
}

Attribute Changes

You can monitor specific attribute changes of an entity by using the attribute property in the annotation.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnStateTrigger(
      entity = "climate.bathroom_heating", 
      attribute = "hvac_mode", 
      to = "heat", 
      _for = @Interval(minutes = 10)
  )
  public void onHeatingForTenMinutes() {
    sb.log("Boiler is heating for 10 minutes...");
  }
}

State Events

Your annotated method can optionally include a StateEvent parameter. When the trigger is fired, SmartBeans provides an event object that gives you access to the event parameters. Through this object, you can retrieve both the previous (old) and current (new) state and attribute values.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnStateTrigger(entity = "climate.bathroom_heating", notTo = "unavailable")
  public void onStateChange(StateEvent event) {
    sb.log(
        "Boiler switched from " + event.getOldState().getState() + " to " + event.getNewState().getState() + ". " +
        "Fan mode is " + event.getNewState().getAttributes().asString(Climate.ATTR_FAN_MODE)
    );
  }
}

This approach allows you to efficiently manage multiple state changes through a single method.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnStateTrigger(entity = "binary_sensor.movement_kitchen")
  public void onMovementChange(StateEvent event) {
    BinarySensor.State state = BinarySensor.State.fromValue(event.getNewState().getState());
    if(state == BinarySensor.State.ON) {
      sb.log("Movement detected!");
    }
    else {
      sb.log("No movement detected!");
    }
  }
}

Register Triggers Programmatically

As an alternative to the annotation-based approach, you can register triggers programmatically using the registerTrigger() method of the SmartBeans API. To register a state change trigger, you can use the state() factory method of the Triggers class. This factory provides a fluent API to create the same triggers as with annotations. There are two main reasons to choose the programmatic approach over annotations:

1. You need to create triggers with dynamic parameters, for example when the entity ID is generated by business logic.
2. You need to register or unregister the trigger at a specific point in time, rather than having it permanently active.

Here is an example of registering and unregistering a trigger with the programmatic approach:

public class ASampleBean implements SmartBean {

  private SmartBeans sb;
  private TriggerRegistration<StateEvent> stateTriggerRegistration;

  public void registerStateTrigger() {
    stateTriggerRegistration = sb.registerTrigger(
      Triggers.state()
          .ofEntity("climate.bathroom_heating")
          .ofAttribute(Climate.ATTR_HVAC_MODE)
          .to(Climate.HvacMode.HEAT.value())
          .forDuration(Duration.ofMinutes(10))
    );
    stateTriggerRegistration.onTrigger(this::onHeatingForTenMinutes);
  }
  
  public void unregisterStateTrigger() {
    stateTriggerRegistration.unregister();
  }

  private void onHeatingForTenMinutes(StateEvent event) {
    sb.log("Boiler is heating for 10 minutes...");
  }
}