{"id":18602907,"url":"https://github.com/legobas/mqtt-timer","last_synced_at":"2025-04-10T19:31:15.746Z","repository":{"id":151791837,"uuid":"606102063","full_name":"Legobas/mqtt-timer","owner":"Legobas","description":"Programmable Timer/Scheduler for MQTT","archived":false,"fork":false,"pushed_at":"2025-02-25T19:47:59.000Z","size":117,"stargazers_count":16,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T10:42:45.221Z","etag":null,"topics":["automation","gocron","home-automation","iot","iot-scheduling","mqtt","mqtt-smarthome","scheduler","smarthome","time-scheduler","timer"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/legobas/mqtt-timer","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Legobas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-24T15:51:10.000Z","updated_at":"2025-02-25T19:47:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"4dd047cc-6120-4648-b826-debc86a666ba","html_url":"https://github.com/Legobas/mqtt-timer","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Legobas%2Fmqtt-timer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Legobas%2Fmqtt-timer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Legobas%2Fmqtt-timer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Legobas%2Fmqtt-timer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Legobas","download_url":"https://codeload.github.com/Legobas/mqtt-timer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248281395,"owners_count":21077423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","gocron","home-automation","iot","iot-scheduling","mqtt","mqtt-smarthome","scheduler","smarthome","time-scheduler","timer"],"created_at":"2024-11-07T02:12:50.659Z","updated_at":"2025-04-10T19:31:13.326Z","avatar_url":"https://github.com/Legobas.png","language":"Go","readme":"# MQTT-Timer\n\nProgrammable Timer for MQTT messaging.\n\n[![mqtt-smarthome](https://img.shields.io/badge/mqtt-smarthome-blue.svg?style=flat-square)](https://github.com/mqtt-smarthome/mqtt-smarthome)\n[![Build/Test](https://github.com/Legobas/mqtt-timer/actions/workflows/release.yml/badge.svg)](https://github.com/Legobas/mqtt-timer/actions/workflows/release.yml)\n[![CodeQL](https://github.com/Legobas/mqtt-timer/actions/workflows/codeql.yml/badge.svg)](https://github.com/Legobas/mqtt-timer/actions/workflows/codeql.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Legobas/mqtt-timer)](https://goreportcard.com/report/github.com/legobas/mqtt-timer)\n[![Docker Pulls](https://badgen.net/docker/pulls/legobas/mqtt-timer?icon=docker\u0026label=pulls)](https://hub.docker.com/r/legobas/mqtt-timer)\n[![Docker Image Size](https://badgen.net/docker/size/legobas/mqtt-timer?icon=docker\u0026label=image%20size)](https://hub.docker.com/r/legobas/mqtt-timer)\n\nMQTT-Timer is a flexible timer service for scheduling and automating tasks.\nIt allows you to set up timers for any task, from turning on lights to running a script.\nBecause it is based on the MQTT protocol can it be easily be integrated with other home automation systems. \nIt also provides a range of features such as customizable time intervals, random timers, sunrise/sunset timers and logging.\n\nIn 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.\nAdhering to the Unix/Linux philosophy of \"do one thing, and do it well,\" this timer will continue to send messages at the specified times, \neven if node-red or other home control software crashes. \nThis ensures that the system remains reliable and consistent, even in the event of an unexpected interruption.\n\n## Installation\n\nMQTT-Timer can be used in a [Go](https://go.dev) environment or as a [Docker container](#docker):\n\n```bash\n$ go get -u github.com/Legobas/mqtt-timer\n```\n\n## Environment variables\n\nSupported environment variables:\n\n```\nLOGLEVEL = INFO/DEBUG/ERROR\n```\n\n# Configuration\n\nMQTT-Timer can be configured with the `mqtt-timer.yml` yaml configuration file.\nThe `mqtt-timer.yml` file has to exist in one of the following locations:\n\n * A `config` directory in de filesystem root: `/config/mqtt-timer.yml`\n * A `.config` directory in the user home directory `~/.config/mqtt-timer.yml`\n * The current working directory\n\n## Configuration options\n\n| Config item               | Description                                                              |\n| ------------------------- | ------------------------------------------------------------------------ |\n| latitude/longitude        | GPS location used for Sunrise/Sunset                                     |\n| **mqtt**                  |                                                                          |\n| url                       | MQTT Server URL                                                          |\n| username/password         | MQTT Server Credentials                                                  |\n| qos                       | MQTT Server Quality Of Service                                           |\n| retain                    | MQTT Server Retain messages                                              |\n| **timers**                |                                                                          |\n| id                        | Unique ID for this timer (mandatory)                                     |\n| time                      | Time in `15:04` or `15:04:05` format                                     |\n|                           | `sunrise` or `sunset`                                                    |\n| cron                      | Cron expression in `30 7 * * *` or `15 30 7 * * *` (with seconds) format |\n| description               | something useful                                                         |\n| topic                     | MQTT Topic                                                               |\n| message                   | string --\u003e  message: `on`                                                |\n|                           | JSON --\u003e message: `'{\"device\"=\"light1\", \"command\"=\"on\"}'`                |\n| before, after             | offset: fixed duration in `25 sec`,`12 min` or `1 hour` format           |\n| randomBefore, randomAfter | offset: random duration in `25 sec`,`12 min` or `1 hour` format          |\n| enabled                   | true (default), false                                                    |\n\nExample mqtt-timer.yml:\n\n```yml\n    latitude: 51.50722\n    longitude: -0.1275\n    \n    mqtt:\n      url: \"tcp://\u003cMQTT SERVER\u003e:1883\"\n      username: \u003cMQTT USERNAME\u003e\n      password: \u003cMQTT PASSWORD\u003e\n      qos: 0\n      retain: false\n      \n    timers:\n    - id: 001\n      time: 22:30\n      description: Light outside on at 22:30\n      topic: shellies/Shelly1/relay/0/command\n      message: on\n    - id: 002\n      time: sunrise\n      before: 20 minutes\n      description: Light outside off 20 minutes before sunrise\n      topic: shellies/Shelly1/relay/0/command\n      message: off\n```\n\nSee also: [Example mqtt-timer.yml](https://github.com/Legobas/mqtt-timer/blob/main/mqtt-timer.yml)\n\n## Programmable timers\n\nTimers can be set by sending a MQTT JSON message to the topic:\n\n    MQTT-Timer/set\n\nThe following fields can be part of the JSON message:\n \n| Field       | Description                                                 | Default                        |\n| ----------- | ----------------------------------------------------------- | ------------------------------ |\n| id          | unique ID for this message (mandatory)                      |                                |\n| description | something useful                                            |                                |\n| start       | after: duration in `25 sec`,`12 min` or `1 hour` format     | immediately                    |\n|             | at: time in `15:04` or `15:04:05` format                    |                                |\n| interval    | duration in `25 sec`,`12 min` or `1 hour` format            | 30 seconds                     |\n| until       | number of times in `10 times` or `10` format                | 1 time                         |\n|             | duration in `25 sec`,`12 min` or `1 hour` format            |                                |\n|             | time in `15:04` or `15:04:05` format                        |                                |\n| topic       | MQTT Topic                                                  | `MQTT-Timer/timers/\u003cid\u003e/event` |\n| message     | MQTT Message --\u003e  \"message\": `\"on\"`                         | id                             |\n|             | JSON --\u003e \"message\": `\"{'device'='light1', 'command'='on'}\"` |                                |\n|             | JSON Array --\u003e \"message\": `[\"green\", \"red\", \"blue\"]`        |                                |\n\nexamples:\n\n```json\n{\n  \"id\": \"alarm01\",\n  \"description\": \"Intruder detected\",\n  \"interval\": \"1 sec\",\n  \"until\": \"100 times\",\n  \"topic\": \"/homeassistant/light02\",\n  \"message\": [\"on\", \"off\"]\n}\n```\n\n```json\n{\n  \"id\": \"light01\",\n  \"description\": \"Light on after 10 min.\",\n  \"start\": \"10 min\",\n  \"topic\": \"/homeassistant/light01\",\n  \"message\": \"on\",\n}\n```\n\n```json\n{\n  \"id\": \"pulsating_dimmer\",\n  \"description\": \"Dim light from 100% to 0% and back to 100% with 10 second steps from 10:15 to 10:20\",\n  \"start\": \"10:15:00\",\n  \"interval\": \"10 sec\",\n  \"until\": \"10:20:00\",\n  \"topic\": \"/homeassistant/light04/dimmer\",\n  \"message\": [\"100%\", \"80%\", \"60%\", \"20%\", \"0%\", \"20%\", \"60%\", \"80%\", \"100%\"]\n}\n```\n\n### Disable/Enable timers\n\nTimers can be disabled or enabled by sending a JSON message with the `enable` field.\n\nThe MQTT topic for the disable/enable message is the same:\n\n    MQTT-Timer/set\n\nThe behavior if a message with `enable: false` is received:\n* Configurable timers will be paused.\n* Programmable timers will be removed from the scheduler.\n\nThe behavior if a message with `enable: true` is received:\n* Configurable timers will be activated.\n* Programmable timers won't change, an error message will be logged.\n\nBesides the `id` field the `enable` field has to be the only field in the message.\n\nThe JSON message to disable or cancel a timer:\n\n| Field  | Description                                                              |\n| ------ | ------------------------------------------------------------------------ |\n| id     | unique ID for this message (mandatory)                                   |\n|        | wildcard: `lamp_*` will enable/disable every timer starting with \"lamp_\" |\n| enable | true or false                                                            |\n|        | true (re-enable) can only be used for configurable timers                |\n\nexamples:\n\n```json\n{\n  \"id\": \"light01\",\n  \"enable\": false\n}\n```\n\n```json\n{\n  \"id\": \"light*\",\n  \"enable\": true\n}\n```\n\n## Docker\n\nDocker run example:\n\n```bash\n$ docker run -d -v /home/legobas/mqtt-timer:/config legobas/mqtt-timer\n```\n\nDocker compose example:\n\n```yml\nversion: \"3.0\"\n\nservices:\n  MqttTimer:\n    image: legobas/mqtt-timer:latest\n    container_name: mqtt-timer\n    environment:\n      - LOGLEVEL=debug\n      - TZ=America/New_York\n    volumes:\n      - /home/legobas/mqtt-timer:/config:ro\n    restart: unless-stopped\n```\n\n## Timezone\n\nBy default all the times will be in the timezone of the server.\nIn a docker environment the timezone can be specified by the TZ environment variable.\n\nFor example: \n\n```bash\n$ docker run -e TZ=America/New_York mqtt-timer\n```\n\n## Credits\n\n* [GoCron](https://github.com/go-co-op/gocron)\n* [Paho Mqtt Client](https://github.com/eclipse/paho.mqtt.golang)\n* [GoSunrise](https://github.com/nathan-osman/go-sunrise)\n* [ZeroLog](https://github.com/rs/zerolog)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flegobas%2Fmqtt-timer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flegobas%2Fmqtt-timer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flegobas%2Fmqtt-timer/lists"}