MMM-GPIO-Notifications

MMM-GPIO-Notifications is a module for the MagicMirror project by Michael Teeuw.

It watches the state of configurable GPIO-Pins and sends configurable notifications (with optional payload) if the state of the pins change to the configured value. If you configure a delay no notifcations will be send for the pin after a successful trigger for this time. As a new feature you can now set profiles for each notifcation. Because of this you can use the same sensor for different actions in different profiles (i.e. different pages).

As of version 0.1.0 of the module it is possible to use rotary encoders, too. Instead of one pin, two pins get configured (one data and one clock pin) which work together.

As with version 0.2.0 of the module i needed to change to a different library and so the gpio_debounce option is no longer supported. Use the delay options instead!

If the module is unable to register a GPIO i.e. cause it is used by a other program it prints a message to the log now.

I wrote an english and an german tutorial on howto connect an HC-SR501 PIR sensor and use this module in combination with MMM-Screen-Powersave-Notifications to implement an auto-on/auto-off for the screen

Installation

Hint: The postinstallation will take some time. Please wait for it to finish! Hint: If you use the module in a container (i.e. docker) setup please skip this steps and make sure to look to the next section and then run these steps if the preconditions are met.

    cd ~/MagicMirror/modules
    git clone https://github.com/Tom-Hirschberger/MMM-GPIO-Notifications.git
    cd MMM-GPIO-Notifications
    ./preinstall
    npm install

Setup in a container

As of version 0.2.0 of the module you will need a container image which contains the "lipgpiod-dev" and "gpiod" package. The installation will fail if they are not present!

The image of karsten13 will contains with all releases after 2024-03-24. You will need the fat tag to install the module and run the converter script proberly.

If you want to use the module within a container it will need some preperation. First make sure python3 is available in the container. It is needed only during the installation (npm install) of the module but not during runtime.

If you use the container image of karsten13 you need to switch from the latest tag to the fat.

If you use docker-compose you will find a line:

image: karsten13/magicmirror:latest

in the `docker-compose.yml" file. Please change it to:

image: karsten13/magicmirror:fat

Next you will need to make sure that you map /dev and sys inside the container and run the container in privileged mode.

If you started the container without docker-compose simply add the following options to the command docker run command:

-v /dev:/dev -v /sys:/sys --privileged

It then will look something like:

docker run --privileged -it --rm --name mymirror \
 -v ${HOME}/mm/modules:/opt/magic_mirror/modules \
 -v ${HOME}/mm/config:/opt/magic_mirror/config \
 -v ${HOME}/mm/css:/opt/magic_mirror/css \
 -v /dev:/dev \
 -v /sys:/sys \
 -p 8080:8080 \
 karsten13/magicmirror:fat npm run server

In case you use docker-compose to start your mirror you need to add a additional volume and the privileged option to the docker-compose.yml. It then will look something like:

version: '3'

services:
  magicmirror:
    container_name: mm
    privileged: true
    image: karsten13/magicmirror:latest
    ports:
      - "8080:8080"
    volumes:
      - ../mounts/config:/opt/magic_mirror/config
      - ../mounts/modules:/opt/magic_mirror/modules
      - ../mounts/css:/opt/magic_mirror/css
      - /dev:/dev
      - /sys:/sys
    restart: unless-stopped
    command:
      - npm
      - run
      - server

Configuration

As of version 0.1.0 of the module rotary encoders can be used. The configuration is slightly different between single pins and the one for rotary encoders. Cause of this i will provide two examples in two sections of this readme.

General

• forceInfoFileUsage: If this option is set to true the gpioinfo.json file will be used instead of build in device information. If the registration of your pins fails although you are sure you configured the right ones you can try to change this option. Default: false

Single GPIO pin

To use the module insert it in the config.js file. Here is an example:

    {
        module: 'MMM-GPIO-Notifications',
        config: {
            '17': {
              delay: 1000,
              notifications_high: [
                {
                  notification: 'USER_PRESENCE',
                  payload: true
                },
                {
                  notification: 'SCREEN_ON',
                  payload: { 'forced': false }
                }
              ]
            },
            '4': {
              delay: 20,
              notifications_high: [
                {
                  notification: 'SCREEN_TOGGLE',
                  payload: { 'forced': true },
                  profiles: 'pageOneEveryone pageTwoEveryone'
                }
              ]
            }
        }
    },

There are two buttons configured in this example. As of version 0.0.8 of the module it is possible to send specific notifications for both states of the the pin. Instead of specifying gpio_state and notifications the two arrays notifications_low and notifications_high are used. In the example above both gpio pins cause notifications being send if high state is triggered.

As of version 0.0.9 of the module the old syntax using gpio_state and notifications is depcreated. Use notifications_low and notifications_high instead!

As of version 0.0.9 of the module it is possible to configure different delays depending on the state with the options delay_high and delay_low. If only delay is configured it will be used for both the high and the low state.

Rotary encoder

    {
        module: 'MMM-GPIO-Notifications',
        config: {
          '13': {
              delay: 500,
              notifications_high: [
                {
                  notification: 'SCREEN_TOGGLE',
                  payload: { 'forced': true }
                }
              ]
          },
          '6,5': {
            delay_cw: 100,
            delay_ccw: 200,
            rotaryDelay: 5,
            notifications_ccw: [
              {
                notification: 'PROFILE_INCREMENT_HORIZONTAL',
                payload: true,
              },
              {
                notification: 'TEST',
                payload: false,
                profiles: "pageC"
              }
            ],
            notifications_cw: [
              {
                notification: 'PROFILE_DECREMENT_HORIZONTAL',
                payload: true,
              }
            ],
          },
        }
    },

In this example a rotary encoder with the following options is configured:

• the switch pin of my rotary encoder is GPIO 13
• if the rotary encoder gets pressed my screen gets toggled by notification "SCREEN_TOGGLE"
• the data pin of the rotary encoder is GPIO 6
• the clock pin of the rotary encoder is GPIO 5
• notifications for clockwise direction will be send only after a delay of 100 milliseconds
• notifications for counterclockwise direction will be send only after a delay of 200 milliseconds
• my rotary encoder sometimes sends results twice within a short time when it is turned. So i set a small amount of 5 milliseconds as delay between two events
• if the rotary is turned counterclockwise two notifications are send: "PROFILE_INCREMENT_HORIZONTAL" and "TEST". But "TEST" is only send on my center profile "pageC"
• if the rotary is turned clockwise the notification "PROFILE_DECREMENT_HORIZONTAL" is send