Bee-Mar/MMM-Simple-Swiper

A simple, multi-threaded interface for the HC-SR04 sensors and the MagicMirror

MMM-Simple-Swiper

Author	Contact
Brandon Marlowe	bpmarlowe-software@protonmail.com
Otto Juba	ottojuba@gmail.com

What is this, and why did we make this module?

This module attempts to determine distance/motion based on the output from the sensors in a simple, efficient manner. When the MMM-Simple-Swiper modules loads, it sends a socket notification to node_helper.js. The node_helper then creates a child process, which calls a C executable, and supplies the JSON config as a command line argument in string format. The JSON string is parsed, the values are stored in structs, and an infinite loop is entered. Within the inifinte loop, two threads are created to collect the distance measurements, remove the outliers, and calculate the average distance. The two threads are joined, and the averages are printed to stdout in a [FLOAT]:[FLOAT] format, which is read by the child process created in node_helper.js. From here, the values are checked to see if both are within a certain threshold. If the values meet this criteria and there is a large enough difference between the two values, a socket nofication is sent to the MMM-Simple-Swiper module, which sends a notification to the MMM-pages module.

Dependencies

This module has three dependencies, all of which are listed in the table below. When you clone this repo, install the wiringPi library using the instructions from the table below, and run and npm install inside repo’s directory.

Library Dependencies	Link/Installation
WiringPi	sudo apt-get install wiringpi -y
child_process	https://nodejs.org/api/child_process.html
electron-rebuild	https://github.com/electron/electron-rebuild
Recommended MagicMirror Modules	Link
MMM-pages	https://github.com/edward-shen/MMM-pages
MMM-page-indicator	https://github.com/edward-shen/MMM-page-indicator

Installation

You can either follow the manual instructions for installation below, or you can make use of the MMPM (Magic Mirror Package Manager) found here: https://github.com/Bee-Mar/mmpm

# assuming mmpm is already installed

$ sudo apt-get install wiringpi -y
$ mmpm -i MMM-Simple-Swiper
$ cd ~/MagicMirror/modules/MMM-Simple-Swiper && make

# manual installation
$ cd ~/MagicMirror/modules/
$ https://github.com/Bee-Mar/MMM-Simple-Swiper.git
$ cd MMM-Simple-Swiper
$ sudo apt-get install wiringpi -y
$ npm install
$ make

Be sure to add the snippet for your config.js file below.

SuDON’T

When running this module, there is absolutely no need to execute sudo with npm start. This is due to the small hack (I guess it can be considered a hack??) used when launching the child process within node_helper.js. The code snippet where this occurs is shown below:

// other code above ...

var child = require("child_process").spawn("sudo", [
   __dirname + "/swiper",
   JSON.stringify(payload),
]);

// other code below ...

Notice the first argument of the spawn function being sudo, which takes care of the permissions required for the GPIO pins. We show you this in an attempt to be transparent, and asure you no funny business is taking place.

Raspberry Pi Pin Layout Reference

• Source: https://www.jameco.com/Jameco/workshop/circuitnotes/raspberry_pi_circuit_note_fig2a.jpg

Wiring the Sensors

• Source: https://github.com/mochman/MMM-Swipe (shamelessly lifted)

How we wired ours

• IMPORTANT: Do not forget to add a resistor to the Echo wire. Refer to the diagram above.

Config

The default config is shown below, and the order in which the values are listed are not important. Feel free to tweak the values to your needs. Also, please read the Tested Conditions/Warning section below.

// other module configs ...

   module: "MMM-Simple-Swiper",
   disabled: false,
   config: {
       echoLeftPin: 24, // GPIO #
       triggerLeftPin: 23, // GPIO #
       echoRightPin: 26, // GPIO #
       triggerRightPin: 25, // GPIO #
       threshold: 175, // in centimeters
       distanceDiff: 1.25, // difference between both sensors
       debug: false, // if true, the raw data is printed to stdout while MagicMirror is running
       magicMirrorDelay: 1000, // number of milliseconds between passing data from C executable to the node_helper for MagicMirror to act upon
       sensorDelay: 10, // the number of microseconds each sensor waits to check for changes in voltage (fine tune this for CPU performance)
   }

// other module configs ...

MMM-pages

When using with MMM-pages, place MMM-Simple-Swiper within the fixed property. The fixed property contains the list of modules which are fixed in place (as the name would suggest).

Just so it’s more clear, here’s the example config taken from the MMM-pages Github, with our module tucked nicely inside the fixed section.

modules: [
  {
    module: 'MMM-pages',
    config: {
      modules: [
        [ "weatherforecast", "newsfeed"],
        [ "calendar", "compliments" ]
      ],

      fixed: [
        "clock",
        "currentweather",
        "MMM-page-indicator",
        "MMM-Simple-Swiper"
      ],

    }
  }
]

Tested Conditions/Warning

This has only been tested on the RaspberryPi 3 B using Raspbian (based on Debian Stretch), using two HC-SR04 ultra sonic sensors. This module was intended to be run along side MMM-pages and MMM-page-indicator, and has done so very well in our testing. Also, since the C executable outputs raw values from the sensors, if you wanted to take the code and utilize it in another project, please, feel free. In fact, you’re encouraged to do so.

While messing around with the delay parameter of the config in the MMM-Simple-Swiper file, we did notice that anything less than 600 milliseconds can cause the entire module to hang after running for approximately 30 seconds. We haven’t figured out exactly why, but we suspect it has to do with too much throughput, and the child process not being able to read the data from stdout fast enough. Additionally, attempting to cover the sensors or swiping across the sensors rapidly can cause the module to lock up. We are actively looking into this issue, but, if you can exercise patience, and swipe through your pages at a moderate pace, you will not experience this issue.

If you notice any bugs, please let us know, and we’ll do our best to correct them.

Side note, I’m sure you noticed we abused the use of the special tags… Well, we like how it looks.

Future Work

We intend to add more options that can be tweaked from the config.js, such as:

• being able to change the direction in which pages slide (ie. left-to-right or right-to-left)
• adjusting the number of samples the sensors use for determining motion

If you have any suggestions that would be cool, or useful, feel free to email us!

Performance Demonstration

./videos/MMM-Simple-Swiper-Demo.mp4

Step-By-Step Instructions

Screencasted Video of Installation

./videos/MMM-Simple-Swiper-Installation.mp4

Before getting started…

1. The demo installation was done on a Raspberry Pi 3 B running Raspbian
   • The board was BRAND NEW and the OS was FRESHLY installed
   • The installation occurred after the initial boot and initial update
     • Remote GPIO and SSH were enabled under raspi-config
     • (You can enable them as well, if you would like to by following below)
       1. Open a terminal window
       2. run sudo raspi-config
       3. select Interfacing Options, select SSH; select <YES> to enable
       4. Also within Interfacing Options; select Remote GPIO; select <YES> to enable
     • I created SSH keys & copied them to my laptop (for easier SSHing)
       • For information on how to do this, see: https://www.ssh.com/ssh/keygen/
     • Otherwise, nothing else beyond what is shown was installed or removed
2. I used my laptop to SSH into the Pi and record the installation
   • The Pi cannot handle screen recording + installation of MagicMirror very well
3. All of these steps can be replicated directly from the Raspberry Pi 3 B in a terminal
4. There were no steps skipped throughout the video
5. Instructions for the Required Packages are from the relevant Github pages
6. The Required Packages are the BARE MINIMUM to get this working
7. NOTE: Within the Basic config.js containing required modules
   • There are default modules, which can be removed, if desired (see comments within file)

Required Magic Mirror Modules

NodeJS (10.15 or higher)

# taken from: https://github.com/MichMich/MagicMirror

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -

sudo apt install nodejs -y

MagicMirror

cd ~/

git clone https://github.com/MichMich/MagicMirror

cd ~/MagicMirror

npm install

# for the moment, don’t start the MagicMirror

MMM-pages

cd ~/MagicMirror/modules/

git clone https://github.com/edward-shen/MMM-pages.git

cd ~/MagicMirror/modules/MMM-pages

npm install

MMM-page-indicator

cd ~/MagicMirror/modules/

git clone https://github.com/edward-shen/MMM-page-indicator.git

# this module has no package.json, so "npm install" is not needed

MMM-Simple-Swiper

cd ~/MagicMirror/modules

git clone https://github.com/Bee-Mar/MMM-Simple-Swiper.git

cd ~/MagicMirror/modules/MMM-Simple-Swiper

# ONLY DO THIS IF YOU DON’T ALREADY HAVE A CONFIG SETUP
cp sample-config-file/SAMPLE_CONFIG.js ~/MagicMirror/config/config.js
# otherwise, simply examine the file, and see what is required

# installing dependencies and compile executable
make build_depends && make

# OPTIONAL: To test the module, follow below
cd ~/MagicMirror/modules/MMM-Simple-Swiper/

make clean && make debug

sudo ./swiper "{echoLeftPin: 24, triggerLeftPin: 23, echoRightPin: 26, triggerRightPin: 25, threshold: 175, distanceDiff: 1.25, debug: false, delay: 750, }"

# if the executable compiled correctly, then you should see values being output to the screen

# after running "make debug", recompile to build normal executable
make clean && make

Basic config.js containing required modules

/* Magic Mirror Config Sample
 *
 * By Michael Teeuw http://michaelteeuw.nl
 * MIT Licensed.
 *
 * For more information how you can configurate this file
 * See https://github.com/MichMich/MagicMirror#configuration
 *
 */

var config = {
  address: "localhost", // Address to listen on, can be:
  // - "localhost", "127.0.0.1", "::1" to listen on loopback interface
  // - another specific IPv4/6 to listen on a specific interface
  // - "", "0.0.0.0", "::" to listen on any interface
  // Default, when address config is left out, is "localhost"
  port: 8080,
  ipWhitelist: ["127.0.0.1", "::ffff:127.0.0.1", "::1"], // Set [] to allow all IP addresses
  // or add a specific IPv4 of 192.168.1.5 :
  // ["127.0.0.1", "::ffff:127.0.0.1", "::1", "::ffff:192.168.1.5"],
  // or IPv4 range of 192.168.3.0 --> 192.168.3.15 use CIDR format :
  // ["127.0.0.1", "::ffff:127.0.0.1", "::1", "::ffff:192.168.3.0/28"],

  language: "en",
  timeFormat: 24,
  units: "metric",

  modules: [
    {
      module: "MMM-pages", // REQUIRED
      config: {
        modules: [
          [
            "weatherforecast", // feel free to remove or swap out
            "newsfeed", // feel free to remove or swap out
          ],
          [
            "calendar", // feel free to remove or swap out
            "compliments", // feel free to remove or swap out
          ],
        ],
        fixed: [
          "clock", // feel free to remove or swap out
          "currentweather", // feel free to remove or swap out
          "MMM-page-indicator", // REQUIRED
          "MMM-Simple-Swiper", // REQUIRED
        ],
      },
    },
    {
      module: "MMM-page-indicator", //REQUIRED
      position: "bottom_bar", // feel free to adjust
      config: {
        pages: 3, // feel free to adjust
      },
    },
    {
      module: "MMM-Simple-Swiper",
      disabled: false,
      config: {
        echoLeftPin: 24, // GPIO #
        triggerLeftPin: 23, // GPIO #
        echoRightPin: 26, // GPIO #
        triggerRightPin: 25, // GPIO #
        threshold: 175, // in centimeters
        distanceDiff: 1.25, // difference between both sensors
        debug: false, // if true, the raw data is printed to stdout while MagicMirror is running
        delay: 1000, // time between passing data from C executable to the node_helper in milliseconds
      },
    },
    {
      module: "alert", // feel free to remove or swap out
      disabled: false,
    },
    {
      module: "updatenotification", // feel free to remove or swap out
      position: "top_bar",
      disabled: false,
    },
    {
      module: "clock", // feel free to remove or swap out
      position: "top_right",
      timeFormat: 12,
      showPeriodUpper: true,
      disabled: false,
    },
    {
      module: "calendar", // feel free to remove or swap out
      header: "US Holidays",
      position: "top_right",
      disabled: false,
      config: {
        calendars: [
          {
            symbol: "calendar-check-o ",
            url: "webcal://www.calendarlabs.com/templates/ical/US-Holidays.ics",
          },
        ],
      },
    },

    {
      module: "compliments", // feel free to remove or swap out
      position: "lower_third",
      disabled: true,
    },

    {
      module: "weatherforecast", // feel free to remove or swap out
      position: "top_right",
      header: "Weather Forecast",
      disabled: false,
      config: {
        location: "New York, NY, USA",
        units: "imperial",
        appid: "c0520f8e8537b2c7555a9f7d5c2d53ec",
      },
    },

    {
      module: "currentweather", // feel free to remove or swap out
      position: "top_right",
      disabled: false,
      config: {
        location: "New York, NY, USA",
        units: "imperial",
        appid: "c0520f8e8537b2c7555a9f7d5c2d53ec",
      },
    },

    {
      module: "newsfeed", // feel free to remove or swap out
      position: "bottom_bar",
      config: {
        feeds: [
          {
            title: "New York Times",
            url: "http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml",
          },
          {
            title: "CNET",
            url: "https://www.cnet.com/rss/news/",
          },
          {
            title: "TechRepublic",
            url: "https://www.techrepublic.com/rssfeeds/articles/",
          },
        ],
        showSourceTitle: true,
        showPublishDate: true,
      },
    },
  ],
};

/*************** DO NOT EDIT THE LINE BELOW ***************/
if (typeof module !== "undefined") {
  module.exports = config;
}

Start MagicMirror

cd ~/MagicMirror

npm start

# check to ensure the MMM-Simple-Swiper module is running
ps -ef | egrep -i "sudo\s+.*./MMM-Simple-Swiper/swiper"

# if it is running, you should see an output similar to this
sudo /home/pi/MagicMirror/modules/MMM-Simple-Swiper/main {"echoLeftPin":24,"triggerLeftPin":23,"echoRightPin":26,"triggerRightPin":25,"threshold":175,"distanceDiff":1.25,"debug":false,"delay":1000}

# depending on the arguments provided to the config, your JSON string may differ