Merge branch 'master' of https://github.com/coogle/CoogleIOT

README.md

@@ -5,12 +5,11 @@ A ESP8266-12 Library for easy IOT device development.
 The CoogleIOT library was created to make building IOT devices on the ESP8266-12 microcontroller easier by providing a
 solid encapsulated framework for most of the common things you want to do on an IOT device, including:
 
-- Captive Portal for configuration of the device - allowing you to configure the AP name, the Wifi Client, and the built in MQTT Client. 
+- Captive Portal for configuration of the device - allowing you to configure the AP name, the Wifi Client, and the built in MQTT Client. Just connect to the AP and configure (mobile friendly).
 - Built in persistent logging mechanisms using SPIFFS filesystem (also available for viewing from the web interface)
-  Just connect to the AP and configure (mobile friendly).
 - Built in MQTT client (provided by PubSubClient) 
 - Built in UI libraries for the device (Mini.css for style, jquery 3.x for Javascript) that can be served from the AP
-  using the /css or /jquery URLs
+  using the `/css` or `/jquery` URLs
 - Built in NTP client for access to local date / time on device
 - Built in DNS Server during configuration for captive portal support when connected to the device as an AP directly
 - Built in Security-minded tools like HTML Escaping and other filters to prevent malicious inputs
@@ -39,7 +38,7 @@ Status Page
 
 CoogleIOT is designed to hang out in the background so your sketches are focused on the things you actually want to
 work on without having to worry about things like WiFi or MQTT clients. Here is an example of using it to control a
-Garage Door w/open and close sensors
+Garage Door w/open and close sensors:
 
 ```
 /* GarageDoor-Opener.h */
@@ -237,6 +236,31 @@ void mqttCallbackHandler(char *topic, byte *payload, unsigned int length)
 
 ```
 
+There are other projects that use this library which serve as great examples of it's use as well. You should probably check out these:
+
+[Coogle Switch](https://github.com/ThisSmartHouse/coogle-switch) - A CoogleIOT-powered ESP8266-12 sketch for creating smart switches that operate over MQTT (controlling a relay module of configured sized). Just set up which pins your relay operates on and it takes care of all the MQTT topics, etc. you need for it to work.
+
+## Where's my Device?
+
+When MQTT is enabled, CoogleIOT automatically sends a periodic heartbeat message to `/coogleiot/devices/<client_id>` containing a JSON payload with useful information:
+
+```
+{ 
+    "timestamp" : "2017-10-27 05:27:13", 
+    "ip" : "192.168.1.130", 
+    "coogleiot_version" : "1.2.1", 
+    "client_id" : "bbq-temp-probe" 
+}
+```
+
+If running multiple CoogleIOT devices this can be very useful to keep track of them all by just subscribing to the `/coogleiot/devices/#` wildcard channel which will capture all the heartbeat transmissions.
+
+## MQTT Client Notes
+
+Presently, due to [This Issue](https://github.com/knolleary/pubsubclient/issues/110) in the MQTT client used by CoogleIOT it is important that you compile your sketches using the `MQTT_MAX_PACKET_SIZE` flag set to a reasonable value (we recommend 512). Without this flag, larger MQTT packets (i.e. long topic names) will not be sent properly. 
+
+Please consult your build envrionment's documentation on how to set this compile-time variable. (hint: `-DMQTT_MAX_PACKET_SIZE 512` works)
+
 ## API
 
 CoogleIOT is an evolving code base, so this API may change before this document is updated to reflect that. The best source is the source. When possible CoogleIOT uses a fluent interface, allowing you to chain method calls together: