ThingSpeak.h

/*
  ThingSpeak(TM) Communication Library For Arduino, ESP8266, and Particle

  Enables an Arduino or other compatible hardware to write or read data to or from ThingSpeak,
  an open data platform for the Internet of Things with MATLAB analytics and visualization. 

  ThingSpeak ( https://www.thingspeak.com ) is an analytic IoT platform service that allows you to aggregate, visualize and 
  analyze live data streams in the cloud.
  
  Copyright 2016, The MathWorks, Inc.
 
  See the accompaning licence file for licensing information.
*/

#ifndef ThingSpeak_h
#define ThingSpeak_h

//#define PRINT_DEBUG_MESSAGES
//#define PRINT_HTTP


#if defined(ARDUINO_ARCH_AVR) || defined(ARDUINO_ARCH_ESP8266) || defined(ARDUINO_ARCH_SAMD) || defined(ARDUINO_ARCH_SAM)
  #include "Arduino.h"
  #include <Client.h>
#else
  #error Only Arduino MKR1000, Yun, Uno/Mega/Due with either WiFi101 or Ethernet shield. ESP8266 also supported.
#endif


#define THINGSPEAK_URL "api.thingspeak.com"
#define THINGSPEAK_IPADDRESS IPAddress(184,106,153,149)
#define THINGSPEAK_PORT_NUMBER 80

#ifdef ARDUINO_ARCH_AVR
    #ifdef ARDUINO_AVR_YUN
        #define TS_USER_AGENT "tslib-arduino/1.0 (arduino yun)"
    #else
        #define TS_USER_AGENT "tslib-arduino/1.0 (arduino uno or mega)"
    #endif
#elif defined(ARDUINO_ARCH_ESP8266)
    #define TS_USER_AGENT "tslib-arduino/1.0 (ESP8266)"
#elif defined(ARDUINO_SAMD_MKR1000)
    #define TS_USER_AGENT "tslib-arduino/1.0 (arduino mkr1000)"
#elif defined(ARDUINO_SAM_DUE)
    #define TS_USER_AGENT "tslib-arduino/1.0 (arduino due)"
#elif defined(ARDUINO_ARCH_SAMD) || defined(ARDUINO_ARCH_SAM)
    #define TS_USER_AGENT "tslib-arduino/1.0 (arduino unknown sam or samd)"
#else
    #error "Platform not supported"
#endif

#define FIELDNUM_MIN 1
#define FIELDNUM_MAX 8
#define FIELDLENGTH_MAX 255  // Max length for a field in ThingSpeak is 255 bytes (UTF-8)

#define TIMEOUT_MS_SERVERRESPONSE 5000  // Wait up to five seconds for server to respond

#define OK_SUCCESS              200     // OK / Success
#define ERR_BADAPIKEY           400     // Incorrect API key (or invalid ThingSpeak server address)
#define ERR_BADURL              404     // Incorrect API key (or invalid ThingSpeak server address)
#define ERR_OUT_OF_RANGE        -101    // Value is out of range or string is too long (> 255 bytes)
#define ERR_INVALID_FIELD_NUM   -201    // Invalid field number specified
#define ERR_SETFIELD_NOT_CALLED -210    // setField() was not called before writeFields()
#define ERR_CONNECT_FAILED      -301    // Failed to connect to ThingSpeak
#define ERR_UNEXPECTED_FAIL     -302    // Unexpected failure during write to ThingSpeak
#define ERR_BAD_RESPONSE        -303    // Unable to parse response
#define ERR_TIMEOUT             -304    // Timeout waiting for server to respond
#define ERR_NOT_INSERTED        -401    // Point was not inserted (most probable cause is the rate limit of once every 15 seconds)

class ThingSpeakClass
{
  public:
    ThingSpeakClass()
    {
        resetWriteFields();
        this->lastReadStatus = OK_SUCCESS;
    };

    bool begin(Client & client, const char * customHostName, unsigned int port)
    {
#ifdef PRINT_DEBUG_MESSAGES
        Serial.print("ts::tsBegin    (client: Client URL: "); Serial.print(customHostName); Serial.println(")");
#endif
    this->setClient(&client);
    this->setServer(customHostName, port);
    resetWriteFields();
    this->lastReadStatus = OK_SUCCESS;
    return true;
    };

    bool begin(Client & client, IPAddress customIP, unsigned int port)
    {
#ifdef PRINT_DEBUG_MESSAGES
        Serial.print("ts::tsBegin    (client: Client IP: "); Serial.print(customIP); Serial.println(")");
#endif
        this->setClient(&client);
        this->setServer(customIP, port);
        resetWriteFields();
        this->lastReadStatus = OK_SUCCESS;
        return true;
    };

    bool begin(Client & client)
    {
#ifdef PRINT_DEBUG_MESSAGES
        Serial.print("ts::tsBegin");
#endif
        this->setClient(&client);
        this->setServer();
        resetWriteFields();
        this->lastReadStatus = OK_SUCCESS;
        return true;
    };
    
    int writeField(unsigned long channelNumber, unsigned int field, int value, const char * writeAPIKey)
    {
        char valueString[10];  // int range is -32768 to 32768, so 7 bytes including terminator, plus a little extra
        itoa(value, valueString, 10);
        return writeField(channelNumber, field, valueString, writeAPIKey);
    };

    int writeField(unsigned long channelNumber, unsigned int field, long value, const char * writeAPIKey)
    {
        char valueString[15];  // long range is -2147483648 to 2147483647, so 12 bytes including terminator
        ltoa(value, valueString, 10);
        return writeField(channelNumber, field, valueString, writeAPIKey);
    };

    int writeField(unsigned long channelNumber, unsigned int field, float value, const char * writeAPIKey)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::writeField (channelNumber: "); Serial.print(channelNumber); Serial.print(" writeAPIKey: "); Serial.print(writeAPIKey); Serial.print(" field: "); Serial.print(field); Serial.print(" value: "); Serial.print(value,5); Serial.println(")");
        #endif
        char valueString[20]; // range is -999999000000.00000 to 999999000000.00000, so 19 + 1 for the terminator
        int status = convertFloatToChar(value, valueString);
        if(status != OK_SUCCESS) return status;

        return writeField(channelNumber, field, valueString, writeAPIKey);
    };

    int writeField(unsigned long channelNumber, unsigned int field, const char * value, const char * writeAPIKey)
    {
        return writeField(channelNumber, field, String(value), writeAPIKey);
    };

    int writeField(unsigned long channelNumber, unsigned int field, String value, const char * writeAPIKey)
    {
        // Invalid field number specified
        if(field < FIELDNUM_MIN || field > FIELDNUM_MAX) return ERR_INVALID_FIELD_NUM;
        // Max # bytes for ThingSpeak field is 255
        if(value.length() > FIELDLENGTH_MAX) return ERR_OUT_OF_RANGE;
        
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::writeField (channelNumber: "); Serial.print(channelNumber); Serial.print(" writeAPIKey: "); Serial.print(writeAPIKey); Serial.print(" field: "); Serial.print(field); Serial.print(" value: \""); Serial.print(value); Serial.println("\")");
        #endif
        String postMessage = String("field") + String(field) + "=" + value;
        return writeRaw(channelNumber, postMessage, writeAPIKey);
    };

    
    int setField(unsigned int field, int value)
    {

        char valueString[10];  // int range is -32768 to 32768, so 7 bytes including terminator
        itoa(value, valueString, 10);
        
        return setField(field, valueString);

    };

    int setField(unsigned int field, long value)
    {
        char valueString[15];  // long range is -2147483648 to 2147483647, so 12 bytes including terminator
        ltoa(value, valueString, 10);
        return setField(field, valueString);
    };


    int setField(unsigned int field, float value)
    {
        char valueString[20]; // range is -999999000000.00000 to 999999000000.00000, so 19 + 1 for the terminator
        int status = convertFloatToChar(value, valueString);
        if(status != OK_SUCCESS) return status;

        return setField(field, valueString);
    };

    int setField(unsigned int field, const char * value)
    {
        return setField(field, String(value));
    };

    int setField(unsigned int field, String value)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::setField   (field: "); Serial.print(field); Serial.print(" value: \""); Serial.print(value); Serial.println("\")");
        #endif
        if(field < FIELDNUM_MIN || field > FIELDNUM_MAX) return ERR_INVALID_FIELD_NUM;
        // Max # bytes for ThingSpeak field is 255 (UTF-8)
        if(value.length() > FIELDLENGTH_MAX) return ERR_OUT_OF_RANGE;
        this->nextWriteField[field - 1] = value;
        return OK_SUCCESS;
    };


    int setLatitude(float latitude)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::setLatitude(latitude: "); Serial.print(latitude,3); Serial.println("\")");
        #endif
        this->nextWriteLatitude = latitude;
        return OK_SUCCESS;
    };


    int setLongitude(float longitude)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::setLongitude(longitude: "); Serial.print(longitude,3); Serial.println("\")");
        #endif
        this->nextWriteLongitude = longitude;
        return OK_SUCCESS;
    };


    int setElevation(float elevation)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::setElevation(elevation: "); Serial.print(elevation,3); Serial.println("\")");
        #endif
        this->nextWriteElevation = elevation;
        return OK_SUCCESS;
    };


    int writeFields(unsigned long channelNumber, const char * writeAPIKey)
    {
        String postMessage = String("");
        bool fFirstItem = true;
        for(size_t iField = 0; iField < 8; iField++)
        {
            if(this->nextWriteField[iField].length() > 0)
            {
                if(!fFirstItem)
                {
                    postMessage = postMessage + String("&");
                }
                postMessage = postMessage + String("field") + String(iField + 1) + String("=") + this->nextWriteField[iField];
                fFirstItem = false;
                this->nextWriteField[iField] = "";
            }
        }

        if(!isnan(nextWriteLatitude))
        {
            if(!fFirstItem)
            {
                postMessage = postMessage + String("&");
            }
            postMessage = postMessage + String("lat=") + String(this->nextWriteLatitude);
            fFirstItem = false;
            this->nextWriteLatitude = NAN;
        }

        if(!isnan(this->nextWriteLongitude))
        {
            if(!fFirstItem)
            {
                postMessage = postMessage + String("&");
            }
            postMessage = postMessage + String("long=") + String(this->nextWriteLongitude);
            fFirstItem = false;
            this->nextWriteLongitude = NAN;
        }


        if(!isnan(this->nextWriteElevation))
        {
            if(!fFirstItem)
            {
                postMessage = postMessage + String("&");
            }
            postMessage = postMessage + String("elevation=") + String(this->nextWriteElevation);
            fFirstItem = false;
            this->nextWriteElevation = NAN;
        }

        if(fFirstItem)
        {
            // setField was not called before writeFields
            return ERR_SETFIELD_NOT_CALLED;
        }

        return writeRaw(channelNumber, postMessage, writeAPIKey);
    };


    int writeRaw(unsigned long channelNumber, const char * postMessage, const char * writeAPIKey)
    {
        return writeRaw(channelNumber, String(postMessage), writeAPIKey);
    };


    int writeRaw(unsigned long channelNumber, String postMessage, const char * writeAPIKey)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::writeRaw   (channelNumber: "); Serial.print(channelNumber); Serial.print(" writeAPIKey: "); Serial.print(writeAPIKey); Serial.print(" postMessage: \""); Serial.print(postMessage); Serial.println("\")");
        #endif

        if(!connectThingSpeak())
        {
            // Failed to connect to ThingSpeak
            return ERR_CONNECT_FAILED;
        }

        postMessage = postMessage + String("&headers=false");

        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("               POST \"");Serial.print(postMessage);Serial.println("\"");
        #endif

        postMessage = postMessage + String("\n");

        // Post data to thingspeak
        if(!this->client->print("POST /update HTTP/1.1\n")) return abortWriteRaw();
        if(!writeHTTPHeader(writeAPIKey)) return abortWriteRaw();
        if(!this->client->print("Content-Type: application/x-www-form-urlencoded\n")) return abortWriteRaw();
        if(!this->client->print("Content-Length: ")) return abortWriteRaw();
        if(!this->client->print(postMessage.length())) return abortWriteRaw();
        if(!this->client->print("\n\n")) return abortWriteRaw();
        if(!this->client->print(postMessage)) return abortWriteRaw();
  
        String entryIDText = String();
        int status = getHTTPResponse(entryIDText);
        if(status != OK_SUCCESS)
        {
            client->stop();
            return status;
        }
        long entryID = entryIDText.toInt();

        #ifdef PRINT_DEBUG_MESSAGES
        Serial.print("               Entry ID \"");Serial.print(entryIDText);Serial.print("\" (");Serial.print(entryID);Serial.println(")");
        #endif

        client->stop();
        
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.println("disconnected.");
        #endif
        if(entryID == 0)
        {
            // ThingSpeak did not accept the write
            status = ERR_NOT_INSERTED;
        }
        return status;
    };
    
    String readStringField(unsigned long channelNumber, unsigned int field, const char * readAPIKey)
    {
        if(field < FIELDNUM_MIN || field > FIELDNUM_MAX)
        {
            this->lastReadStatus = ERR_INVALID_FIELD_NUM;
            return("");
        }
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::readStringField(channelNumber: "); Serial.print(channelNumber); 
            if(NULL != readAPIKey)
            {
                Serial.print(" readAPIKey: "); Serial.print(readAPIKey);
            }
            Serial.print(" field: "); Serial.print(field); Serial.println(")");
        #endif
        return readRaw(channelNumber, String(String("/fields/") + String(field) + String("/last")), readAPIKey);
    }


    String readStringField(unsigned long channelNumber, unsigned int field)
    {
        return readStringField(channelNumber, field, NULL);
    };


    float readFloatField(unsigned long channelNumber, unsigned int field, const char * readAPIKey)
    {
        return convertStringToFloat(readStringField(channelNumber, field, readAPIKey));
    };


    float readFloatField(unsigned long channelNumber, unsigned int field)
    {
        return readFloatField(channelNumber, field, NULL);
    };


    long readLongField(unsigned long channelNumber, unsigned int field, const char * readAPIKey)
    {
        // Note that although the function is called "toInt" it really returns a long.
        return readStringField(channelNumber, field, readAPIKey).toInt();
    }


    long readLongField(unsigned long channelNumber, unsigned int field)
    {
        return readLongField(channelNumber, field, NULL);
    };


    int readIntField(unsigned long channelNumber, unsigned int field, const char * readAPIKey)
    {
        return readLongField(channelNumber, field, readAPIKey);
    }


    int readIntField(unsigned long channelNumber, unsigned int field)
    {
        return readLongField(channelNumber, field, NULL);
    };
    
    String readRaw(unsigned long channelNumber, String URLSuffix)
    {
        return readRaw(channelNumber, URLSuffix, NULL);
    }
    
    String readRaw(unsigned long channelNumber, String URLSuffix, const char * readAPIKey)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::readRaw   (channelNumber: "); Serial.print(channelNumber);
            if(NULL != readAPIKey)
            {
                Serial.print(" readAPIKey: "); Serial.print(readAPIKey);
            }
            Serial.print(" URLSuffix: \""); Serial.print(URLSuffix); Serial.println("\")");
        #endif

        if(!connectThingSpeak())
        {
            this->lastReadStatus = ERR_CONNECT_FAILED;
            return String("");
        }

        String URL = String("/channels/") + String(channelNumber) + URLSuffix;

        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("               GET \"");Serial.print(URL);Serial.println("\"");
        #endif

        // Post data to thingspeak
        if(!this->client->print("GET ")) return abortReadRaw();
        if(!this->client->print(URL)) return abortReadRaw();
        if(!this->client->print(" HTTP/1.1\n")) return abortReadRaw();
        if(!writeHTTPHeader(readAPIKey)) return abortReadRaw();
        if(!this->client->print("\n")) return abortReadRaw();
 
        String content = String();
        int status = getHTTPResponse(content);
            
        this->lastReadStatus = status;


        #ifdef PRINT_DEBUG_MESSAGES
            if(status == OK_SUCCESS)
            {
                Serial.print("Read: \""); Serial.print(content); Serial.println("\"");
            }
        #endif

        client->stop();
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.println("disconnected.");
        #endif

        if(status != OK_SUCCESS)
        {
            // return status;
            return String("");
        }

        // This is a workaround to a bug in the Spark implementation of String
        return String("") + content;
    };
    
    int getLastReadStatus()
    {
        return this->lastReadStatus;
    };
private:

    int abortWriteRaw()
    {
        this->client->stop();
        return ERR_UNEXPECTED_FAIL;
    }

    String abortReadRaw()
    {
        this->client->stop();
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.println("ReadRaw abort - disconnected.");
        #endif
        this->lastReadStatus = ERR_UNEXPECTED_FAIL;
        return String("");
    }

    void setServer(const char * customHostName, unsigned int port)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::setServer  (URL: \""); Serial.print(customHostName); Serial.println("\")");
        #endif
        this->customIP = INADDR_NONE;
        this->customHostName = customHostName;
        this->port = port;
    };

    void setServer(IPAddress customIP, unsigned int port)
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::setServer  (IP: \""); Serial.print(customIP); Serial.println("\")");
        #endif
        this->customIP = customIP;
        this->customHostName = NULL;
        this->port = port;
    };

    void setServer()
    {
        #ifdef PRINT_DEBUG_MESSAGES
            Serial.print("ts::setServer  (default)");
        #endif
        this->customIP = INADDR_NONE;
        this->customHostName = NULL;
        this->port = THINGSPEAK_PORT_NUMBER;
    };

    void setClient(Client * client) {this->client = client;};

    Client * client = NULL;
    const char * customHostName = NULL;
    IPAddress customIP = INADDR_NONE;
    unsigned int port = THINGSPEAK_PORT_NUMBER;
    String nextWriteField[8];
    float nextWriteLatitude;
    float nextWriteLongitude;
    float nextWriteElevation;
    int lastReadStatus;

    bool connectThingSpeak()
    {
        bool connectSuccess = false;
        if(this->customIP == INADDR_NONE && NULL == this->customHostName)
        {
            #ifdef PRINT_DEBUG_MESSAGES
                Serial.print("               Connect to default ThingSpeak URL...");
            #endif
            connectSuccess = client->connect(THINGSPEAK_URL,THINGSPEAK_PORT_NUMBER);
            if(!connectSuccess)
            {
                #ifdef PRINT_DEBUG_MESSAGES
                    Serial.print("Failed. Try default IP...");
                #endif
                connectSuccess = client->connect(THINGSPEAK_IPADDRESS,THINGSPEAK_PORT_NUMBER);
            }
       }
       else
       {
            if(!(this->customIP == INADDR_NONE))
            {
                // Connect to the server on port 80 (HTTP) at the customIP address
                #ifdef PRINT_DEBUG_MESSAGES
                  Serial.print("               Connect to ");Serial.print(this->customIP);Serial.print("...");
                #endif
                connectSuccess = client->connect(this->customIP,this->port);
            }
            if(NULL != this->customHostName)
            {
                // Connect to the server on port 80 (HTTP) at the URL address
                #ifdef PRINT_DEBUG_MESSAGES
                    Serial.print("               Connect to ");Serial.print(this->customHostName);Serial.print(" ...");
                #endif
                connectSuccess = client->connect(customHostName,this->port);
            }
        }

        #ifdef PRINT_DEBUG_MESSAGES
        if (connectSuccess)
        {
            Serial.println("Success.");
        }
        else
        {
            Serial.println("Failed.");
        }
        #endif
        return connectSuccess;
    };

    bool writeHTTPHeader(const char * APIKey)
    {
        if(NULL != this->customHostName)
        {
            if (!this->client->print("Host: ")) return false;
            if (!this->client->print(this->customHostName)) return false;
            if (!this->client->print("\n")) return false;
        }
        else
        {
            if (!this->client->print("Host: api.thingspeak.com\n")) return false;
        }
        if (!this->client->print("Connection: close\n")) return false;
        if (!this->client->print("User-Agent: ")) return false;
        if (!this->client->print(TS_USER_AGENT)) return false;
        if (!this->client->print("\n")) return false;
        if(NULL != APIKey)
        {
            if (!this->client->print("X-THINGSPEAKAPIKEY: ")) return false;
            if (!this->client->print(APIKey)) return false;
            if (!this->client->print("\n")) return false;
        }
        return true;
    };

    int getHTTPResponse(String & response)
    {
        long startWaitForResponseAt = millis();
        while(client->available() == 0 && millis() - startWaitForResponseAt < TIMEOUT_MS_SERVERRESPONSE)
        {
            delay(100);
        }
        if(client->available() == 0)
        {
            return ERR_TIMEOUT; // Didn't get server response in time
        }

        if(!client->find(const_cast<char *>("HTTP/1.1")))
        {
            #ifdef PRINT_HTTP
                Serial.println("ERROR: Didn't find HTTP/1.1");
            #endif
            return ERR_BAD_RESPONSE; // Couldn't parse response (didn't find HTTP/1.1)
        }
        int status = client->parseInt();
        #ifdef PRINT_HTTP
            Serial.print("Got Status of ");Serial.println(status);
        #endif
        if(status != OK_SUCCESS)
        {
            return status;
        }

        if(!client->find(const_cast<char *>("\r\n")))
        {
            #ifdef PRINT_HTTP
                Serial.println("ERROR: Didn't find end of status line");
            #endif
            return ERR_BAD_RESPONSE;
        }
        #ifdef PRINT_HTTP
            Serial.println("Found end of status line");
        #endif

        if(!client->find(const_cast<char *>("\n\r\n")))
        {
            #ifdef PRINT_HTTP
                Serial.println("ERROR: Didn't find end of header");
            #endif
            return ERR_BAD_RESPONSE;
        }
        #ifdef PRINT_HTTP
            Serial.println("Found end of header");
        #endif
        // This is a workaround to a bug in the Spark implementation of String
        String tempString = client->readStringUntil('\r');
        response = tempString;
        #ifdef PRINT_HTTP
            Serial.print("Response: \"");Serial.print(response);Serial.println("\"");
        #endif
        return status;
    };

    int convertFloatToChar(float value, char *valueString)
    {
        // Supported range is -999999000000 to 999999000000
        if(0 == isinf(value) && (value > 999999000000 || value < -999999000000))
        {
            // Out of range
            return ERR_OUT_OF_RANGE;
        }
        // assume that 5 places right of decimal should be sufficient for most applications

        #if defined(ARDUINO_ARCH_SAMD) || defined(ARDUINO_ARCH_SAM)
          sprintf(valueString, "%.5f", value);
        #else
          dtostrf(value,1,5, valueString);
        #endif
        return OK_SUCCESS;
    };

    float convertStringToFloat(String value)
    {
        // There's a bug in the AVR function strtod that it doesn't decode -INF correctly (it maps it to INF)
        float result = value.toFloat();
        if(1 == isinf(result) && *value.c_str() == '-')
        {
            result = (float)-INFINITY;
        }
        return result;
    };

    void resetWriteFields()
    {
        for(size_t iField = 0; iField < 8; iField++)
        {
            this->nextWriteField[iField] = "";
        }
        this->nextWriteLatitude = NAN;
        this->nextWriteLongitude = NAN;
        this->nextWriteElevation = NAN;
    };
};

extern ThingSpeakClass ThingSpeak;

#endif //ThingSpeak_h