MMM-GPIO-HANDLER

MagicMirror² module to handle GPIO Input and Output, including PWM functions.

Maintained

This module works and is currently maintained. Any suggestions/improvements are welcome.

Contents

• Concept / Background
• Dependencies
• Installation
• Configuration
  • Example Configuration
  • Module Configuration
  • Input Configuration
  • Output Configuration
• Usage
  • Input usage
  • Buttons
  • PIR
  • Other
  • Output usage
  • HANDLE_ON/OFF notification payload
  • HANDLE_PWM notification payload
• Credits

Concept / Background

While building my Mirror, I could not find a module that supports PWM (Pulse Width Modulation) and/or handles GPIO as a whole (input & output). The Mirror had LEDs and LED strips installed according to this instruction (with MOSFETs). Though the instructions do not mention PWM explicitly, the concept uses Software PWM.

This module supports:

• Both Hardware and Software PWM and some PWM effects, mostly optimized for LEDs. (Breath, Pulse, Flash, Fade-in, Fade-out).
• On/off handling of outputs (1/0 state, not using PWM).
• Input handling of buttons (short & long press), PIR, Other.

The module sends a Notification if an input is changed, which can be used to start actions in other modules. The module starts output handling from defaults set or when a HANDLE_PWM or HANDLE_ON/OFF notification is received. Payload in notification sets the options.

Dependencies

The module depends on the use of the socket interface of the pigpio library. It works by launching the pigpio Daemon and exposing the socket interface. The pigpiod utility requires sudo privileges to launch the library but thereafter the socket commands may be issued by normal users (e.g., MagicMirror).

On Raspbian/Raspberry Pi OS, these utilities are normally already installed. To check, you can run

pigpiod -v

It will show the version if it is installed.

If not installed on Raspbian/Raspberry Pi OS, you can run:

sudo apt-get update
sudo apt-get install pigpio

On other OS, if the above does not work, or if, for some reason, the latest version of the package is not installed and you need the latest package, you'll need the build-essential package:

sudo apt-get install build-essential

Next, run the following shell commands:

rm master.zip
sudo rm -rf pigpio-master
wget https://github.com/joan2937/pigpio/archive/master.zip
unzip master.zip
cd pigpio-master
make
sudo make install

Additionally, the pigpio-client is installed from dependencies to expose the socket interface APIs to JavaScript using Node.js.

Lastly, the module sends alerts in some cases. For this, the default module Alert should be configured.

Installation

Clone this repository into your modules folder, and install dependencies:

cd ~/MagicMirror/modules # adapt directory if you are using a different one
git clone https://github.com/Sjohn21/MMM-GPIO-HANDLER.git
cd MMM-GPIO-HANDLER
npm install

Configuration

To configure this module, add it to your modules array in your config.js. The full list of configurable options can be found in Module Configuration.

Example Configuration

Below is a simple example with two buttons connected to pins 24 & 25. One button has an internal pull-up resistor, and the other has an internal pull-down resistor active. More information about pull-up and pull-down resistors can be found here, There is also a PIR sensor connected to pin 14 with a pull-up resistor and an unspecified/other sensor on pin 8 as inputs. The example includes the definition of 5 outputs:

1. A (software) PWM output with a fixed state (250000) for dutyCycle on pin 4.
2. A hardwarePWM output with an effect of type Pulse, using a speed of 50ms between changes and in 50 steps (of complete dutyCycle) on pin 12.
3. An On/Off output with a default state of 1 on pin 15.
4. An On/Off output with a default state of 0 on pin 10.
5. A (software) PWM output with an effect of type Breath, using a speed of 50ms between changes and in 10 steps, within a certain bandwidth of dutyCycle between a minimum of 20% and a maximum of 80% of dutyCycle.

   {
   module: "MMM-GPIO-HANDLER",
   config: {
       debounce: 10000,
       longPressTime: 500000,
       longPressTimeOut: 3000000,
       input: {
           "24": {
               type: "Button",
               name: "Button 1",
               pull: "PUD_DOWN"
           },
           "25": {
               type: "Button",
               name: "Button 2",
               pull: "PUD_UP"
           },
           "14": {
               type: "PIR",
               name: "Pir Sensor",
               pull: "PUD_DOWN"                
           },
           "8": {
               type: "Other",
               name: "Other type of Sensor"        
           }
       },
       output: {
           "4": {
               type: "PWM",
               name: "Ledstrip FET cool",
               default_PWM_effect: "Fixed",
               default_PWM_state: 250000
           },
           "12": {
               type: "hardwarePWM",
               name: "Button 8 LED FET",
               default_PWM_effect: "Pulse",
               default_PWM_speed: 50,
               default_PWM_steps: 50
           },
           "15": {
               type: "On/Off",
               name: "Display K0",
               default_state: 1
           },
           "10": {
               type: "On/Off",
               name: "Relay CH1",
               default_state: 0
           },
           "17": {
               type: "PWM",
               name: "Button 7 LED FET",
               default_PWM_effect: "Breath",
               default_PWM_speed: 50,
               default_PWM_steps: 10,
               default_PWM_upperLimitDCP: 80,
               default_PWM_lowerLimitDCP: 20
           }
       }
   }
   },

   Module Configuration

   See below table for all options for the global module configuration. Some of them can be set globally and/or per output, see Output Configuration:

Input Configuration

See below table for all options for configuring input pins.
Each pin configuration goes in their own object, within the input object.

Output Configuration

See below table for all options for configuring output pins.
Each pin configuration goes in their own object, within the output object. Configuration in the pin object overwrites the system defaults for that pin.

Usage

The module needs to have the Pigpio Daemon running.
Before running Magic Mirror start the Daemon using the following command:

sudo pigpiod -l

If Pm2 is used start autostart Magic Mirror mm.sh (or whatever the bash script is called) can be adjusted by adding one line:

cd ./MagicMirror
sudo pigpiod -l # add this line here
DISPLAY=:0 npm start

Input usage

Once all inputs are configured, the module will monitor them. When triggered, the module will send notifications to other modules. Another module can then perform actions based on these notifications. The human-readable name will be converted to a system name in all uppercase, with spaces replaced by underscores.

Buttons

The pull can be set as per Input Configuration. If the Pull is set to PUD_UP and the level (3.3v) changes to 0, the notification will trigger. Similarly, when the Pull is set to PUD_DOWN or not set, and the level (3.3v) changes to 1, the notification will trigger.
If the button is held longer than longPressTime, a long press notification will be sent. If the button is held shorter than this time, a short press notification will be sent. If the button is held longer than longPressTimeOut, a long-press notification will be sent at longPressTimeOut nonetheless, and an alert will be sent to notify the user if the button might be stuck.
Notifications are formatted as: <<systemname>>_LONG_PRESSED and <<systemname>>_SHORT_PRESSED.
For example, if the Button is named Button 1, the notifications will be BUTTON_1_LONG_PRESSED and BUTTON_1_SHORT_PRESSED.

PIR

The pull can be set as per Input Configuration. If the Pull is set to PUD_UP and the level (3.3v) changes to 0, the detection notification will trigger. Similarly, when the Pull is set to PUD_DOWN or not set and the level (3.3v) changes to 1, the detection notification will trigger. A no detection notification will trigger when the level changes the other way around.
Notifications are formatted as: <<systemname>>_DETECTION and <<systemname>>_NO_DETECTION.
For example, if the PIR sensor is named Pir Sensor, the notifications will be PIR_SENSOR_DETECTION and PIR_SENSOR_NO_DETECTION.

Other

If something other than a button or PIR is connected, the other option can be used. When the level (3.3v) changes to 1, a high notification will be sent. When the level (3.3v) changes to 0, a low notification will be sent. When the level (3.3v) changes to something else, a floating notification will be sent.
otifications are formatted as: <<systemname>>_HIGH, <<systemname>>_LOW and <<systemname>>_FLOATING.
For example, if the sensor is named Other type of Sensor, the notifications will be OTHER_TYPE_OF_SENSOR_HIGH, OTHER_TYPE_OF_SENSOR_LOW and OTHER_TYPE_OF_SENSOR_FLOATING.

Output usage

Once all outputs are configured, the defaults set on the outputs will run when the module is started. For example, if globally default_PWM_cycles is set to 10 cycles and pin 17 is configured as:

"17": {
    type: "PWM",
    name: "Button 7 LED FET",
    default_PWM_effect: "Breath",
    default_PWM_speed: 50,
    default_PWM_steps: 10,
    default_PWM_upperLimitDCP: 80,
    default_PWM_lowerLimitDCP: 20
}

the LED (in this case, a LED on a button) will run the the Breath effect with a changing speed of 50 and in 10 steps between a max dutyCycle of 80 percent and a min dutyCycle of 20 percent.

Additionally, outputs can be changed by notifications. The HANDLE_PWM and HANDLE_ON/OFF notification are read by the module, and a payload sets the options. See the next paragraphs for details.

HANDLE_ON/OFF notification payload

The HANDLE_ON/OFF notification should be accompanied by an object in the payload. The object options are:

The set action sets the output pin to the given state. The toggle action changes the state; if it was 0, it will be set to 1, and vice versa. The trigger action sends a short pulse of level for length microseconds.

Examples of payload:

{
    "pin" : 10,
    "action" : "set",
    "state" : 1
}

and

{
    "pin" : 10,
    "action" : "trigger",
    "level" : 1,
    "length" : 100000  //0.1 second
}

HANDLE_PWM notification payload

The HANDLE_PWM notification should be accompanied by an object in the payload. The object options are:

Example payload:

{
    "pin" : 17,
    "pwmEffect" : "Pulse",
    "pwmSpeed" : 50,
    "pwmSteps" : 15,
    "pwmUpperLimitDCP" : 85,
    "pwmLowerLimitDCP" : 10,
    "pwmStart" : "high",
    "pwmCycles" : 15,
    "pwmEnd" : "low"
}

Credits

• Michael Teeuw for MagicMirror2
• Guy McSwain for pigpio-client
• Joan for Pigpio & Pigpiod