# MQTT-Timer

Programmable Timer for MQTT messaging.

MQTT-Timer is a flexible timer service for scheduling and automating tasks. It allows you to set up timers for any task, from turning on lights to running a script. Because it is based on the MQTT protocol can it be easily be integrated with other home automation systems. It also provides a range of features such as customizable time intervals, random timers, sunrise/sunset timers and logging.

In a MQTT-based home automation environment, a timer independent from home control software like Node-Red or Home Assistant can significantly improve the stability of the system. Adhering to the Unix/Linux philosophy of "do one thing, and do it well," this timer will continue to send messages at the specified times, even if node-red or other home control software crashes. This ensures that the system remains reliable and consistent, even in the event of an unexpected interruption.

Installation

MQTT-Timer can be used in a Go environment or as a Docker container:

$ go get -u github.com/Legobas/mqtt-timer

Environment variables

Supported environment variables:

LOGLEVEL = INFO/DEBUG/ERROR

Configuration

MQTT-Timer can be configured with the mqtt-timer.yml yaml configuration file. The mqtt-timer.yml file has to exist in one of the following locations:

• A config directory in de filesystem root: /config/mqtt-timer.yml
• A .config directory in the user home directory ~/.config/mqtt-timer.yml
• The current working directory

Configuration options

Example mqtt-timer.yml:

    latitude: 51.50722
    longitude: -0.1275

    mqtt:
      url: "tcp://<MQTT SERVER>:1883"
      username: <MQTT USERNAME>
      password: <MQTT PASSWORD>
      qos: 0
      retain: false

    timers:
    - id: 001
      time: 22:30
      description: Light outside on at 22:30
      topic: shellies/Shelly1/relay/0/command
      message: on
    - id: 002
      time: sunrise
      before: 20 minutes
      description: Light outside off 20 minutes before sunrise
      topic: shellies/Shelly1/relay/0/command
      message: off

See also: Example mqtt-timer.yml

Programmable timers

Timers can be set by sending a MQTT JSON message to the topic:

MQTT-Timer/set

The following fields can be part of the JSON message:

examples:

{
  "id": "alarm01",
  "description": "Intruder detected",
  "interval": "1 sec",
  "until": "100 times",
  "topic": "/homeassistant/light02",
  "message": ["on", "off"]
}

{
  "id": "light01",
  "description": "Light on after 10 min.",
  "start": "10 min",
  "topic": "/homeassistant/light01",
  "message": "on",
}

{
  "id": "pulsating_dimmer",
  "description": "Dim light from 100% to 0% and back to 100% with 10 second steps from 10:15 to 10:20",
  "start": "10:15:00",
  "interval": "10 sec",
  "until": "10:20:00",
  "topic": "/homeassistant/light04/dimmer",
  "message": ["100%", "80%", "60%", "20%", "0%", "20%", "60%", "80%", "100%"]
}

Disable/Enable timers

Timers can be disabled or enabled by sending a JSON message with the enable field.

The MQTT topic for the disable/enable message is the same:

MQTT-Timer/set

The behavior if a message with enable: false is received:

• Configurable timers will be paused.
• Programmable timers will be removed from the scheduler.

The behavior if a message with enable: true is received:

• Configurable timers will be activated.
• Programmable timers won't change, an error message will be logged.

Besides the id field the enable field has to be the only field in the message.

The JSON message to disable or cancel a timer:

examples:

{
  "id": "light01",
  "enable": false
}

{
  "id": "light*",
  "enable": true
}

Docker

Docker run example:

$ docker run -d -v /home/legobas/mqtt-timer:/config legobas/mqtt-timer

Docker compose example:

version: "3.0"

services:
  MqttTimer:
    image: legobas/mqtt-timer:latest
    container_name: mqtt-timer
    environment:
      - LOGLEVEL=debug
      - TZ=America/New_York
    volumes:
      - /home/legobas/mqtt-timer:/config:ro
    restart: unless-stopped

Timezone

By default all the times will be in the timezone of the server. In a docker environment the timezone can be specified by the TZ environment variable.

For example:

$ docker run -e TZ=America/New_York mqtt-timer

Credits

• GoCron
• Paho Mqtt Client
• GoSunrise
• ZeroLog