Merge pull request #14 from rlisle/pinrelay

Pin based relay

Photon/Plugins/NCD8Relay/LICENSE

@@ -1,3 +1,22 @@
 Copyright 2017 Ron Lisle
 
-<insert the text of your chosen license license here>
+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/NCD8Relay/README.md

@@ -24,31 +24,6 @@ to work, since a "Discover Devices" cycle is needed. You can manually
 invoke a discovery using the Alexa app to eliminate the delay.
 
 
-```
-#include <IoT.h>
-#include <PatriotNCD8Relay.h>
-
-IoT *iot;
-
-void setup() {
-    iot = IoT::getInstance();
-    iot->setControllerName("myPhoton");
-    iot->setPublishName("patriot");
-    iot->begin();
-
-    byte address = 0x20;
-    byte numRelays = 8;
-    Relay *relay1 = new Relay(address, numRelays, 0, "relay1");
-    iot->addDevice(relay1);
-
-    iot->addBehavior(relay1, new Behavior("Relay", '>', 0, 100));
-}
-
-void loop() {
-    iot->loop();
-}
-```
-
 ## Documentation
 
 Refer to the Patriot Github repository and documentation for more

Photon/Plugins/NCD8Relay/examples/relay/relay.ino

@@ -1,5 +1,5 @@
 /*******************************************************
-Relay Example
+NCD 8 Relay board Example
 
 This example supports the 1st relay on an NCD 8 Relay board.
 
@@ -21,16 +21,15 @@ IoT *iot;
 
 void setup() {
     iot = IoT::getInstance();
-    iot->setControllerName("myPhoton");
-    iot->setPublishName("patriot");
     iot->begin();
 
     byte address = 0x20;
     byte numRelays = 8;
-    Relay *relay1 = new Relay(address, numRelays, 0, "relay1");
+    Relay *relay1 = new Relay(address, numRelays, 0, "relay");
     iot->addDevice(relay1);
 
-    iot->addBehavior(relay1, new Behavior("Relay", '>', 0, 100));
+    iot->addBehavior(relay1, new Behavior("my gadget", '>', 0, 100));    // Turn on
+    iot->addBehavior(relay1, new Behavior("my gadget", '=', 0, 0));      // Turn off
 }
 
 void loop() {

Photon/Plugins/NCD8Relay/library.properties

@@ -1,5 +1,5 @@
 name=PatriotNCD8Relay
-version=2.0.0
+version=2.0.1
 author=Ron Lisle
 license=BSD
 sentence=Extend Patriot IoT to support NCD 8 Relay board

Photon/Plugins/NCD8Relay/src/PatriotRelay.cpp → Photon/Plugins/NCD8Relay/src/PatriotNCD8Relay.cpp

@@ -1,10 +1,12 @@
 /******************************************************************
- Relay control
+ NCD 8 Relay board control
 
- Up to 8 relay controllers can reside on a single I2C bus.
+ Up to 8 relay boards can reside on a single I2C bus.
 
  Features:
  - On/Off control
+ - Supports multiple boards
+ - Automatic shut off if duration specified
 
  http://www.github.com/rlisle/Patriot
 
@@ -19,22 +21,23 @@
  2017-10-03: Initial creation
  ******************************************************************/
 
-#include "PatriotRelay.h"
+#include "PatriotNCD8Relay.h"
 
 #define MILLIS_PER_SECOND 1000
 
-int8_t Relay::_numControllers = 0;    // Count of relay boards on I2C bus
-int8_t Relay::_currentStates[8];      // All relays initially off
-int8_t Relay::_addresses[8];          // Addresses of up to 8 boards
+int8_t NCD8Relay::_numControllers = 0;  // Count of relay boards on I2C bus
+int8_t NCD8Relay::_currentStates[8];    // All relays initially off
+int8_t NCD8Relay::_addresses[8];        // Addresses of up to 8 boards
 
 /**
  * Constructor
  * @param address is the board address set by jumpers (0-7)
  * @param numRelays identifies which NCD Relay board by the number of relays on it
  * @param relayNum is the relay number on the NCD 8 Relay board (1-8)
  * @param name String name used to address the relay.
+ * @param duration Optional seconds value to automatically turn off relay. 0 = no automatic turn off.
  */
-Relay::Relay(int8_t address, int8_t numRelays, int8_t relayNum, String name, int8_t duration)
+NCD8Relay::NCD8Relay(int8_t address, int8_t numRelays, int8_t relayNum, String name, int8_t duration)
     : Device(name)
 {
     _relayNum   = relayNum;
@@ -51,7 +54,7 @@ Relay::Relay(int8_t address, int8_t numRelays, int8_t relayNum, String name, int
     }
 }
 
-int8_t Relay::initialize8RelayBoard(int8_t address) {
+int8_t NCD8Relay::initialize8RelayBoard(int8_t address) {
 
     _registerAddress = 0x0A;    // Does this change for different boards?
 
@@ -63,7 +66,7 @@ int8_t Relay::initialize8RelayBoard(int8_t address) {
     return index;
 }
 
-int8_t Relay::initializeBoard(int8_t address) {
+int8_t NCD8Relay::initializeBoard(int8_t address) {
 
     // Only the first relay loaded needs to initialize the I2C link
     if(!Wire.isEnabled()) {
@@ -83,7 +86,7 @@ int8_t Relay::initializeBoard(int8_t address) {
     return addAddressToArray(address);
 }
 
-int8_t Relay::boardIndex(int8_t address) {
+int8_t NCD8Relay::boardIndex(int8_t address) {
     for(int8_t index=0; index<_numControllers; index++) {
         if(_addresses[index] == address) {
             return index;
@@ -92,7 +95,7 @@ int8_t Relay::boardIndex(int8_t address) {
     return -1;
 }
 
-int8_t Relay::addAddressToArray(int8_t address) {
+int8_t NCD8Relay::addAddressToArray(int8_t address) {
     _currentStates[_numControllers] = 0x00;
     _addresses[_numControllers] = address;
 
@@ -111,15 +114,15 @@ int8_t Relay::addAddressToArray(int8_t address) {
  * This is how things are turned on/off in Patriot
  * @param percent Int 0 to 100. 0 = off, >0 = on
  */
-void Relay::setPercent(int percent) {
+void NCD8Relay::setPercent(int percent) {
     if(percent == 0) setOff();
     else setOn();
 }
 
 /**
  * Set On
  */
-void Relay::setOn() {
+void NCD8Relay::setOn() {
     if(isOn()) return;
 
     _percent = 100;
@@ -130,11 +133,11 @@ void Relay::setOn() {
     }
 
     byte bitmap = 1 << _relayNum;
-    Relay::_currentStates[_boardIndex] |= bitmap;            // Set relay's bit
+    NCD8Relay::_currentStates[_boardIndex] |= bitmap;            // Set relay's bit
 
     Wire.beginTransmission(_addresses[_boardIndex]);
     Wire.write(_registerAddress);
-    Wire.write(Relay::_currentStates[_boardIndex]);
+    Wire.write(NCD8Relay::_currentStates[_boardIndex]);
     byte status = Wire.endTransmission();
     if(status != 0) {
         //TODO: handle any errors, retry, etc.
@@ -145,19 +148,19 @@ void Relay::setOn() {
 /**
  * Set relay off
  */
-void Relay::setOff() {
+void NCD8Relay::setOff() {
     if(isOff()) return;
 
     _percent = 0;
     _stopMillis = 0;
 
     byte bitmap = 1 << _relayNum;
     bitmap = 0xff ^ bitmap;
-    Relay::_currentStates[_boardIndex] &= bitmap;
+    NCD8Relay::_currentStates[_boardIndex] &= bitmap;
 
     Wire.beginTransmission(_addresses[_boardIndex]);
     Wire.write(_registerAddress);
-    Wire.write(Relay::_currentStates[_boardIndex]);
+    Wire.write(NCD8Relay::_currentStates[_boardIndex]);
     byte status = Wire.endTransmission();
     if(status != 0) {
         //TODO: handle any errors, retry, etc.
@@ -172,7 +175,7 @@ void Relay::setOff() {
 /**
  * loop()
  */
-void Relay::loop()
+void NCD8Relay::loop()
 {
     if(_stopMillis != 0)
     {

Photon/Plugins/NCD8Relay/src/PatriotRelay.h → Photon/Plugins/NCD8Relay/src/PatriotNCD8Relay.h

@@ -4,6 +4,7 @@
  Features:
  - On/Off control
  - Supports multiple boards
+ - Automatic shut off if duration specified
 
  http://www.github.com/rlisle/Patriot
 
@@ -23,7 +24,7 @@
 #include "Particle.h"
 #include "device.h"
 
-class Relay : public Device
+class NCD8Relay : public Device
 {
  private:
     int8_t  _relayNum;
@@ -42,7 +43,7 @@ class Relay : public Device
     int8_t  addAddressToArray(int8_t address);
 
  public:
-    Relay(int8_t address, int8_t numRelays, int8_t relayNum, String name, int8_t duration = 0);
+    NCD8Relay(int8_t address, int8_t numRelays, int8_t relayNum, String name, int8_t duration = 0);
 
     void    setPercent(int percent);
     void    setOn();

Photon/Plugins/Relay/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/Relay/README.md

@@ -0,0 +1,55 @@
+# PatriotRelay
+
+A Patriot plugin to support simple relays.
+
+## Usage
+
+Include this library in a Photon sketch to control simple on/off
+devices such as relays.
+
+Note that many relay type devices require more current than can be 
+safely provided by a GPIO pin. In these cases you will need to provide
+some sort of driver circuit (eg. transistor, MOSFET, etc) to provide
+ample current to the device.
+
+This example creates a single device connected to a relay attached
+to GPIO D0. The device is named "relay".
+
+Since Patriot supports automatic detection by the iOS app and Alexa,
+either of these can be used to control the relay once this sketch is
+loaded to a Photon. There may be a 15 minute delay before Alexa starts
+to work, since a "Discover Devices" cycle is needed. You can manually
+invoke a discovery using the Alexa app to eliminate the delay.
+
+After Alexa discovery is performed, you can control this by saying
+"Alexa, turn on relay" or "Alexa, turn off relay".
+
+
+## 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/Relay/examples/relay/relay.ino

@@ -0,0 +1,37 @@
+/*******************************************************
+Relay Example
+
+This example supports a relay connected to pin D7.
+D7 is also connected to the built-in blue LED, so
+it can be used to view operation.
+
+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-10-31: Initial creation
+********************************************************/
+
+#include <IoT.h>
+#include <PatriotRelay.h>
+
+IoT *iot;
+
+void setup() {
+    iot = IoT::getInstance();
+    iot->begin();
+
+    // Define our "relay" device on pin D7
+    // Since no duration is specified, it is set to a
+    // default value of 0 meaning no automatic turn off.
+    Relay *relay = new Relay(D7, "relay");
+    iot->addDevice(relay);
+}
+
+void loop() {
+    iot->loop();
+}