Merge pull request #18 from myDevicesIoT/feature/esp-support

Feature/esp support

Author: jburhenn

README.md

@@ -1,17 +1,60 @@
 # Cayenne MQTT Arduino Library
-The Cayenne MQTT Arduino Library provides functions to easily connect to the Cayenne IoT project builder.
+The Cayenne MQTT Arduino Library provides functions to easily connect to the [Cayenne IoT project builder](https://www.cayenne-mydevices.com). This library is designed to work with Arduino, ESP8266 and ESP32 devices. With it you can send data to and receive data from Cayenne.
 
-This library bundles the [Eclipse Paho MQTT C/C++ client](https://github.com/eclipse/paho.mqtt.embedded-c).
+![alt text](https://upload.wikimedia.org/wikipedia/commons/3/38/Arduino_Uno_-_R3.jpg)
 
-## Repository Structure
-- **src** - The library source code.
-  - **CayenneUtils** - Common code for creating and parsing Cayenne topics and payloads. This code can be used with any MQTT client.
-  - **CayenneMQTTClient** - Platform independent Cayenne C++ library using the Paho MQTT C++ library. To create platform specific versions of this library networking and timer code for the platform are required.
-  - **MQTTCommon** - Common Paho MQTT C code used by both the C and C++ libraries.
-  - **Platform** - Platform specific networking and timer code, as well as test and example applications.
+[Arduino Uno image](https://commons.wikimedia.org/wiki/File%3AArduino_Uno_-_R3.jpg) by [SparkFun](https://www.sparkfun.com) is licensed under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/)
+
+![alt text](https://cdn-learn.adafruit.com/assets/assets/000/024/792/medium640/adafruit_products_2471_iso_assembled_01_ORIG.jpg?1429908417)
+
+[Adafruit HUZZAH ESP8266 image](https://learn.adafruit.com/assets/24792) by [lady ada](https://learn.adafruit.com/users/adafruit2) is licensed under [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/)
+
+![alt text](https://cdn.sparkfun.com//assets/parts/1/1/5/6/4/13907-01.jpg)
+
+[SparkFun ESP32 Thing image](https://www.sparkfun.com/products/13907) by [SparkFun](https://www.sparkfun.com) is licensed under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/)
+
+## Requirements
+### Hardware
+* An Arduino, ESP8266 or ESP32 module, e.g. the [Arduino Uno](https://store.arduino.cc/usa/arduino-uno-rev3), [Adafruit HUZZAH ESP8266](https://www.adafruit.com/product/2471) or [SparkFun ESP32 Thing](https://www.sparkfun.com/products/13907).
+* A USB cable, or if using certain ESP devices, a USB to Serial FTDI cable.
+
+### Software
+* [Arduino IDE](https://www.arduino.cc/en/Main/Software) for Windows, Linux or Mac OS.
+* [This library](https://github.com/myDevicesIoT/Cayenne-MQTT-Arduino/archive/master.zip).
+
+## Getting Started
+### Environment Setup
+1. Download and install the [Arduino IDE](https://www.arduino.cc/en/Main/Software).
+2. Install the **CayenneMQTT** library from **Sketch -> Include Library -> Manage Libraries**.
+3. If using an ESP module, install the Board Package.
+   1. For **ESP8266**:
+      1. Under **File -> Preferences** add `http://arduino.esp8266.com/stable/package_esp8266com_index.json` to the **Additional Boards Manager URLs** field.
+      2. Install the **esp8266** platform from **Tools -> Board -> Boards Manager**.
+   2. For **ESP32**, manually install the board package by following the instructions here: https://github.com/espressif/arduino-esp32/blob/master/README.md#installation-instructions.
+4. Connect your device to your computer using the appropriate USB cable or USB to Serial FTDI cable.
+5. Select your Arduino board or ESP module and and the correct port from the **Tools** menu.
+
+### Cayenne Setup
+1. Create your Cayenne account at https://www.cayenne-mydevices.com.
+2. Add a new device using the **Add new...** page **MicroControllers** or **Bring Your Own Thing** options.
+
+### Building Examples
+1. Open an included example connection sketch from **File -> Examples -> CayenneMQTT -> Connections**.
+2. Modify the included sketch with the Cayenne authentication info you received when adding your device.
+3. If using an ESP module or WiFi shield modify the sketch with your network info.
+3. Compile and upload the sketch to your device. For ESP devices uploading may require setting the device into bootload mode. For the Adafruit HUZZAH ESP8266 module this is done with the folowing steps:
+   1. Hold down the **GPIO0** button.
+   2. Click the **Reset** button.
+   3. Let go of the **GPIO0** button.
+   4. The red LED should light up, indicating the device is ready for uploading.
+   5. Upload your sketch.
+4. Check the Cayenne dashboard to ensure it is receiving sample data from your device.
+
+## Compatibility
+This library was tested with various Arduino boards including the Uno, Mega, Due, etc. as well as the Adafruit HUZZAH ESP8266 breakout module and an Espressif ESP32 development board. It should also work with other standard ESP8266 and ESP32 modules that are compatible with the Arduino IDE. Boards with very constrained memory like the Arduino Leonardo or Micro may have issues fitting this library alongside other libraries. For those boards you might try using a manually specified IP as shown in the [ManualConnection example sketch](https://github.com/myDevicesIoT/Cayenne-MQTT-Arduino/blob/master/examples/Connections/ManualConnection/ManualConnection.ino) in order to save space.
+
+## Contributions
+* This library includes the [Eclipse Paho MQTT C/C++ client](https://github.com/eclipse/paho.mqtt.embedded-c).
 
 ## Cayenne MQTT Libraries
-- **[Cayenne-MQTT-C](https://github.com/myDevicesIoT/Cayenne-MQTT-C)** - C version of the Cayenne MQTT Library.
-- **[Cayenne-MQTT-CPP](https://github.com/myDevicesIoT/Cayenne-MQTT-CPP)** - C++ version of the Cayenne MQTT Library.
-- **[Cayenne-MQTT-Arduino](https://github.com/myDevicesIoT/Cayenne-MQTT-Arduino)** - Arduino version of the Cayenne MQTT Library.
-- **[Cayenne-MQTT-mbed](https://github.com/myDevicesIoT/Cayenne-MQTT-mbed)** - mbed version of the Cayenne MQTT Library. This is also available on the mbed developer site [here](https://developer.mbed.org/teams/myDevicesIoT/code/Cayenne-MQTT-mbed/).
+Additional libraries are available for connecting to Cayenne on other platforms and devices. These can be found at https://github.com/myDevicesIoT.

examples/Connections/ESP32/ESP32.ino

@@ -0,0 +1,57 @@
+/*
+This example shows how to connect to Cayenne using an ESP32 and send/receive sample data.
+
+The CayenneMQTT Library is required to run this sketch. If you have not already done so you can install it from the Arduino IDE Library Manager.
+
+Steps:
+1. If you have not already installed the ESP32 Board Package install it using the instructions here: https://github.com/espressif/arduino-esp32/blob/master/README.md#installation-instructions.
+2. Select your ESP32 board from the Tools menu.
+3. Set the Cayenne authentication info to match the authentication info from the Dashboard.
+4. Set the network name and password.
+5. Compile and upload the sketch.
+6. A temporary widget will be automatically generated in the Cayenne Dashboard. To make the widget permanent click the plus sign on the widget.
+*/
+
+//#define CAYENNE_DEBUG
+#define CAYENNE_PRINT Serial
+#include <CayenneMQTTESP32.h>
+
+// WiFi network info.
+char ssid[] = "ssid";
+char wifiPassword[] = "wifiPassword";
+
+// Cayenne authentication info. This should be obtained from the Cayenne Dashboard.
+char username[] = "MQTT_USERNAME";
+char password[] = "MQTT_PASSWORD";
+char clientID[] = "CLIENT_ID";
+
+
+void setup() {
+	Serial.begin(9600);
+	Cayenne.begin(username, password, clientID, ssid, wifiPassword);
+}
+
+void loop() {
+	Cayenne.loop();
+}
+
+// Default function for sending sensor data at intervals to Cayenne.
+// You can also use functions for specific channels, e.g CAYENNE_OUT(1) for sending channel 1 data.
+CAYENNE_OUT_DEFAULT()
+{
+	// Write data to Cayenne here. This example just sends the current uptime in milliseconds on virtual channel 0.
+	Cayenne.virtualWrite(0, millis());
+	// Some examples of other functions you can use to send data.
+	//Cayenne.celsiusWrite(1, 22.0);
+	//Cayenne.luxWrite(2, 700);
+	//Cayenne.virtualWrite(3, 50, TYPE_PROXIMITY, UNIT_CENTIMETER);
+}
+
+// Default function for processing actuator commands from the Cayenne Dashboard.
+// You can also use functions for specific channels, e.g CAYENNE_IN(1) for channel 1 commands.
+CAYENNE_IN_DEFAULT()
+{
+	CAYENNE_LOG("Channel %u, value %s", request.channel, getValue.asString());
+	//Process message here. If there is an error set an error message using getValue.setError(), e.g getValue.setError("Error message");
+}
+

examples/Connections/ESP8266/ESP8266.ino

@@ -0,0 +1,57 @@
+/*
+This example shows how to connect to Cayenne using an ESP8266 and send/receive sample data.
+
+The CayenneMQTT Library is required to run this sketch. If you have not already done so you can install it from the Arduino IDE Library Manager.
+
+Steps:
+1. If you have not already installed the ESP8266 Board Package install it using the instructions here: https://github.com/esp8266/Arduino#installing-with-boards-manager.
+2. Select your ESP8266 board from the Tools menu.
+3. Set the Cayenne authentication info to match the authentication info from the Dashboard.
+4. Set the network name and password.
+5. Compile and upload the sketch.
+6. A temporary widget will be automatically generated in the Cayenne Dashboard. To make the widget permanent click the plus sign on the widget.
+*/
+
+//#define CAYENNE_DEBUG
+#define CAYENNE_PRINT Serial
+#include <CayenneMQTTESP8266.h>
+
+// WiFi network info.
+char ssid[] = "ssid";
+char wifiPassword[] = "wifiPassword";
+
+// Cayenne authentication info. This should be obtained from the Cayenne Dashboard.
+char username[] = "MQTT_USERNAME";
+char password[] = "MQTT_PASSWORD";
+char clientID[] = "CLIENT_ID";
+
+
+void setup() {
+	Serial.begin(9600);
+	Cayenne.begin(username, password, clientID, ssid, wifiPassword);
+}
+
+void loop() {
+	Cayenne.loop();
+}
+
+// Default function for sending sensor data at intervals to Cayenne.
+// You can also use functions for specific channels, e.g CAYENNE_OUT(1) for sending channel 1 data.
+CAYENNE_OUT_DEFAULT()
+{
+	// Write data to Cayenne here. This example just sends the current uptime in milliseconds on virtual channel 0.
+	Cayenne.virtualWrite(0, millis());
+	// Some examples of other functions you can use to send data.
+	//Cayenne.celsiusWrite(1, 22.0);
+	//Cayenne.luxWrite(2, 700);
+	//Cayenne.virtualWrite(3, 50, TYPE_PROXIMITY, UNIT_CENTIMETER);
+}
+
+// Default function for processing actuator commands from the Cayenne Dashboard.
+// You can also use functions for specific channels, e.g CAYENNE_IN(1) for channel 1 commands.
+CAYENNE_IN_DEFAULT()
+{
+	CAYENNE_LOG("Channel %u, value %s", request.channel, getValue.asString());
+	//Process message here. If there is an error set an error message using getValue.setError(), e.g getValue.setError("Error message");
+}
+

library.properties

@@ -1,5 +1,5 @@
 name=CayenneMQTT
-version=1.1.0
+version=1.2.0
 author=myDevices
 maintainer=myDevices
 sentence=Connect a device to the Cayenne dashboard using MQTT.

src/CayenneArduinoDefines.h

@@ -2,7 +2,7 @@
 The MIT License(MIT)
 
 Cayenne Arduino Client Library
-Copyright © 2016 myDevices
+Copyright (c) 2016 myDevices
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 documentation files(the "Software"), to deal in the Software without restriction, including without limitation
@@ -52,7 +52,7 @@ Logging code adapted from Blynk library BlynkDebug.h. Copyright info below.
 		char buffer[12];
 		CAYENNE_PRINT.print('[');
 		CAYENNE_PRINT.print(millis());
-		CAYENNE_PRINT.print(F("] "));
+		CAYENNE_PRINT.print(CAYENNE_FLASH("] "));
 		const char* p = message;
 		size_t n = 0;
 		while (1) {
@@ -127,4 +127,4 @@ Logging code adapted from Blynk library BlynkDebug.h. Copyright info below.
 #include "DetectDevice.h"
 #include "CayenneHandlers.h"
 
-#endif
+#endif