CoogleIOT

Code available on GitHub
Download the code at GitHub

Here at This Smart House, we wouldn’t be able to do many of the things we do without a solid framework for building the controller logic of our IoT devices! Because we generally want things to be Internet-ready so we can control them from our phones, our go-to device is the extremely powerful ESP8266-12E.

Generally speaking all of our IoT devices share a lot in common:

  • We need an easy way to manage their WiFi connection
  • We need an easy way to communicate with an MQTT server
  • We need an easy way to upgrade the firmware, even if the device is buried in a 3D-printed case without physical access
  • We need a way to check what’s going on with a device

For all of these reasons we created CoogleIOT – a ESP8266-12E foundation library that takes care of all of those messy details for us, so when we build something we can focus on the code for that (instead of worrying about all the cookie-cutter details). Here’s what CoogleIOT provides:

  • 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)
  • 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
  • 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
  • Built in OTA firmware update support. Can both upload a new firmware from the UI or pull a new one down from a server
  • Built in Timer allows you to create very clean timings for measurements, et.c (i.e. read sensor every x minutes)

You’ll see CoogleIOT being used all over This Smart House, and since it’s open source you can use it in your projects as well! It’s available through the Arduino IDE as a library to download, or you can just check it out from GitHub.

Looking for Examples? Check out the CoogleIOT Examples page!

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 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:

  // Chaining method calls together
  iot->enableSerial(115200)
     ->initialize();

void CoogleIOT::CoogleIOT(status_led_pin = NULL) The library constructor. You may provide an optional pin to use for a status LED which will be used to indicate different states the device can be in (i.e. WiFi initializing, etc.)

bool CoogleIOT::initialize() Must be called in setup() of your sketch to initialize the library and it’s components

void CoogleIOT::loop() Must be called in loop() of your sketch

CoogleIOT& CoogleIOT::enableSerial(int baud = 115200) Enables Serial output from the IOT library. Will initialize the Serial object for you at the baud rate specified if not already initialized.

PubSubClient* CoogleIOT::getMQTTClient() Return a pointer to the built in PubSubClient to use in your sketch

bool CoogleIOT::serialEnabled() Returns true if Serial is enabled

CoogleIOT& CoogleIOT::flashStatus(speed_in_ms, repeat = 5) Flashes the defined pin / LED at a speed, repeating as defined (5 times by default)

CoogleIOT& CoogleIOT::flashSOS() Flashes the status pin / LED in an SOS pattern (useful to indicate an error)

CoogleIOT& CoogleIOT::resetEEProm() Resets the EEPROM memory used by CoogleIOT to NULL, effectively “factory resetting” the device

void CoogleIOT::restartDevice() Restarts the device. Due to This Bug, you must physically press the restart button on the ESP8266 after flashing via Serial. If you fail to do that, this command will hang the device.

String CoogleIOT::filterAscii() Filters the provided string of anything that is not a printable ASCII character

bool CoogleIOT::verifyFlashConfiguration() Verifies the Flash configuration for the device (what the device supports, vs. what the device is set as in your sketch) is correct.

CoogleIOT& CoogleIOT::syncNTPTime(int offsetSeconds, int daylightOffsetSeconds) Synchronizes and sets the local device date / time based on NTP servers. Must have a working WiFi connection to use this method. The first parameter is the number of seconds local time is offset from UTC time (i.e. -5 hrs in seconds is America/New York). The second parameter is the number of seconds to offset based on daylight savings.

String CoogleIOT::getWiFiStatus() Returns a string representing the current state of the WiFi Client

bool CoogleIOT::mqttActive() Returns true/false indicating if the MQTT client is active and ready to use or not

bool CoogleIOT::dnsActive() Returns true/false if the integrated captive portal DNS is enabled or not

bool CoogleIOT::ntpActive() Returns true/false if the NTP client is online and synchronizing with NTP time servers

bool CoogleIOT::firmwareClientActive() Returns true/false if the periodic firmware client (that will download a new firmware from a web server) is active or not. If active, the Firmware client will check every 30 minutes for a new firmware at the configured URL

bool CoogleIOT::apStatus() Returns true/false if the AP of the device is active or not.

CoogleIOT& CoogleIOT::registerTimer(int interval, callback) Create a callback timer that will call callback (void function with no params) every interval milliseconds. You can turn off the timer by passing 0 as the interval. Useful for taking a sensor reading every X seconds, etc.

void CoogleIOT::checkForFirmwareUpdate() Performs a check against the specified Firmware Server endpoint for a new version of this device’s firmware. If a new version exists it performs the upgrade.

The following getters/setters are pretty self explainatory. Each getter will return a String object of the value from EEPROM (or another primiative data type), with a matching setter:

String CoogleIOT::getRemoteAPName() CoogleIOT& CoogleIOT::setRemoteAPName(String) String CoogleIOT::getRemoteAPPassword() CoogleIOT& CoogleIOT::setRemoteAPPassword(String) String CoogleIOT::getMQTTHostname() CoogleIOT& CoogleIOT::setMQTTHostname(String) String CoogleIOT::getMQTTUsername() CoogleIOT& CoogleIOT::setMQTTUsername(String) String CoogleIOT::getMQTTPassword() CoogleIOT& CoogleIOT::setMQTTPassword(String) String CoogleIOT::getMQTTClientId() CoogleIOT& CoogleIOT::setMQTTClientId() int CoogleIOT::getMQTTPort() CoogleIOT& CoogleIOT::setMQTTPort(int) String CoogleIOT::getAPName() CoogleIOT& CoogleIOT::setAPName(String) String CoogleIOT::getAPPassword() CoogleIOT& CoogleIOT::setAPPassword(String) String CoogleIOT::getFirmwareUpdateUrl() CoogleIOT& CoogleIOT::setFirmwareUpdateUrl(String)

CoogleIOT Firmware Configuration

The Firmware default values and settings are defined in the CoogleIOTConfig.h file and can be overriden by providing new #define statements

#define COOGLEIOT_STATUS_INIT 500 Defines the status LED flash speed in MS for initial initialization

#define COOGLEIOT_STATUS_WIFI_INIT 250 Defines the status LED flash speed for WiFi initialization

#define COOGLEIOT_STATUS_MQTT_INIT 100 Defines the status LED flash speed for MQTT initialization

#define COOGLEIOT_AP "COOGLEIOT_ Defines the prepended string used for the default AP name. The remainder of the AP name will be a randomly generated number (i.e. COOGLEIOT_234934)

#define COOGLEIOT_AP_DEFAULT_PASSWORD "coogleiot" The default AP password

#define COOGLEIOT_DEFAULT_MQTT_CLIENT_ID "coogleIoT" The default MQTT client ID

#define COOGLEIOT_DEFAULT_MQTT_PORT 1883 The default MQTT Port

#define COOGLEIOT_TIMEZONE_OFFSET ((3600 * 5) * -1) The default NTP Timezone offset (America/New York)

#define COOGLEIOT_DAYLIGHT_OFFSET 0 The default NTP Daylight Offset

# define COOGLEIOT_NTP_SERVER_1 "pool.ntp.org" # define COOGLEIOT_NTP_SERVER_2 "time.nist.gov" # define COOGLEIOT_NTP_SERVER_3 "time.google.com"

The three default NTP servers to attempt to synchronize with

#define COOGLEIOT_FIRMWARE_UPDATE_CHECK_MS 54000000 // 15 Minutes in Milliseconds The frequency that we will check for a new Firmware Update if the server is configured. Defaults to 15 minutes.

#define COOGLEIOT_DNS_PORT 53 The default DNS port

#define COOGLE_EEPROM_EEPROM_SIZE 1024 The amount of EEPROM memory allocated to CoogleIOT, 1kb default.

IMPORTANT NOTE: Do NOT reduce this value below it’s default value unless you really know what you are doing, otherwise you will break the firmware.

#define COOGLEIOT_WEBSERVER_PORT 80 The default Webserver port for the configuration system

#define COOGLEIOT_DEBUG If defined, it will enable debugging mode for CoogleIOT which will dump lots of debugging data to the Serial port (if enabled)