MQTT Infrared
The MQTT Infrared integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to integrate infrared emitter or receiver devices via MQTT.
Configuration
To use an MQTT infrared entity in your installation, add an MQTT device as a subentry, or add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.
After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes.
The MQTT infrared platform supports a configuration schema for infrared emitter and receiver devices.
Infrared emitter schema
# Example configuration.yaml entry
mqtt:
- infrared:
schema: emitter
command_topic: command-topic
Alternatively, a more advanced approach is to set it up via MQTT discovery.
Configuration Variables
A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with availability_topic.
The payload that represents the available state.
The payload that represents the unavailable state.
The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with availability.
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 most recent payload_available or payload_not_available received on any configured availability topic determines availability.
Defines a template to extract the device’s availability from the availability_topic. To determine the device’s availability, the result of this template will be compared to payload_available and payload_not_available.
Defines a template to generate the payload to send to command_topic. Available variables for templating are timings, a list of integers that represent the microseconds a pulse is on (positive int) and off (negative int), modulation, the modulation frequency for the signal and repeat_count, the number of times the signal sequence is to be repeated. The signal data is derived from the commands that are provided via the infrared protocols library.
The MQTT topic to publish the MQTT signal payload. Without a command_template defined, a JSON payload will be published when an infrared command is issued.
Use default_entity_id instead of name for automatic generation of the entity ID. For example, infrared.foobar. When used without a unique_id, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, it will be created with a number appended. When used with a unique_id, the default_entity_id is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
Device information for this infrared entity. Used to link the entity to a device in the device registry. Only works when unique_id is set. At least one of identifiers or connections is required to identify the device.
A link to the webpage that can manage the configuration of this device. Can be either an http://, https:// or an internal homeassistant:// URL.
A list of device connections to the outside world, each specified as a tuple of [connection_type, connection_identifier]. For example, the MAC address of a network interface: "connections": [["mac", "02:5b:26:a8:dc:12"]].
A list of IDs that uniquely identify the device. For example, a serial number.
Controls whether this entity is enabled by default. When set to true, the entity is enabled and usable immediately. Disabled entities are hidden by default until you enable them from the device page.
The encoding used for received payloads and published messages. Set to "" to disable decoding of incoming payload.
The category of the entity.
Defines a template to extract the JSON dictionary from messages received on the json_attributes_topic.
The MQTT topic subscribed to for receiving a JSON dictionary payload that sets the entity attributes. Implies force_update of the current state when a message is received on this topic.
Controls how long queued or retained messages sent from Home Assistant persist at the broker for offline subscribers. This option prevents the broker from retaining stale messages. The expected value for this option is a JSON mapping, for example, {"days": 1, "hours": 2, "minutes": 20, "seconds": 30} or {"seconds": 3600}.
Number of days published messages are queued or retained for offline subscribers.
Number of hours published messages are queued or retained for offline subscribers.
Number of minutes published messages are queued or retained for offline subscribers.
The name of the infrared entity. Can be set to null if only the device name is relevant.
Must be infrared. Only allowed and required in MQTT auto discovery device messages.
The maximum QoS level to be used when receiving and publishing messages.
If the published message should have the retain flag on or not.
Infrared receiver schema
# Example configuration.yaml entry
mqtt:
- infrared:
schema: receiver
state_topic: state-topic
Alternatively, a more advanced approach is to set it up via MQTT discovery.
Configuration Variables
A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with availability_topic.
The payload that represents the available state.
The payload that represents the unavailable state.
The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with availability.
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 most recent payload_available or payload_not_available received on any configured availability topic determines availability.
Defines a template to extract the device’s availability from the availability_topic. To determine the device’s availability, the result of this template will be compared to payload_available and payload_not_available.
Use default_entity_id instead of name for automatic generation of the entity ID. For example, infrared.foobar. When used without a unique_id, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, it will be created with a number appended. When used with a unique_id, the default_entity_id is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
Device information for this infrared entity. Used to link the entity to a device in the device registry. Only works when unique_id is set. At least one of identifiers or connections is required to identify the device.
A link to the webpage that can manage the configuration of this device. Can be either an http://, https:// or an internal homeassistant:// URL.
A list of device connections to the outside world, each specified as a tuple of [connection_type, connection_identifier]. For example, the MAC address of a network interface: "connections": [["mac", "02:5b:26:a8:dc:12"]].
A list of IDs that uniquely identify the device. For example, a serial number.
Controls whether this entity is enabled by default. When set to true, the entity is enabled and usable immediately. Disabled entities are hidden by default until you enable them from the device page.
The encoding used for received payloads and published messages. Set to "" to disable decoding of incoming payload.
The category of the entity.
Defines a template to extract the JSON dictionary from messages received on the json_attributes_topic.
The MQTT topic subscribed to for receiving a JSON dictionary payload that sets the entity attributes. Implies force_update of the current state when a message is received on this topic.
Controls how long queued or retained messages sent from Home Assistant persist at the broker for offline subscribers. This option prevents the broker from retaining stale messages. The expected value for this option is a JSON mapping, for example, {"days": 1, "hours": 2, "minutes": 20, "seconds": 30} or {"seconds": 3600}.
Number of days published messages are queued or retained for offline subscribers.
Number of hours published messages are queued or retained for offline subscribers.
Number of minutes published messages are queued or retained for offline subscribers.
The name of the infrared entity. Can be set to null if only the device name is relevant.
Must be infrared. Only allowed and required in MQTT auto discovery device messages.
The maximum QoS level to be used when receiving and publishing messages.
If the published message should have the retain flag on or not.
The MQTT topic subscribed to receive a JSON payload with timings as required attribute and and modulation as optional attribute. The timings attribute must hold a list of integers representing the on and off timings in microseconds the infrared emitter was on (positive) or off (negative). The modulation of the infrared signal in Hz, typical 38 kHz.
An ID that uniquely identifies this infrared entity. If two infrared entities have the same unique ID Home Assistant will raise an exception. Required when used with device-based discovery.
Infrared signal schema
The signal data schema is derived from the commands that are provided via the infrared protocols library.
By default, an infrared receiver entity expects a JSON payload that includes required timings and optional modulation attributes. The timings attribute must hold a list of integers representing the on and off timings in microseconds the infrared emitter was on (positive) or off (negative). The modulation of the infrared signal in Hz, typical 38 kHz.
An example message to receive:
{
"timings":[9000,-4500,562,-1687,562,-1687,562,-562,562,-1687,562,-1687,562,
-1687,562,-1687,562,-1687,562,-562,562,-562,562,-1687,562,-562,562,-562,562,
-562,562,-562,562,-562,562,-1687,562,-1687,562,-1687,562,-562,562,-1687,562,
-1687,562,-1687,562,-1687,562,-562,562,-562,562,-562,562,-1687,562,-562,562,
-562,562,-562,562,-562,562],
"modulation":38000
}
The message should contain the timings attribute and optional the modulation attribute, any other attributes in the JSON message will be ignored.
The message will silently be ignored if null, None or an empty string is received instead.
An example message that is sent when a command is issued:
{
"timings":[9000,-4500,562,-1687,562,-1687,562,-562,562,-1687,562,-1687,562,
-1687,562,-1687,562,-1687,562,-562,562,-562,562,-1687,562,-562,562,-562,562,
-562,562,-562,562,-562,562,-1687,562,-1687,562,-1687,562,-562,562,-1687,562,
-1687,562,-1687,562,-1687,562,-562,562,-562,562,-562,562,-1687,562,-562,562,
-562,562,-562,562,-562,562],
"modulation":38000,
"repeat_count":0
}
Examples
Manual configuration example
This is an example of a manual configured MQTT infrared receiver item.
# Example configuration.yaml entry
mqtt:
- infrared:
name: "My Infrared receiver"
schema: "receiver"
icon: mdi:ab-testing
state_topic: "ir/receive-signal"
This is an example of a manual configured MQTT infrared emitter item.
# Example configuration.yaml entry
mqtt:
- infrared:
name: "My Infrared emitter"
schema: "emitter"
icon: mdi:ab-testing
command_topic: "ir/send-signal"
Discovery of Tuya based IR blaster
Some Tuya based IR blasters will support MQTT discovery for an infrared emitter and receiver through Zigbee2MQTT. Note that the IR receiver will only when the device is in learning mode. Most times you can enable learning mode continuously by turning on learning mode every 15 seconds, of after an infrared signal was received.
Example automation, to turn on learning mode for Tuya IR blasters via Zigbee2MQTT:
alias: Activate infrared learning mode
description: ""
triggers:
- trigger: time_pattern
seconds: /15
- trigger: mqtt
options:
topic: zigbee2mqtt/irhub
payload: true
value_template: "{{ iif(value_json.learned_ir_timings, true, false) }}"
conditions: []
actions:
- action: button.press
metadata: {}
target:
entity_id: button.irhub_switch_learn_ir_code
data: {}
mode: single