MQTT Trigger

The MQTT trigger enables you to execute actions in response to a MQTT message within Home Assistant. It implements the same functionality as the Home Assistant mqtt trigger, providing a seamless integration between SmartBeans and Home Assistant.

Annotating Methods

The @OnMqttTrigger annotation allows you to invoke any SmartBean method when something is published to a MQTT topic.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnMqttTrigger(topic = "some/topic")
  public void onTopicPublished() {
    sb.log("MQTT topic published.");
  }
}

Specific Payload

By specifying a payload, the method is only executed if the specific payload is published to the topic.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnMqttTrigger(topic = "some/state", payload = "on")
  public void onPayloadOn() {
    sb.log("Payload is on now.");
  }
}

The payload option can be combined with a valueTemplate to process the message received on the given MQTT topic before matching it with the payload. The trigger in the example below will trigger only when the message received on living_room/switch/ac is valid JSON, with a key state which has the value on.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnMqttTrigger(topic = "living_room/switch/ac", payload = "on", valueTemplate = "{{ value_json.state }}")
  public void onPayloadOn() {
    sb.log("AC state is on now.");
  }
}

State Events

Your annotated method can optionally include a MqttEvent 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 the published topic and payload.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnMqttTrigger(topic = "some/topic")
  public void onPublish(MqttEvent event) {
    sb.log("Topic " + event.getTopic() + " is published with payload " + event.getPayload() + ".");
  }
}

When working with JSON payloads, you can use getPayloadAsObject() to directly access the parsed JSON data instead of parsing it manually.

public class ASampleBean implements SmartBean {

  private SmartBeans sb;

  @OnMqttTrigger(topic = "living_room/switch/ac")
  public void onPublish(MqttEvent event) {
    sb.log("State of AC is " + event.getPayloadAsObject().asString("state") + ".");
  }
}

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 MQTT trigger, you can use the mqtt() 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 MQTT topic 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<MqttEvent> mqttTriggerRegistration;

  public void registerMqttTrigger() {
    mqttTriggerRegistration = sb.registerTrigger(
      Triggers.mqtt()
          .topic("living_room/switch/ac")
          .hasPayload("on")
    );
    mqttTriggerRegistration.onTrigger(this::onSwitchedOn);
  }
  
  public void unregisterMqttTrigger() {
    mqttTriggerRegistration.unregister();
  }

  private void onSwitchedOn(MqttEvent event) {
    sb.log("AC is on now.");
  }
}