#+AUTHOR: Brandon Marlowe & Otto Juba #+EMAIL: [email protected];[email protected] #+STARTUP: showall #+OPTIONS: toc:nil

• MMM-Simple-Swiper | Author | Contact | |-----------------+-----------------------------------| | Brandon Marlowe | [email protected] | | Otto Juba | [email protected] |

** 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

#+BEGIN_SRC sh

assuming mmpm is already installed

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

#+END_SRC

#+BEGIN_SRC sh

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 #+END_SRC

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:

#+BEGIN_SRC js // other code above ...

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

// other code below ... #+END_SRC

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 [[./images/raspberry_pi_circuit_note_fig2a.jpg]]

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

** Wiring the Sensors [[./images/hcsr04.png]]

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

** How we wired ours [[./images/MMM-Simple-Swiper-Pin-Layout.jpg]]

• 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.

#+BEGIN_SRC js // 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 ... #+END_SRC

** 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.

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

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

  }
}

] #+END_SRC

** 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) #+BEGIN_SRC sh

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

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

 sudo apt install nodejs -y

#+END_SRC

*** MagicMirror #+BEGIN_SRC sh

 cd ~/

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

 cd ~/MagicMirror

 npm install

 # for the moment, don’t start the MagicMirror

#+END_SRC

*** MMM-pages #+BEGIN_SRC sh

 cd ~/MagicMirror/modules/

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

 cd ~/MagicMirror/modules/MMM-pages

 npm install

#+END_SRC

*** MMM-page-indicator #+BEGIN_SRC sh

 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

#+END_SRC

*** MMM-Simple-Swiper #+BEGIN_SRC sh

 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

#+END_SRC

** Basic config.js containing required modules #+BEGIN_SRC js /* 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;
}

#+END_SRC

** Start MagicMirror #+BEGIN_SRC sh

 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

#+END_SRC