Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Bee-Mar/MMM-Simple-Swiper
A simple, multi-threaded interface for the HC-SR04 sensors and the MagicMirror
https://github.com/Bee-Mar/MMM-Simple-Swiper
c javascript magic-mirror-modules magicmirror2 nodejs raspberry-pi-3 rasperrypi
Last synced: about 2 months ago
JSON representation
A simple, multi-threaded interface for the HC-SR04 sensors and the MagicMirror
- Host: GitHub
- URL: https://github.com/Bee-Mar/MMM-Simple-Swiper
- Owner: Bee-Mar
- Archived: true
- Created: 2019-01-14T03:22:36.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-01-16T14:43:22.000Z (over 2 years ago)
- Last Synced: 2024-07-08T18:51:22.449Z (2 months ago)
- Topics: c, javascript, magic-mirror-modules, magicmirror2, nodejs, raspberry-pi-3, rasperrypi
- Language: JavaScript
- Size: 13.1 MB
- Stars: 19
- Watchers: 6
- Forks: 9
- Open Issues: 2
-
Metadata Files:
- Readme: README.org
Awesome Lists containing this project
README
#+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 ==
to enable
4) Also within =Interfacing Options=; select =Remote GPIO=;
select == 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