Merge pull request #6 from rlisle/ultrasonic

Ultrasonic plugin

Photon/IoTlib/examples/everything/everything.ino

@@ -49,6 +49,7 @@ BSD license, check LICENSE for more information.
 All text above must be included in any redistribution.
 
 Changelog:
+2017-05-21: Add plugins
 2017-03-28: Use fixed 'patriot' event name.
 2017-03-24: Rename Patriot
 2017-03-11: TODO: add remaining devices.
@@ -59,6 +60,7 @@ Changelog:
 #include <PatriotLight.h>
 #include <PatriotSwitch.h>
 #include <PatriotFan.h>
+#include <PatriotUltrasonic.h>
 
 IoT *iot;
 
@@ -80,6 +82,8 @@ void setup() {
 
     Fan *fan = new Fan(DAC, "Fan");
 
+    Ultrasonic *ultra = new Ultrasonic(A1, A0, "Proximity");
+
     // Add them
     iot->addDevice(outside);
     iot->addDevice(kitchen);
@@ -93,6 +97,8 @@ void setup() {
 
     iot->addDevice(fan);
 
+    iot->addDevice(ultra);
+
     //TODO: Add light level sensor
 
     //TODO: Add servo motor

Photon/IoTlib/examples/ultrasonic/ultrasonic.ino

@@ -0,0 +1,41 @@
+/*******************************************************
+Patriot HC-SR04 Ultrasonic Proximity Sensor Example
+
+This example shows how to use the Patriot Switch plugin
+It includes:
+
+ * HC-SR04 Ultrasonic Proximity Sensor
+    - Trigger               A1      Photon pin 11
+    - Echo                  A0      Photon pin 12
+
+http://www.github.com/rlisle/Patriot
+
+Written by Ron Lisle
+
+BSD license, check LICENSE for more information.
+All text above must be included in any redistribution.
+
+Changelog:
+2017-05-21: Initial creation
+********************************************************/
+
+#include <IoT.h>
+#include <PatriotUltrasonic.h>
+
+IoT *iot;
+
+void setup() {
+    iot = IoT::getInstance();
+    iot->setControllerName("myPhoton");
+    iot->begin();
+
+    // Create the HC-SR04 sensor device
+    Ultrasonic *ultra1 = new Ultrasonic(A1, A0, "Proximity");
+
+    // Add it to IoT
+    iot->addDevice(ultra1);
+}
+
+void loop() {
+    iot->loop();
+}

Photon/IoTlib/library.properties

@@ -1,5 +1,5 @@
 name=IoT
-version=1.1.2
+version=1.1.3
 author=Ron Lisle
 license=BSD
 sentence=Control your Photon projects using events from other Photons, Alexa and iOS devices
@@ -12,3 +12,4 @@ dependencies.PatriotLight=1.0.0
 dependencies.PatriotSwitch=1.0.0
 dependencies.PatriotFan=1.0.0
 dependencies.PatriotDHT=1.0.0
+dependencies.PatriotUltrasonic=1.0.0

Photon/Plugins/Ultrasonic/LICENSE

@@ -0,0 +1,22 @@
+Copyright 2017 Ron Lisle
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+   disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+   disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
+   products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Photon/Plugins/Ultrasonic/README.md

@@ -0,0 +1,78 @@
+# PatriotUltrasonic
+
+A Patriot plugin to support ultrasonic proximity detector devices.
+
+This library is used to support HC-SR04 ultrasonic proximity devices.
+Any 2 Photon I/O pins may be used to provide pulse trigger and echo status.
+
+## Usage
+
+Include this library in any Photon sketch that needs to support an ultrasonic
+proximity sensor such as the HC-SR04. 
+These are inexpensive devices that generate an ultrasonic
+pulse when triggered, and raise an echo line when that pulse is detected.
+Distance is calculated by measuring the time between the trigger and the
+received echo.
+Refer to the more complex examples in the main Patriot IoT examples
+ directory.
+
+This example creates a single ultrasonic proximity device connected to pins
+A1 and A0.
+
+When the state of the input D4 pin changes, an event named "switch"
+will be published. Other device can define a behavior that uses
+this event.
+
+You can use the Particle.io console to monitor these events.
+
+```
+#include <IoT.h>
+#include <PatriotUltrasonic.h>
+
+IoT *iot;
+
+void setup() {
+    iot = IoT::getInstance();
+    iot->setControllerName("myPhoton");
+    iot->begin();
+
+    // Create the HC-SR04 sensor device
+    Ultrasonic *ultra1 = new Ultrasonic(A1, A0, "Proximity");
+
+    // Add it to IoT
+    iot->addDevice(ultra1);
+}
+
+void loop() {
+    iot->loop();
+}
+```
+
+## Documentation
+
+Refer to the Patriot Github repository and documentation for more
+information.
+
+
+## Contributing
+
+Here's how you can make changes to this library and eventually contribute those changes back.
+
+To get started, [clone the library from GitHub to your local machine](https://help.github.com/articles/cloning-a-repository/).
+
+Change the name of the library in `library.properties` to something different. You can add your name at then end.
+
+Modify the sources in <src> and <examples> with the new behavior.
+
+To compile an example, use `particle compile examples/usage` command in [Particle CLI](https://docs.particle.io/guide/tools-and-features/cli#update-your-device-remotely) or use our [Desktop IDE](https://docs.particle.io/guide/tools-and-features/dev/#compiling-code).
+
+After your changes are done you can upload them with `particle library upload` or `Upload` command in the IDE. This will create a private (only visible by you) library that you can use in other projects. Do `particle library add IoT_myname` to add the library to a project on your machine or add the IoT_myname library to a project on the Web IDE or Desktop IDE.
+
+At this point, you can create a [GitHub pull request](https://help.github.com/articles/about-pull-requests/) with your changes to the original library.
+
+If you wish to make your library public, use `particle library publish` or `Publish` command.
+
+## LICENSE
+Copyright 2017 Ron Lisle
+
+Refer to the included LICENSE file.

Photon/Plugins/Ultrasonic/examples/ultrasonic/ultrasonic.ino

@@ -0,0 +1,41 @@
+/*******************************************************
+Patriot HC-SR04 Ultrasonic Proximity Sensor Example
+
+This example shows how to use the Patriot Switch plugin
+It includes:
+
+ * HC-SR04 Ultrasonic Proximity Sensor
+    - Trigger               A1      Photon pin 11
+    - Echo                  A0      Photon pin 12
+
+http://www.github.com/rlisle/Patriot
+
+Written by Ron Lisle
+
+BSD license, check LICENSE for more information.
+All text above must be included in any redistribution.
+
+Changelog:
+2017-05-21: Initial creation
+********************************************************/
+
+#include <IoT.h>
+#include <PatriotUltrasonic.h>
+
+IoT *iot;
+
+void setup() {
+    iot = IoT::getInstance();
+    iot->setControllerName("myPhoton");
+    iot->begin();
+
+    // Create the HC-SR04 sensor device
+    Ultrasonic *ultra1 = new Ultrasonic(A1, A0, "Proximity");
+
+    // Add it to IoT
+    iot->addDevice(ultra1);
+}
+
+void loop() {
+    iot->loop();
+}

Photon/Plugins/Ultrasonic/library.properties

@@ -0,0 +1,9 @@
+name=PatriotUltrasonic
+version=1.0.0
+author=Ron Lisle
+license=BSD
+sentence=Extend Patriot IoT to support ultrasonic proximity detectors.
+paragraph=Patriot provides support for controlling IoT devices using Alexa and iOS devices. This plugin adds the ability to use ultrasonic proximity detectors to control those devices wirelessly also.
+url=http://www.github.com/rlisle/Patriot
+repository=http://www.github.com/rlisle/Patriot
+architectures=particle-photon

Photon/Plugins/Ultrasonic/src/PatriotUltrasonic.cpp

@@ -0,0 +1,135 @@
+/******************************************************************
+PatriotUltrasonic plugin
+
+Features:
+- Reports distance to nearest object in inches
+
+http://www.github.com/rlisle/Patriot
+
+Written by Ron Lisle
+
+BSD license, check license.txt for more information.
+All text above must be included in any redistribution.
+
+Changelog:
+2017-05-17: Move to separate library
+2017-05-15: Make devices generic
+2017-03-24: Rename Patriot
+2017-03-05: Convert to v2 particle library
+2016-07-29: Refactor to separate switch and switches classes
+         Add mapping to an activity
+2016-06-21: Photon version
+2016-02-3: Initial version
+******************************************************************/
+
+#include "PatriotUltrasonic.h"
+
+Ultrasonic::Ultrasonic(int triggerPin, int echoPin, String name)
+{
+    _triggerPin         = triggerPin;
+    _echoPin            = echoPin;
+    _name               = name;
+    _thresholdInInches  = kThresholdInInches;
+
+    distanceInInches    = 0;
+
+    pinMode(_triggerPin, OUTPUT);
+    digitalWrite(_triggerPin, LOW);
+    if(_triggerPin != _echoPin) {
+        pinMode(_echoPin, INPUT_PULLUP);
+    }
+}
+
+
+void Ultrasonic::loop()
+{
+    long time = millis();
+    if (isTimeToPing(time))
+    {
+        _lastPingTime = time;
+        int newDistance = ping();
+        if (didDistanceChange(newDistance))
+        {
+            distanceInInches = newDistance;
+            notify(newDistance);
+        }
+    }
+}
+
+
+bool Ultrasonic::isTimeToPing(long time)
+{
+    return (time > _lastPingTime + kPingInterval);
+}
+
+
+bool Ultrasonic::didDistanceChange(int newDistance)
+{
+    return ((newDistance > distanceInInches + _thresholdInInches)
+        || (newDistance < distanceInInches - _thresholdInInches));
+}
+
+
+int Ultrasonic::ping()
+{
+    // establish variables for duration of the ping,
+    // and the distance result in inches and centimeters:
+    long duration;
+    int  inches;
+
+    // The PING))) is triggered by a HIGH pulse of 2 or more microseconds.
+    // Give a short LOW pulse beforehand to ensure a clean HIGH pulse:
+    // If using the same pin, need to set to output and low state
+    if(_triggerPin == _echoPin){
+        pinMode(_triggerPin, OUTPUT);
+        digitalWrite(_triggerPin, LOW);
+        delayMicroseconds(5);
+    }
+    digitalWrite(_triggerPin, HIGH);
+    delayMicroseconds(5);
+    digitalWrite(_triggerPin, LOW);
+
+    // The same pin can be used to read the signal from the PING))): a HIGH
+    // pulse whose duration is the time (in microseconds) from the sending
+    // of the ping to the reception of its echo off of an object.
+    if(_echoPin == _triggerPin) {
+        pinMode(_echoPin, INPUT_PULLUP);
+    }
+    duration = pulseIn(_echoPin, HIGH);
+//  Serial.println("Ping: duration = "+String(duration));
+    if(_echoPin == _triggerPin) {
+        pinMode(_triggerPin, OUTPUT);
+        digitalWrite(_triggerPin, LOW);
+    }
+
+    // convert the time into a distance
+    inches = microsecondsToInches(duration);
+    //cm = microsecondsToCentimeters(duration);
+
+    return inches;
+}
+
+// Private
+int Ultrasonic::microsecondsToInches(long microseconds) {
+    // According to Parallax's datasheet for the PING))), there are
+    // 73.746 microseconds per inch (i.e. sound travels at 1130 feet per
+    // second).  This gives the distance travelled by the ping, outbound
+    // and return, so we divide by 2 to get the distance of the obstacle.
+    // See: http://www.parallax.com/dl/docs/prod/acc/28015-PING-v1.3.pdf
+    return microseconds / 74 / 2;
+}
+
+int Ultrasonic::microsecondsToCentimeters(long microseconds) {
+    // The speed of sound is 340 m/s or 29 microseconds per centimeter.
+    // The ping travels out and back, so to find the distance of the
+    // object we take half of the distance travelled.
+    return microseconds / 29 / 2;
+}
+
+void Ultrasonic::notify(int distance)
+{
+    String pubString = _name + ":" + String(distance);
+    Serial.println(pubString);
+    //TODO: get event name from IoT instead of hardcoded "patriot"
+    Particle.publish("patriot", pubString);
+}