Time Trigger

The time trigger enables you to execute actions at a specific time. It implements the same functionality as the Home Assistant time trigger, providing a seamless integration between SmartBeans and Home Assistant.

Annotating Methods

The @OnTimeTrigger annotation allows you to invoke any SmartBean method every day at a specific time.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnTimeTrigger(at = "08:00")
  public void itsTime() {
    sb.log("It's 8 o'clock");
  }
}

Using Entities

You can also specify the time using entities. As in Home Assistant, you can use any input_datetime entity or any sensor entity whose device class is set to datetime.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnTimeTrigger(entityId = "input_datetime.alarmtime")
  public void itsTime() {
    sb.log("Wake up!");
  }
}

Define Offset

By specifying an offset, the method is scheduled relative to the entity's value. The offset can be positive (after) or negative (before) and must be provided in the hh:mm:ss format, optionally prefixed with + or -.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnTimeTrigger(entityId = "input_datetime.alarmtime", offset = "-00:30:00")
  public void itsTime() {
    sb.log("In 30 minutes it's time to wake up.");
  }
}

Weekdays

It's possible to specify the weekdays on which the trigger should fire.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnTimeTrigger(at = "06:00", weekday = Weekday.MONDAY)
  public void itsTime() {
    sb.log("I hate mondays");
  }
}

Time Events

Your annotated method can optionally include a TimeEvent parameter. When the trigger is fired, SmartBeans provides an event object that gives you access to the event parameters.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnTimeTrigger(entityId = "input_datetime.alarmtime")
  public void itsTime(TimeEvent event) {
    sb.log("Wake up, it's " + event.getTime());
  }
}

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 time trigger, you can use the time() 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<TimeEvent> timeTriggerRegistration;

  public void registerTimeTrigger() {
    timeTriggerRegistration = sb.registerTrigger(
      Triggers.time()
          .at("input_datetime.alarmtime", Duration.ofMinutes(30).negated())
          .onlyOn(Weekday.MONDAY)
    );
    timeTriggerRegistration.onTrigger(this::onTime);
  }

  public void unregisterTimeTrigger() {
    timeTriggerRegistration.unregister();
  }

  private void onTime(TimeEvent event) {
    sb.log("Wake up!");
  }
}