Numeric State Trigger

The numeric state trigger enables you to execute actions in response to state changes of entities with a numeric state, such as temperature sensors, within Home Assistant. It implements the same functionality as the Home Assistant numeric state trigger, providing a seamless integration between SmartBeans and Home Assistant.

Annotating Methods

The @OnNumericStateTrigger 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;

  @OnNumericStateTrigger(entity = "sensor.outside_temperature", above = 30)
  public void onVeryHot() {
    sb.log("It's getting hot outside, let's jump in the pool!");
  }
}

Advanced Features

The numeric state trigger offers advanced Home Assistant features that provide precise control over when your actions are triggered:

• above: Triggers when the value transitions from below to above the specified threshold
• below: Triggers when the value transitions from above to below the specified threshold
• for: Specifies the minimum duration that the value must remain above or below the threshold before triggering

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnNumericStateTrigger(entity = "sensor.free_memory", below = 10, _for = @Interval(days = 2))
  public void onPermanentlyLowMemory() {
    sb.log("We are running out of memory.");
  }
}

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;

  @OnNumericStateTrigger(entity = "climate.bathroom_heating", attribute = "current_temperature", below = 20)
  public void onColdInTheBathroom() {
    sb.log("It's too cold in the bathroom.");
  }
}

Value Templates

In addition to entities and attributes, you can use templates to monitor specific values and create triggers when these values exceed or fall below defined thresholds.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnNumericStateTrigger(
      entity = "sensor.temperature",
      valueTemplate = "{{ state.state | float * 9 / 5 + 32 }}",
      above = 70
  )
  public void onAboveThreshold(StateEvent event) {
    sb.log("Temperature is above 70 degrees Fahrenheit!");
  }
}

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;

  @OnNumericStateTrigger(entity = "sensor.temperature_livingroom")
  public void watchLivingRoomTemperature(StateEvent evt) {
    double newTemp = evt.getNewState().getStateAsDouble(0d);
    double oldTemp = evt.getNewState().getStateAsDouble(0d);
    if(newTemp > 25 && oldTemp < newTemp) {
      sb.log("Living room is hot! Switch on AC.");
    }
    else if(newTemp < 20 && oldTemp > newTemp) {
      sb.log("Living room is cold! Switch on Heater.");
    }
    else {
      sb.log("Living room is ok!");
    }
  }
}

The state object provides convenient methods to retrieve the state value as int, Integer, double or Double. Methods with a default parameter return primitive types, while methods without a default parameter return wrapper types. The wrapper types can be null in certain cases, for instance when the sensor is unavailable. The methods with default values, return the defaults in these cases.

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 numeric state change trigger, you can use the numericState() 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.numericState()
          .ofEntity("climate.bathroom_heating")
          .ofAttribute(Climate.ATTR_CURRENT_TEMPERATURE)
          .below(20)
          .forDuration(Duration.ofMinutes(10))
    );
    stateTriggerRegistration.onTrigger(this::turnHeatingOn);
  }
  
  public void unregisterStateTrigger() {
    stateTriggerRegistration.unregister();
  }

  private void turnHeatingOn(StateEvent event) {
    //Turn heating on...
  }
}