MQTT Date/Time
The MQTT Date/Time integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to integrate devices that expose a control to set the date and time.
Configuration
To use an MQTT date/time entity in your installation, 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.
# Example configuration.yaml entry
mqtt:
- datetime:
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.
The MQTT topic to publish the date/time value that is set in ISO format (UTC timezone). Use the command_template option to render to a different format.
Use default_entity_id instead of name for automatic generation of the entity ID. For example, datetime.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 time 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 date/time state when a message is received on this topic.
The name of the date/time entity. Can be set to null if only the device name is relevant.
Must be datetime. 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 date/time state updates. Date state updates should contain a parsable date string, e.a. ‘2025-12-01’ or ‘1 March 2025’. If a time structure is passed, the current date will be will be used. Can be used with value_template to render the incoming payload to a parsable date/time string expression. The expression must include a timezone, but must be omitted if the timezone option is set. If needed, the value_template option can be used to define a template that renders to a valid date/time structure.
Set to a valid IANA timezone identifier. Do not set this option if the data/time structure is providing timezone information via the status update.
An ID that uniquely identifies this date/time entity. If two date/time entities have the same unique ID Home Assistant will raise an exception. Required when used with device-based discovery.
Make sure that your topic matches exactly. some-topic/ and some-topic are different topics.
Examples
This is an example of a manual configured MQTT datetime item.
# Example configuration.yaml entry
mqtt:
- datetime:
name: "Scheduled task"
icon: mdi:ab-testing
command_topic: "date_selector/set"
state_topic: "date_selector/state"