MQTT Siren


The mqtt siren platform lets you control your MQTT enabled sirens and text based notification devices.

Configuration

In an ideal scenario, the MQTT device will have a state_topic to publish state changes. If these messages are published with a RETAIN flag, the MQTT siren will receive an instant state update after subscription, and will start with the correct state. Otherwise, the initial state of the siren will be false / off.

When a state_topic is not available, the siren will work in optimistic mode. In this mode, the siren will immediately change state after every command. Otherwise, the siren will wait for state confirmation from the device (message from state_topic).

Optimistic mode can be forced, even if the state_topic is available. Try to enable it, if experiencing incorrect operation.

To enable this siren in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
siren:
  - platform: mqtt
    command_topic: "home/bedroom/siren/set"

Configuration Variables

availability list (Optional)

A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with availability_topic.

payload_available string (Optional, default: online)

The payload that represents the available state.

payload_not_available string (Optional, default: offline)

The payload that represents the unavailable state.

topic string Required

An MQTT topic subscribed to receive availability (online/offline) updates.

value_template template (Optional)

Defines a template to extract device’s availability from the topic. To determine the devices’s availability result of this template will be compared to payload_available and payload_not_available.

availability_mode string (Optional, default: latest)

When availability is configured, this controls the conditions needed to set the entity to available. Valid entries are all, any, and latest. If set to all, payload_available must be received on all configured availability topics before the entity is marked as online. If set to any, payload_available must be received on at least one configured availability topic before the entity is marked as online. If set to latest, the last payload_available or payload_not_available received on any configured availability topic controls the availability.

availability_template template (Optional)

Defines a template to extract device’s availability from the availability_topic. To determine the devices’s availability result of this template will be compared to payload_available and payload_not_available.

availability_topic string (Optional)

The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with availability.

available_tones list (Optional)

A list of available tones the siren supports. When configured, this enables the support for setting a tone and enables the tone state attribute.

command_template template (Optional)

Defines a template to generate the payload to send to command_topic. The variable value will be assigned with the configured payload_on or payload_off setting. The siren turn on service parameters tone, volume_level or duration can be used as variables in the template. When operation in optimistic mode the corresponding state attributes will be set. Turn parameters will be filtered if a device misses the support.

command_off_template template (Optional)

Defines a template to generate the payload to send to command_topic when the siren turn off service is called. By default command_template will be used as template for service turn off. The variable value will be assigned with the configured payload_off setting.

command_topic string (Optional)

The MQTT topic to publish commands to change the siren state. Without command template a JSON payload is published. When the siren turn on service is called, the startup parameters will be added to the JSON payload. The state value of the JSON payload will be set to the the payload_on or payload_off configured payload.

device map (Optional)

Information about the device this siren is a part of to tie it into the device registry. Only works through MQTT discovery and when unique_id is set. At least one of identifiers or connections must be present to identify the device.

configuration_url string (Optional)

A link to the webpage that can manage the configuration of this device. Can be either an HTTP or HTTPS link.

connections list (Optional)

A list of connections of the device to the outside world as a list of tuples [connection_type, connection_identifier]. For example the MAC address of a network interface: "connections": [["mac", "02:5b:26:a8:dc:12"]].

identifiers string | list (Optional)

A list of IDs that uniquely identify the device. For example a serial number.

manufacturer string (Optional)

The manufacturer of the device.

model string (Optional)

The model of the device.

name string (Optional)

The name of the device.

suggested_area string (Optional)

Suggest an area if the device isn’t in one yet.

sw_version string (Optional)

The firmware version of the device.

via_device string (Optional)

Identifier of a device that routes messages between this device and Home Assistant. Examples of such devices are hubs, or parent devices of a sub-device. This is used to show device topology in Home Assistant.

enabled_by_default boolean (Optional, default: true)

Flag which defines if the entity should be enabled when first added.

encoding string (Optional, default: utf-8)

The encoding of the payloads received and published messages. Set to "" to disable decoding of incoming payload.

entity_category string (Optional, default: None)

The category of the entity.

icon icon (Optional)

Icon for the entity.

json_attributes_template template (Optional)

Defines a template to extract the JSON dictionary from messages received on the json_attributes_topic. Usage example can be found in MQTT sensor documentation.

json_attributes_topic string (Optional)

The MQTT topic subscribed to receive a JSON dictionary payload and then set as sensor attributes. Usage example can be found in MQTT sensor documentation.

name string (Optional, default: MQTT Siren)

The name to use when displaying this siren.

object_id string (Optional)

Used instead of name for automatic generation of entity_id

optimistic boolean (Optional)

Flag that defines if siren works in optimistic mode.

Default:

true if no state_topic defined, else false.

payload_available string (Optional, default: online)

The payload that represents the available state.

payload_not_available string (Optional, default: offline)

The payload that represents the unavailable state.

payload_off string (Optional, default: OFF)

The payload that represents off state. If specified, will be used for both comparing to the value in the state_topic (see value_template and state_off for details) and sending as off command to the command_topic.

payload_on string (Optional, default: ON)

The payload that represents on state. If specified, will be used for both comparing to the value in the state_topic (see value_template and state_on for details) and sending as on command to the command_topic.

qos integer (Optional, default: 0)

The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.

retain boolean (Optional, default: false)

If the published message should have the retain flag on or not.

state_off string (Optional)

The payload that represents the off state. Used when value that represents off state in the state_topic is different from value that should be sent to the command_topic to turn the device off.

Default:

payload_off if defined, else 'OFF'

state_on string (Optional)

The payload that represents the on state. Used when value that represents on state in the state_topic is different from value that should be sent to the command_topic to turn the device on.

Default:

payload_on if defined, else 'ON'

state_topic string (Optional)

The MQTT topic subscribed to receive state updates. When a JSON payload is detected, the state value of the JSON payload should supply the payload_on or payload_off defined payload to turn the siren on or off. Additional the state attributes duration, tone and volume_level can be updated. Use value_template to update render custom payload to a compliant JSON payload. Attributes will only be set if the function is supported by the device and a valid value is supplied. The initial state will be unknown. The state will be reset to unknown if a None payload or null JSON value is received as a state update.

state_value_template string (Optional)

Defines a template to extract device’s state from the state_topic. To determine the siren’s state result of this template will be compared to state_on and state_off. Alternatively value_template can be used to render to a valid JSON payload.

support_duration boolean (Optional, default: true)

Set to true if the MQTT siren supports the duration service turn on parameter and enables the duration state attribute.

support_volume_set boolean (Optional, default: true)

Set to true if the MQTT siren supports the volume_set service turn on parameter and enables the volume_level state attribute.

unique_id string (Optional)

An ID that uniquely identifies this siren device. If two sirens have the same unique ID, Home Assistant will raise an exception.

Make sure that your topic matches exactly. some-topic/ and some-topic are different topics.

Examples

In this section, you will find an example of how to use this siren platform.

Full configuration

The example below shows a full configuration for a siren.

# Example configuration.yaml entry
siren:
  - platform: mqtt
    unique_id: custom_siren
    name: "Intrusion siren"
    state_topic: "home/alarm/siren1"
    command_topic: "home/alarm/siren1/set"
    available_tones:
      - ping
      - siren
    availability:
      - topic: "home/alarm/siren1/available"
    payload_on: "ON"
    payload_off: "OFF"
    state_on: "ON"
    state_off: "OFF"
    optimistic: false
    qos: 0
    retain: true

For a check, you can use the command line tools mosquitto_pub shipped with mosquitto to send MQTT messages. This allows you to operate your siren manually:

mosquitto_pub -h 127.0.0.1 -t home/alarm/siren1 -m "ON"