MagTag MQTT Stopwatch

Display how much time has elapsed between a timestamp fetched from an MQTT broker and the current time. The current time is also fetched from an MQTT broker so that a real-time clock is not needed on the MagTag e-ink display device.

Quickstart

1. Clone this repository and its Git submodules:

    git clone https://github.com/garrettheath4/magtag-mqtt-timeago.git
    cd magtag-mqtt-timeago/
    git submodule init && git submodule update
   

2. Plug in MagTag to your computer with a USB-C cable and turn the physical switch on it to the On position. A flash-drive-like file storage device called CIRCUITPY should automatically mount.

3. Run make to copy the code and required libraries from this repository to the CIRCUITPY drive.

4. Create a secrets.py file inside the CIRCUITPY drive with the following contents:

    # This file is where you keep secret settings, passwords, and tokens!
    # If you put them in the code you risk committing that info or sharing it
   
    secrets = {
        'ssid': 'myWifiNetworkName',
        'password': 'myWifiPassword',
        'timezone': "America/New_York",  # http://worldtimeapi.org/timezones
        'broker': '192.168.0.50',  # IP or hostname of MQTT server
        'port': 1883,  # MQTT port, default: 1833
        'topic_past': 'dogs/last_time_out',
        'topic_now': 'time/now',
        # minutes between each screen refresh; optional (default 1)
        'refresh_mins': 1,
        # front LEDs will turn ON if stopwatch is over this many minutes; optional (default always off)
        'leds_on_mins_threshold': 120,
        # front LEDs will never turn on before this hour of the day (0 to 23); optional (default no "off" hours)
        'leds_always_off_before_hour': 8,
    }
   

5. Wait for the MagTag to restart and the code will run automatically.

Requirements

• Adafruit MagTag 2.9" E-Ink WiFi Display
• MQTT broker server such as Eclipse Mosquitto
  • Example: running on a Raspberry Pi or in a Docker container running on an unRAID server on your network

Home Assistant (Optional)

You can run Home Assistant on a Raspberry Pi or in a Docker container running on an unRAID server on your network. A Home Assistant server is optional but recommended since it provides:

1. an easy way to automatically publish the current time to a "now" topic on an MQTT broker
2. an easy way to configure a smart button to "reset" the timer by publishing the current time to a "past" topic on an MQTT broker

MQTT Current Time Automation

Add this Automation to your Home Assistant to publish the current time to the time/now MQTT topic every minute:

alias: MQTT Current Time
description: Publish the current time to MQTT every minute
trigger:
  - platform: time_pattern
    minutes: '*'
condition: []
action:
  - service: mqtt.publish
    data:
      topic: time/now
      retain: true
      qos: '1'
      payload_template: '{{ now().isoformat() }}'
mode: single

Be sure to configure the MQTT integration on your Home Assistant server first.

Reset Timer with Smart Button Automation

Add this Automation to your Home Assistant to publish the current time to the dogs/last_time_out MQTT topic every time you press a smart button:

alias: Reset Dog Timer
description: ''
trigger:
  - device_id: b46f5fe1a48dae52a61ba4c47a06789f
    domain: zha
    platform: device
    type: remote_button_short_press
    subtype: turn_off
condition: []
action:
  - service: mqtt.publish
    data:
      topic: dogs/last_time_out
      retain: true
      qos: '1'
      payload_template: '{{ now().isoformat() }}'
mode: single

You can use any Zigbee button that is compatible with ZHA for Home Assistant for this. It has been tested using an Ikea Trådfri on/off switch.