diff --git a/src/ThingSpeak.h b/src/ThingSpeak.h index f21b71b..814cca8 100644 --- a/src/ThingSpeak.h +++ b/src/ThingSpeak.h @@ -12,56 +12,19 @@ See the accompaning licence file for licensing information. */ -/** - @mainpage - * - * \ref ThingSpeakClass "For technical documentation, visit this page" - * - * ThingSpeak offers free data storage and analysis of time-stamped numeric or alphanumeric data. - * Users can access ThingSpeak by visiting http://thingspeak.com and creating a ThingSpeak user account. - * - * ThingSpeak stores data in channels. Channels support an unlimited number of timestamped observations (think of these as rows in a spreadsheet). - * Each channel has up to 8 fields (think of these as columns in a speadsheet). Check out this video for an overview. - * - * Channels may be public, where anyone can see the data, or private, where only the owner and select users can read the data. - * Each channel has an associated Write API Key that is used to control who can write to a channel. - * In addition, private channels have one or more Read API Keys to control who can read from private channel. - * An API Key is not required to read from public channels. Each channel can have up to 8 fields. One field is created by default. - * - * You can visualize and do online analytics of your data on ThingSpeak using the built in version of MATLAB, or use the desktop version of MATLAB to get - * deeper historical insight. Visit https://www.mathworks.com/hardware-support/thingspeak.html to learn more. - * - *

Compatible Hardware

- * * Arduino/Genuino or compatible using a WiFi Shield, WiFi Shield 101 or Ethernet Shield or MKR ETH Shield (we have tested with Uno and Mega) - * * Arduino Yún and Yún Rev2 running OpenWRT-Yun Release 1.5.3 (November 13th, 2014) or later. There are known issues with earlier versions. Visit [this page](http://www.arduino.cc/en/Main/Software) to get the latest version. - * * Arduino MKR1000 - * * Arduino GSM 1400 - * * Arduino VIDOR 4000 - * * Arduino MKR1010 - * * ESP32 (tested with SparkFun ESP32 Thing) - * * ESP8266 (tested with SparkFun ESP8266 Thing - Dev Board and NodeMCU 1.0 module) - * * SparkFun ESP32 Thing - * - *

Examples

- * The library includes several examples to help you get started. These are accessible in Examples > ThingSpeak menu of the Arduino IDE. - * * ReadField: Reading from a public channel and a private channel on ThingSpeak. - * * WriteSingleField: Writing a value to a single field on ThingSpeak. - * * WriteMultipleFields: Writing values to multiple fields and status in one transaction with ThingSpeak. - */ +// #define PRINT_DEBUG_MESSAGES +// #define PRINT_HTTP #ifndef ThingSpeak_h #define ThingSpeak_h -#define TS_VER "1.4" +#define TS_VER "1.5" -//#define PRINT_DEBUG_MESSAGES -//#define PRINT_HTTP #include "Arduino.h" #include #define THINGSPEAK_URL "api.thingspeak.com" -#define THINGSPEAK_IPADDRESS IPAddress(184,106,153,149) #define THINGSPEAK_PORT_NUMBER 80 #ifdef ARDUINO_ARCH_AVR @@ -108,9 +71,7 @@ #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) -/** - * @brief Enables an Arduino, ESP8266, ESP32 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. - */ +// Enables an Arduino, ESP8266, ESP32 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. class ThingSpeakClass { public: @@ -120,119 +81,86 @@ class ThingSpeakClass this->lastReadStatus = OK_SUCCESS; }; - /** - * @brief Initializes the ThingSpeak library and network settings using a custom installation of ThingSpeak. - * @param client EthernetClient, YunClient, TCPClient, or WiFiClient created earlier in the sketch - * @param customHostName Host name of a custom install of ThingSpeak - * @param port Port number to use with a custom install of ThingSpeak - * @return Always returns true - * @comment This does not validate the information passed in, or generate any calls to ThingSpeak. - * @code - #include - #include - byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED}; - EthernetClient client; - - #include "ThingSpeak.h" - - void setup() { - Ethernet.begin(mac); - ThingSpeak.begin(client,"api.thingspeak.com", 80); - } - * @endcode - */ - 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; - }; - /** - * @brief Initializes the ThingSpeak library and network settings using a custom installation of ThingSpeak. - * @param client EthernetClient, YunClient, TCPClient, or WiFiClient created earlier in the sketch - * @param customIP IP address of a custom install of ThingSpeak - * @param port Port number to use with a custom install of ThingSpeak - * @return Always returns true - * @comment This does not validate the information passed in, or generate any calls to ThingSpeak. - * @code - #include - #include - byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED}; - EthernetClient client; - - #include "ThingSpeak.h" - - void setup() { - Ethernet.begin(mac); - ThingSpeak.begin(client,IPAddress(184,106,153,149), 80); - } - * @endcode - */ - bool begin(Client & client, IPAddress customIP, unsigned int port) + /* + Function: begin + + Summary: + Initializes the ThingSpeak library and network settings using the ThingSpeak.com service. + + Parameters: + client - EthernetClient, YunClient, TCPClient, or WiFiClient created earlier in the sketch + + Returns: + Always returns true + + Notes: + This does not validate the information passed in, or generate any calls to ThingSpeak. + + */ + bool begin(Client & client) { -#ifdef PRINT_DEBUG_MESSAGES - Serial.print("ts::tsBegin (client: Client IP: "); Serial.print(customIP); Serial.println(")"); -#endif + + #ifdef PRINT_DEBUG_MESSAGES + Serial.println("ts::tsBegin"); + #endif this->setClient(&client); - this->setServer(customIP, port); + this->setPort(THINGSPEAK_PORT_NUMBER); + resetWriteFields(); this->lastReadStatus = OK_SUCCESS; + return true; }; + + /* + Function: begin + + Summary: + Initializes the ThingSpeak library and network settings using the ThingSpeak.com service. + + Parameters: + client - EthernetClient, YunClient, TCPClient, or WiFiClient created earlier in the sketch + port - TCP port of server + + Returns: + Always returns true + + Notes: + This does not validate the information passed in, or generate any calls to ThingSpeak. - /** - * @brief Initializes the ThingSpeak library and network settings using the ThingSpeak.com service. - * @param client EthernetClient, YunClient, TCPClient, or WiFiClient created earlier in the sketch - * @return Always returns true - * @comment This does not validate the information passed in, or generate any calls to ThingSpeak. - * @code - #include - #include - byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED}; - EthernetClient client; - - #include "ThingSpeak.h" - - void setup() { - Ethernet.begin(mac); - ThingSpeak.begin(client); - } - * @endcode - */ - bool begin(Client & client) + */ + bool begin(Client & client, unsigned int port) { -#ifdef PRINT_DEBUG_MESSAGES - Serial.print("ts::tsBegin"); -#endif + #ifdef PRINT_DEBUG_MESSAGES + Serial.print("ts::tsBegin"); + #endif this->setClient(&client); - this->setServer(); + this->setPort(port); resetWriteFields(); this->lastReadStatus = OK_SUCCESS; - return true; + return true; }; - /** - * @brief Write an integer value to a single field in a ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to write to. - * @param value Integer value (from -32,768 to 32,767) to write. - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Visit https://thingspeak.com/docs/channels for more information about channels, API keys, and fields. ThingSpeak limits the number of writes to a channel to once every 15 seconds. - * @code - void loop() { - int sensorValue = analogRead(A0); - ThingSpeak.writeField(myChannelNumber, 1, sensorValue, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: writeField + + Summary: + Write an integer value to a single field in a ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to write to. + value - Integer value (from -32,768 to 32,767) to write. + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + HTTP status code of 200 if successful. + + Notes: + See getLastReadStatus() for other possible return values. + */ 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 @@ -240,46 +168,50 @@ class ThingSpeakClass return writeField(channelNumber, field, valueString, writeAPIKey); }; - /** - * @brief Write a long value to a single field in a ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to write to. - * @param value Long value (from -2,147,483,648 to 2,147,483,647) to write. - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Visit https://thingspeak.com/docs/channels for more information about channels, API keys, and fields. ThingSpeak limits the number of writes to a channel to once every 15 seconds. - * @code - void loop() { - int sensorValue = analogRead(A0); - ThingSpeak.writeField(myChannelNumber, 1, sensorValue, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: writeField + + Summary: + Write a long value to a single field in a ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to write to. + value - Long value (from -2,147,483,648 to 2,147,483,647) to write. + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + HTTP status code of 200 if successful. + + Notes: + See getLastReadStatus() for other possible return values. + */ 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); }; - - /** - * @brief Write a floating point value to a single field in a ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to write to. - * @param value Floating point value (from -999999000000 to 999999000000) to write. If you need more accuracy, or a wider range, you should format the number using dtostrf and writeField(). - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Visit https://thingspeak.com/docs/channels for more information about channels, API keys, and fields. ThingSpeak limits the number of writes to a channel to once every 15 seconds. - * @code - void loop() { - int sensorValue = analogRead(A0); - float voltage = sensorValue * (5.0 / 1023.0); - ThingSpeak.writeField(myChannelNumber, 1, voltage, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: writeField + + Summary: + Write a floating point value to a single field in a ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to write to. + value - Floating point value (from -999999000000 to 999999000000) to write. If you need more accuracy, or a wider range, you should format the number using dtostrf and writeField(). + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + HTTP status code of 200 if successful. + + Notes: + See getLastReadStatus() for other possible return values. + */ int writeField(unsigned long channelNumber, unsigned int field, float value, const char * writeAPIKey) { #ifdef PRINT_DEBUG_MESSAGES @@ -292,56 +224,48 @@ class ThingSpeakClass return writeField(channelNumber, field, valueString, writeAPIKey); }; - /** - * @brief Write a string to a single field in a ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to write to. - * @param value String to write (UTF8 string). ThingSpeak limits this field to 255 bytes. - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Visit https://thingspeak.com/docs/channels for more information about channels, API keys, and fields. ThingSpeak limits the number of writes to a channel to once every 15 seconds. - * @code - void loop() { - int sensorValue = analogRead(A0); - if (sensorValue > 512) { - ThingSpeak.writeField(myChannelNumber, 1, "High", myWriteAPIKey); - } - else { - ThingSpeak.writeField(myChannelNumber, 1, "Low", myWriteAPIKey); - } - delay(20000); - } - * @endcode - */ + + /* + Function: writeField + + Summary: + Write a string to a single field in a ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to write to. + value - String to write (UTF8 string). ThingSpeak limits this field to 255 bytes. + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + HTTP status code of 200 if successful. + + Notes: + See getLastReadStatus() for other possible return values. + */ int writeField(unsigned long channelNumber, unsigned int field, const char * value, const char * writeAPIKey) { return writeField(channelNumber, field, String(value), writeAPIKey); }; - - /** - * @brief Write a String to a single field in a ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to write to. - * @param value Character array (zero terminated) to write (UTF8). ThingSpeak limits this field to 255 bytes. - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Visit https://thingspeak.com/docs/channels for more information about channels, API keys, and fields. ThingSpeak limits the number of writes to a channel to once every 15 seconds. - * @code - void loop() { - int sensorValue = analogRead(A0); - String meaning; - if (sensorValue < 400) { - meaning = String("Too Cold!"); - } else if (sensorValue > 600) { - meaning = String("Too Hot!"); - } else { - meaning = String("Just Right"); - } - ThingSpeak.writeField(myChannelNumber, 1, meaning, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: writeField + + Summary: + Write a string to a single field in a ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to write to. + value - String to write (UTF8 string). ThingSpeak limits this field to 255 bytes. + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + HTTP status code of 200 if successful. + + Notes: + See getLastReadStatus() for other possible return values. + */ int writeField(unsigned long channelNumber, unsigned int field, String value, const char * writeAPIKey) { // Invalid field number specified @@ -356,38 +280,22 @@ class ThingSpeakClass return writeRaw(channelNumber, postMessage, writeAPIKey); }; - - /** - * @brief Set the value of a single field that will be part of a multi-field update. - * To write multiple fields at once, call setField() for each of the fields you want to write, and then call writeFields() - * @param field Field number (1-8) within the channel to set - * @param value Integer value (from -32,768 to 32,767) to set. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setLatitude(), setLongitude(), setElevation(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setField + + Summary: + Set the value of a single field that will be part of a multi-field update. + + Parameters: + field - Field number (1-8) within the channel to set. + value - Integer value (from -32,768 to 32,767) to set. + + Returns: + Code of 200 if successful. + Code of -101 if value is out of range or string is too long (> 255 bytes) + + */ int setField(unsigned int field, int value) { @@ -397,38 +305,22 @@ class ThingSpeakClass return setField(field, valueString); }; - - /** - * @brief Set the value of a single field that will be part of a multi-field update. - * To write multiple fields at once, call setField() for each of the fields you want to write, and then call writeFields() - * @param field Field number (1-8) within the channel to set - * @param value Long value (from -2,147,483,648 to 2,147,483,647) to write. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setLatitude(), setLongitude(), setElevation(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setField + + Summary: + Set the value of a single field that will be part of a multi-field update. + + Parameters: + field - Field number (1-8) within the channel to set. + value - Long value (from -2,147,483,648 to 2,147,483,647) to write. + + Returns: + Code of 200 if successful. + Code of -101 if value is out of range or string is too long (> 255 bytes) + + */ int setField(unsigned int field, long value) { char valueString[15]; // long range is -2147483648 to 2147483647, so 12 bytes including terminator @@ -436,38 +328,21 @@ class ThingSpeakClass return setField(field, valueString); }; - - /** - * @brief Set the value of a single field that will be part of a multi-field update. - * To write multiple fields at once, call setField() for each of the fields you want to write, and then call writeFields() - * @param field Field number (1-8) within the channel to set - * @param value Floating point value (from -999999000000 to 999999000000) to write. If you need more accuracy, or a wider range, you should format the number yourself (using dtostrf) and setField() using the resulting string. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setLatitude(), setLongitude(), setElevation(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + /* + Function: setField + + Summary: + Set the value of a single field that will be part of a multi-field update. + + Parameters: + field - Field number (1-8) within the channel to set. + value - Floating point value (from -999999000000 to 999999000000) to write. If you need more accuracy, or a wider range, you should format the number yourself (using dtostrf) and setField() using the resulting string. + + Returns: + Code of 200 if successful. + Code of -101 if value is out of range or string is too long (> 255 bytes) + + */ int setField(unsigned int field, float value) { char valueString[20]; // range is -999999000000.00000 to 999999000000.00000, so 19 + 1 for the terminator @@ -477,73 +352,43 @@ class ThingSpeakClass return setField(field, valueString); }; - /** - * @brief Set the value of a single field that will be part of a multi-field update. - * To write multiple fields at once, call setField() for each of the fields you want to write, and then call writeFields() - * @param field Field number (1-8) within the channel to set - * @param value String to write (UTF8). ThingSpeak limits this to 255 bytes. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setLatitude(), setLongitude(), setElevation(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setField + + Summary: + Set the value of a single field that will be part of a multi-field update. + + Parameters: + field - Field number (1-8) within the channel to set. + value - String to write (UTF8). ThingSpeak limits this to 255 bytes. + + Returns: + Code of 200 if successful. + Code 0f -101 if value is out of range or string is too long (> 255 bytes) + + */ int setField(unsigned int field, const char * value) { return setField(field, String(value)); }; - /** - * @brief Set the value of a single field that will be part of a multi-field update. - * To write multiple fields at once, call setField() for each of the fields you want to write, and then call writeFields() - * @param field Field number (1-8) within the channel to set - * @param value String to write (UTF8). ThingSpeak limits this to 255 bytes. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setLatitude(), setLongitude(), setElevation(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setField + + Summary: + Set the value of a single field that will be part of a multi-field update. + + Parameters: + field - Field number (1-8) within the channel to set. + value - String to write (UTF8). ThingSpeak limits this to 255 bytes. + + Returns: + Code of 200 if successful. + Code of -101 if value is out of range or string is too long (> 255 bytes) + + */ int setField(unsigned int field, String value) { #ifdef PRINT_DEBUG_MESSAGES @@ -556,40 +401,23 @@ class ThingSpeakClass return OK_SUCCESS; }; - - /** - * @brief Set the latitude of a multi-field update. - * To record latitude, longitude and elevation of a write, call setField() for each of the fields you want to write, setLatitude() / setLongitude() / setElevation(), and then call writeFields() - * @param latitude Latitude of the measurement (degrees N, use negative values for degrees S) - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setField(), setLongitude(), setElevation(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - setLatitude(42.2833); - setLongitude(-71.3500); - setElevation(100); - delay(20000); - } - * @endcode - */ + + /* + Function: setLatitude + + Summary: + Set the latitude of a multi-field update. + + Parameters: + latitude - Latitude of the measurement as a floating point value (degrees N, use negative values for degrees S) + + Returns: + Always return 200 + + Notes: + To record latitude, longitude and elevation of a write, call setField() for each of the fields you want to write. Then setLatitude(), setLongitude(), setElevation() and then call writeFields() + + */ int setLatitude(float latitude) { #ifdef PRINT_DEBUG_MESSAGES @@ -599,40 +427,23 @@ class ThingSpeakClass return OK_SUCCESS; }; - - /** - * @brief Set the longitude of a multi-field update. - * To record latitude, longitude and elevation of a write, call setField() for each of the fields you want to write, setLatitude() / setLongitude() / setElevation(), and then call writeFields() - * @param longitude Longitude of the measurement (degrees E, use negative values for degrees W) - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setField(), setLatitude(), setElevation(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - setLatitude(42.2833); - setLongitude(-71.3500); - setElevation(100); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setLongitude + + Summary: + Set the longitude of a multi-field update. + + Parameters: + longitude - Longitude of the measurement as a floating point value (degrees E, use negative values for degrees W) + + Returns: + Always return 200 + + Notes: + To record latitude, longitude and elevation of a write, call setField() for each of the fields you want to write. Then setLatitude(), setLongitude(), setElevation() and then call writeFields() + + */ int setLongitude(float longitude) { #ifdef PRINT_DEBUG_MESSAGES @@ -642,40 +453,23 @@ class ThingSpeakClass return OK_SUCCESS; }; - - /** - * @brief Set the elevation of a multi-field update. - * To record latitude, longitude and elevation of a write, call setField() for each of the fields you want to write, setLatitude() / setLongitude() / setElevation(), and then call writeFields() - * @param elevation Elevation of the measurement (meters above sea level) - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setField(), setLatitude(), setLongitude(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - setLatitude(42.2833); - setLongitude(-71.3500); - setElevation(100); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setElevation + + Summary: + Set the elevation of a multi-field update. + + Parameters: + elevation - Elevation of the measurement as a floating point value (meters above sea level) + + Returns: + Always return 200 + + Notes: + To record latitude, longitude and elevation of a write, call setField() for each of the fields you want to write. Then setLatitude(), setLongitude(), setElevation() and then call writeFields() + + */ int setElevation(float elevation) { #ifdef PRINT_DEBUG_MESSAGES @@ -685,76 +479,51 @@ class ThingSpeakClass return OK_SUCCESS; }; - /** - * @brief Set the status of a multi-field update. - * To record a status message on a write, call setStatus() then call writeFields(). Use status to provide additonal - * details when writing a channel update. Additonally, status can be used by the ThingTweet App to send a message to - * Twitter. - * @param status String to write (UTF8). ThingSpeak limits this to 255 bytes. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, timeRead); - ThingSpeak.setStatus(sensor3Meaning); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + /* + Function: setStatus + + Summary: + Set the status field of a multi-field update. + + Parameters: + status - String to write (UTF8). ThingSpeak limits this to 255 bytes. + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + To record a status message on a write, call setStatus() then call writeFields(). + Use status to provide additonal details when writing a channel update. + Additonally, status can be used by the ThingTweet App to send a message to Twitter. + + */ int setStatus(const char * status) { return setStatus(String(status)); }; - /** - * @brief Set the status of a multi-field update. - * To record a status message on a write, call setStatus() then call writeFields(). Use status to provide additonal - * details when writing a channel update. Additonally, status can be used by the ThingTweet App to send a message to - * Twitter. - * @param status String to write (UTF8). ThingSpeak limits this to 255 bytes. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, timeRead); - ThingSpeak.setStatus(sensor3Meaning); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setStatus + + Summary: + Set the status field of a multi-field update. + + Parameters: + status - String to write (UTF8). ThingSpeak limits this to 255 bytes. + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + To record a status message on a write, call setStatus() then call writeFields(). + Use status to provide additonal details when writing a channel update. + Additonally, status can be used by the ThingTweet App to send a message to Twitter. + + */ int setStatus(String status) { #ifdef PRINT_DEBUG_MESSAGES @@ -766,149 +535,94 @@ class ThingSpeakClass return OK_SUCCESS; }; - /** - * @brief Set the Twitter account and message to use for an update to be tweeted. - * To send a message to twitter call setTwitterTweet() then call writeFields() - * @param twitter Twitter account name as a String. - * @param tweet Twitter message as a String (UTF-8) limited to 140 character. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. - * @see writeFields(),getLastReadStatus() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, timeRead); - ThingSpeak.setTwitterTweet("YourTwitterAccountName",sensor3Meaning); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setTwitterTweet + + Summary: + Set the Twitter account and message to use for an update to be tweeted. + + Parameters: + twitter - Twitter account name as a String. + tweet - Twitter message as a String (UTF-8) limited to 140 character. + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + To send a message to twitter call setTwitterTweet() then call writeFields(). + Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. + */ int setTwitterTweet(const char * twitter, const char * tweet) { return setTwitterTweet(String(twitter), String(tweet)); }; - /** - * @brief Set the Twitter account and message to use for an update to be tweeted. - * To send a message to twitter call setTwitterTweet() then call writeFields() - * @param twitter Twitter account name as a String. - * @param tweet Twitter message as a String (UTF-8) limited to 140 character. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. - * @see writeFields(),getLastReadStatus() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, timeRead); - ThingSpeak.setTwitterTweet("YourTwitterAccountName",sensor3Meaning); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + /* + Function: setTwitterTweet + + Summary: + Set the Twitter account and message to use for an update to be tweeted. + + Parameters: + twitter - Twitter account name as a String. + tweet - Twitter message as a String (UTF-8) limited to 140 character. + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + To send a message to twitter call setTwitterTweet() then call writeFields(). + Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. + */ int setTwitterTweet(String twitter, const char * tweet) { return setTwitterTweet(twitter, String(tweet)); }; - /** - * @brief Set the Twitter account and message to use for an update to be tweeted. - * To send a message to twitter call setTwitterTweet() then call writeFields() - * @param twitter Twitter account name as a String. - * @param tweet Twitter message as a String (UTF-8) limited to 140 character. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. - * @see writeFields(),getLastReadStatus() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, timeRead); - ThingSpeak.setTwitterTweet("YourTwitterAccountName",sensor3Meaning); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + /* + Function: setTwitterTweet + + Summary: + Set the Twitter account and message to use for an update to be tweeted. + + Parameters: + twitter - Twitter account name as a String. + tweet - Twitter message as a String (UTF-8) limited to 140 character. + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + To send a message to twitter call setTwitterTweet() then call writeFields(). + Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. + */ int setTwitterTweet(const char * twitter, String tweet) { return setTwitterTweet(String(twitter), tweet); }; - /** - * @brief Set the Twitter account and message to use for an update to be tweeted. - * To send a message to twitter call setTwitterTweet() then call writeFields() - * @param twitter Twitter account name as a String. - * @param tweet Twitter message as a String (UTF-8) limited to 140 character. - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. - * @see writeFields(),getLastReadStatus() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, timeRead); - ThingSpeak.setTwitterTweet("YourTwitterAccountName",sensor3Meaning); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + /* + Function: setTwitterTweet + + Summary: + Set the Twitter account and message to use for an update to be tweeted. + + Parameters: + twitter - Twitter account name as a String. + tweet - Twitter message as a String (UTF-8) limited to 140 character. + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + To send a message to twitter call setTwitterTweet() then call writeFields(). + Prior to using this feature, a twitter account must be linked to your ThingSpeak account. Do this by logging into ThingSpeak and going to Apps, then ThingTweet and clicking Link Twitter Account. + */ int setTwitterTweet(String twitter, String tweet){ #ifdef PRINT_DEBUG_MESSAGES Serial.print("ts::setTwitterTweet(twitter: "); Serial.print(twitter); Serial.print(", tweet: "); Serial.print(tweet); Serial.println("\")"); @@ -922,75 +636,49 @@ class ThingSpeakClass return OK_SUCCESS; }; - /** - * @brief Set the created-at date of a multi-field update. - * To record created-at of a write, call setField() for each of the fields you want to write, setCreatedAt(), and then call writeFields() - * @param createdAt Desired timestamp to be included with the channel update as a String. The timestamp string must be in the ISO 8601 format. Example "2017-01-12 13:22:54" - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Timezones can be set using the timezone hour offset parameter. For example, a timestamp for Eastern Standard Time is: "2017-01-12 13:22:54-05". If no timezone hour offset parameter is used, UTC time is assumed. - * @see setField(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.setCreatedAt("2017-01-06T13:56:28"); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setCreatedAt + + Summary: + Set the created-at date of a multi-field update. + + Parameters: + createdAt - Desired timestamp to be included with the channel update as a String. The timestamp string must be in the ISO 8601 format. Example "2017-01-12 13:22:54" + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + Timezones can be set using the timezone hour offset parameter. For example, a timestamp for Eastern Standard Time is: "2017-01-12 13:22:54-05". + If no timezone hour offset parameter is used, UTC time is assumed. + + */ int setCreatedAt(const char * createdAt) { return setCreatedAt(String(createdAt)); } -/** - * @brief Set the created-at date of a multi-field update. - * To record created-at of a write, call setField() for each of the fields you want to write, setCreatedAt(), and then call writeFields() - * @param createdAt Desired timestamp to be included with the channel update as a String. The timestamp string must be in the ISO 8601 format. Example "2017-01-12 13:22:54" - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark Timezones can be set using the timezone hour offset parameter. For example, a timestamp for Eastern Standard Time is: "2017-01-12 13:22:54-05". If no timezone hour offset parameter is used, UTC time is assumed. - * @see setField(), writeFields() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.setCreatedAt("2017-01-06T13:56:28"); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: setCreatedAt + + Summary: + Set the created-at date of a multi-field update. + + Parameters: + createdAt - Desired timestamp to be included with the channel update as a String. The timestamp string must be in the ISO 8601 format. Example "2017-01-12 13:22:54" + + Returns: + Code of 200 if successful. + Code of -101 if string is too long (> 255 bytes) + + Notes: + Timezones can be set using the timezone hour offset parameter. For example, a timestamp for Eastern Standard Time is: "2017-01-12 13:22:54-05". + If no timezone hour offset parameter is used, UTC time is assumed. + + */ int setCreatedAt(String createdAt) { #ifdef PRINT_DEBUG_MESSAGES @@ -1006,41 +694,34 @@ class ThingSpeakClass return OK_SUCCESS; } - - /** - * @brief Write a multi-field update. - * Call setField() for each of the fields you want to write, setLatitude() / setLongitude() / setElevation(), and then call writeFields() - * @param channelNumber Channel number - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @see setField(), setLatitude(), setLongitude(), setElevation() - * @code - void loop() { - int sensor1Value = analogRead(A0); - float sensor2Voltage = analogRead(A1) * (5.0 / 1023.0); - String sensor3Meaning; - int sensor3Value = analogRead(A2); - if (sensor3Value < 400) { - sensor3Meaning = String("Too Cold!"); - } else if (sensor3Value > 600) { - sensor3Meaning = String("Too Hot!"); - } else { - sensor3Meaning = String("Just Right"); - } - long timeRead = millis(); - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - setLatitude(42.2833); - setLongitude(-71.3500); - setElevation(100); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: writeFields + + Summary: + Write a multi-field update. + + Parameters: + channelNumber - Channel number + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + 200 - successful. + 404 - Incorrect API key (or invalid ThingSpeak server address) + -101 - Value is out of range or string is too long (> 255 characters) + -201 - Invalid field number specified + -210 - setField() was not called before writeFields() + -301 - Failed to connect to ThingSpeak + -302 - Unexpected failure during write to ThingSpeak + -303 - Unable to parse response + -304 - Timeout waiting for server to respond + -401 - Point was not inserted (most probable cause is the rate limit of once every 15 seconds) + + + Notes: + Call setField(), setLatitude(), setLongitude(), setElevation() and/or setStatus() and then call writeFields() + + */ int writeFields(unsigned long channelNumber, const char * writeAPIKey) { String postMessage = String(""); @@ -1147,48 +828,67 @@ class ThingSpeakClass return writeRaw(channelNumber, postMessage, writeAPIKey); }; - - /** - * @brief Write a raw POST to a ThingSpeak channel - * @param channelNumber Channel number - * @param postMessage Raw URL to write to ThingSpeak as a string. See the documentation at https://thingspeak.com/docs/channels#update_feed. - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark This is low level functionality that will not be required by most users. - * @code - void loop() { - const char postMessage[] = "field1=23&created_at=2014-12-31%2023:59:59"; - - ThingSpeak.setField(1, sensor1Value); - ThingSpeak.setField(2, sensor2Voltage); - ThingSpeak.setField(3, sensor3Meaning); - ThingSpeak.setField(4, timeRead); - ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: writeRaw + + Summary: + Write a raw POST to a ThingSpeak channel + + Parameters: + channelNumber - Channel number + postMessage - Raw URL to write to ThingSpeak as a string. See the documentation at https://thingspeak.com/docs/channels#update_feed. + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + 200 - successful. + 404 - Incorrect API key (or invalid ThingSpeak server address) + -101 - Value is out of range or string is too long (> 255 characters) + -201 - Invalid field number specified + -210 - setField() was not called before writeFields() + -301 - Failed to connect to ThingSpeak + -302 - Unexpected failure during write to ThingSpeak + -303 - Unable to parse response + -304 - Timeout waiting for server to respond + -401 - Point was not inserted (most probable cause is the rate limit of once every 15 seconds) + + Notes: + This is low level functionality that will not be required by most users. + + */ int writeRaw(unsigned long channelNumber, const char * postMessage, const char * writeAPIKey) { return writeRaw(channelNumber, String(postMessage), writeAPIKey); }; - - /** - * @brief Write a raw POST to a ThingSpeak channel - * @param channelNumber Channel number - * @param postMessage Raw URL to write to ThingSpeak as a String. See the documentation at https://thingspeak.com/docs/channels#update_feed. - * @param writeAPIKey Write API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return HTTP status code of 200 if successful. See getLastReadStatus() for other possible return values. - * @remark This is low level functionality that will not be required by most users. - * @code - void loop() { - String postMessage = String("field1=23&created_at=2014-12-31%2023:59:59"); - ThingSpeak.writeRaw(myChannelNumber, postMessage, myWriteAPIKey); - delay(20000); - } - * @endcode - */ + + /* + Function: writeRaw + + Summary: + Write a raw POST to a ThingSpeak channel + + Parameters: + channelNumber - Channel number + postMessage - Raw URL to write to ThingSpeak as a string. See the documentation at https://thingspeak.com/docs/channels#update_feed. + writeAPIKey - Write API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + 200 - successful. + 404 - Incorrect API key (or invalid ThingSpeak server address) + -101 - Value is out of range or string is too long (> 255 characters) + -201 - Invalid field number specified + -210 - setField() was not called before writeFields() + -301 - Failed to connect to ThingSpeak + -302 - Unexpected failure during write to ThingSpeak + -303 - Unable to parse response + -304 - Timeout waiting for server to respond + -401 - Point was not inserted (most probable cause is the rate limit of once every 15 seconds) + + Notes: + This is low level functionality that will not be required by most users. + + */ int writeRaw(unsigned long channelNumber, String postMessage, const char * writeAPIKey) { #ifdef PRINT_DEBUG_MESSAGES @@ -1207,7 +907,6 @@ class ThingSpeakClass 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\r\n")) return abortWriteRaw(); @@ -1244,21 +943,22 @@ class ThingSpeakClass return status; }; - /** - * @brief Read the latest string from a private ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @param readAPIKey Read API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return Value read (UTF8 string), or empty string if there is an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - String message = ThingSpeak.readStringField(myChannelNumber, 1, myReadAPIKey); - Serial.print("Latest message is: "); - Serial.println(message); - delay(30000); - } - * @endcode - */ + + /* + Function: readStringField + + Summary: + Read the latest string from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + readAPIKey - Read API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + Value read (UTF8 string), or empty string if there is an error. Use getLastReadStatus() to get more specific information. + + */ String readStringField(unsigned long channelNumber, unsigned int field, const char * readAPIKey) { if(field < FIELDNUM_MIN || field > FIELDNUM_MAX) @@ -1278,167 +978,165 @@ class ThingSpeakClass } - /** - * @brief Read the latest string from a public ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @return Value read (UTF8), or empty string if there is an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - String message = ThingSpeak.readStringField(myChannelNumber, 1); - Serial.print("Latest message is: "); - Serial.println(message); - delay(30000); - } - * @endcode - */ + + /* + Function: readStringField + + Summary: + Read the latest string from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + + Returns: + Value read (UTF8 string), or empty string if there is an error. Use getLastReadStatus() to get more specific information. + + */ String readStringField(unsigned long channelNumber, unsigned int field) { return readStringField(channelNumber, field, NULL); }; - - /** - * @brief Read the latest float from a private ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @param readAPIKey Read API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. - * @code - void loop() { - float voltage = ThingSpeak.readFloatField(myChannelNumber, 1, myReadAPIKey); - Serial.print("Latest voltage is: "); - Serial.print(voltage); - Serial.println("V"); - delay(30000); - } - * @endcode - */ + + /* + Function: readFloatField + + Summary: + ead the latest floating point value from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + readAPIKey - Read API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. + + */ float readFloatField(unsigned long channelNumber, unsigned int field, const char * readAPIKey) { return convertStringToFloat(readStringField(channelNumber, field, readAPIKey)); }; - - /** - * @brief Read the latest float from a public ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @return Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. - * @code - void loop() { - float voltage = ThingSpeak.readFloatField(myChannelNumber, 1); - Serial.print("Latest voltage is: "); - Serial.print(voltage); - Serial.println("V"); - delay(30000); - } - * @endcode - */ - float readFloatField(unsigned long channelNumber, unsigned int field) + + /* + Function: readFloatField + + Summary: + Read the latest floating point value from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + + Returns: + Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. + + */ + float readFloatField(unsigned long channelNumber, unsigned int field) { return readFloatField(channelNumber, field, NULL); }; - - /** - * @brief Read the latest long from a private ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @param readAPIKey Read API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - long value = ThingSpeak.readLongField(myChannelNumber, 1, myReadAPIKey); - Serial.print("Latest value is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readLongField + + Summary: + Read the latest long value from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + readAPIKey - Read API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. + + */ 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(); } - - /** - * @brief Read the latest long from a public ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @return Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - long value = ThingSpeak.readLongField(myChannelNumber, 1); - Serial.print("Latest value is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readLongField + + Summary: + Read the latest long value from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + + Returns: + Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. + + */ long readLongField(unsigned long channelNumber, unsigned int field) { return readLongField(channelNumber, field, NULL); }; - - /** - * @brief Read the latest int from a private ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @param readAPIKey Read API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. - * @remark If the value returned is out of range for an int, the result is undefined. - * @code - void loop() { - int value = ThingSpeak.readIntField(myChannelNumber, 1, myReadAPIKey); - Serial.print("Latest value is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readIntField + + Summary: + Read the latest int value from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + readAPIKey - Read API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. + + */ int readIntField(unsigned long channelNumber, unsigned int field, const char * readAPIKey) { return readLongField(channelNumber, field, readAPIKey); } - - /** - * @brief Read the latest int from a public ThingSpeak channel - * @param channelNumber Channel number - * @param field Field number (1-8) within the channel to read from. - * @return Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. - * @remark If the value returned is out of range for an int, the result is undefined. - * @code - void loop() { - int value = ThingSpeak.readIntField(myChannelNumber, 1); - Serial.print("Latest value is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readIntField + + Summary: + Read the latest int value from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + field - Field number (1-8) within the channel to read from. + + Returns: + Value read, or 0 if the field is text or there is an error. Use getLastReadStatus() to get more specific information. Note that NAN, INFINITY, and -INFINITY are valid results. + + */ int readIntField(unsigned long channelNumber, unsigned int field) { return readLongField(channelNumber, field, NULL); }; - /** - * @brief Read the latest status from a private ThingSpeak channel - * @param channelNumber Channel number - * @param readAPIKey Read API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return Value read (UTF8 string). An empty string is returned if there was no status written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - String value = ThingSpeak.readStatus(myChannelNumber, myReadAPIKey); - Serial.print("Latest status is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readStatus + + Summary: + Read the latest status from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + readAPIKey - Read API key associated with the channel. *If you share code with others, do _not_ share this key* + + Results: + Value read (UTF8 string). An empty string is returned if there was no status written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. + + */ String readStatus(unsigned long channelNumber, const char * readAPIKey) { String content = readRaw(channelNumber, "/feeds/last.txt?status=true", readAPIKey); @@ -1450,38 +1148,40 @@ class ThingSpeakClass return getJSONValueByKey(content, "status"); }; - /** - * @brief Read the latest status from a public ThingSpeak channel - * @param channelNumber Channel number - * @return Value read (UTF8 string). An empty string is returned if there was no status written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - String value = ThingSpeak.readStatus(myChannelNumber, myReadAPIKey); - Serial.print("Latest status is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readStatus + + Summary: + Read the latest status from a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + + Results: + Value read (UTF8 string). An empty string is returned if there was no status written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. + + */ String readStatus(unsigned long channelNumber) { return readStatus(channelNumber, NULL); }; - /** - * @brief Read the created-at timestamp associated with the latest update to a private ThingSpeak channel - * @param channelNumber Channel number - * @param readAPIKey Read API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return Value read (UTF8 string). An empty string is returned if there was no created-at timestamp written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - String value = ThingSpeak.readCreatedAt(myChannelNumber); - Serial.print("Latest update timestamp is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readCreatedAt + + Summary: + Read the created-at timestamp associated with the latest update to a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + readAPIKey - Read API key associated with the channel. *If you share code with others, do _not_ share this key* + + Results: + Value read (UTF8 string). An empty string is returned if there was no created-at timestamp written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. + + */ String readCreatedAt(unsigned long channelNumber, const char * readAPIKey) { String content = readRaw(channelNumber, "/feeds/last.txt", readAPIKey); @@ -1493,60 +1193,67 @@ class ThingSpeakClass return getJSONValueByKey(content, "created_at"); }; - /** - * @brief Read the created-at timestamp associated with the latest update to a private ThingSpeak channel - * @param channelNumber Channel number - * @return Value read (UTF8 string). An empty string is returned if there was no created-at timestamp written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. - * @code - void loop() { - String value = ThingSpeak.readCreatedAt(myChannelNumber); - Serial.print("Latest update timestamp is: "); - Serial.print(value); - delay(30000); - } - * @endcode - */ + + /* + Function: readCreatedAt + + Summary: + Read the created-at timestamp associated with the latest update to a private ThingSpeak channel + + Parameters: + channelNumber - Channel number + + Results: + Value read (UTF8 string). An empty string is returned if there was no created-at timestamp written to the channel or in case of an error. Use getLastReadStatus() to get more specific information. + + */ String readCreatedAt(unsigned long channelNumber) { return readCreatedAt(channelNumber, NULL); }; - /** - * @brief Read a raw response from a public ThingSpeak channel - * @param channelNumber Channel number - * @param URLSuffix Raw URL to write to ThingSpeak as a String. See the documentation at https://thingspeak.com/docs/channels#get_feed - * @return Response if successful, or empty string. Use getLastReadStatus() to get more specific information. - * @remark This is low level functionality that will not be required by most users. - * @code - void loop() { - String response = ThingSpeak.readRaw(myChannelNumber, String("feeds/days=1")); - Serial.print("Response: "); - Serial.print(response); - delay(30000); - } - * @endcode - */ + + /* + Function: readRaw + + Summary: + Read a raw response from a public ThingSpeak channel + + Parameters: + channelNumber - Channel number + URLSuffix - Raw URL to write to ThingSpeak as a String. See the documentation at https://thingspeak.com/docs/channels#get_feed + + Returns: + Response if successful, or empty string. Use getLastReadStatus() to get more specific information. + + Notes: + This is low level functionality that will not be required by most users. + + */ String readRaw(unsigned long channelNumber, String URLSuffix) { return readRaw(channelNumber, URLSuffix, NULL); } - /** - * @brief Read a raw response from a private ThingSpeak channel - * @param channelNumber Channel number - * @param URLSuffix Raw URL to write to ThingSpeak as a String. See the documentation at https://thingspeak.com/docs/channels#get_feed - * @param readAPIKey Read API key associated with the channel. *If you share code with others, do _not_ share this key* - * @return Response if successful, or empty string. Use getLastReadStatus() to get more specific information. - * @remark This is low level functionality that will not be required by most users. - * @code - void loop() { - String response = ThingSpeak.readRaw(myChannelNumber, String("feeds/days=1"), myReadAPIKey); - Serial.print("Response: "); - Serial.print(response); - delay(30000); - } - * @endcode - */ + + /* + Function: readRaw + + Summary: + Read a raw response from a public ThingSpeak channel + + Parameters: + channelNumber - Channel number + URLSuffix - Raw URL to write to ThingSpeak as a String. See the documentation at https://thingspeak.com/docs/channels#get_feed + readAPIKey - Read API key associated with the channel. *If you share code with others, do _not_ share this key* + + Returns: + Response if successful, or empty string. Use getLastReadStatus() to get more specific information. + + Notes: + This is low level functionality that will not be required by most users. + + */ String readRaw(unsigned long channelNumber, String URLSuffix, const char * readAPIKey) { #ifdef PRINT_DEBUG_MESSAGES @@ -1605,39 +1312,30 @@ class ThingSpeakClass return String("") + content; }; - /** - * @brief Get the status of the previous read. - * @return Generally, these are HTTP status codes. Negative values indicate an error generated by the library. - * Possible response codes: - * * 200: OK / Success - * * 404: Incorrect API key (or invalid ThingSpeak server address) - * * -101: Value is out of range or string is too long (> 255 characters) - * * -201: Invalid field number specified - * * -210: setField() was not called before writeFields() - * * -301: Failed to connect to ThingSpeak - * * -302: Unexpected failure during write to ThingSpeak - * * -303: Unable to parse response - * * -304: Timeout waiting for server to respond - * * -401: Point was not inserted (most probable cause is the rate limit of once every 15 seconds) - * @remark The read functions will return zero or empty if there is an error. Use this function to retrieve the details. - * @code - void loop() { - String message = ThingSpeak.readStringField(myChannelNumber, 1); - int resultCode = ThingSpeak.getLastReadStatus(); - if(resultCode == 200) - { - Serial.print("Latest message is: "); - Serial.println(message); - } - else - { - Serial.print("Error reading message. Status was: "); - Serial.println(resultCode); - } - delay(30000); - } - * @endcode - */ + + /* + Function: getLastReadStatus + + Summary: + Get the status of the previous read. + + Returns: + Generally, these are HTTP status codes. Negative values indicate an error generated by the library. + Possible response codes... + 200 - OK / Success + 404 - Incorrect API key (or invalid ThingSpeak server address) + -101 - Value is out of range or string is too long (> 255 characters) + -201 - Invalid field number specified + -210 - setField() was not called before writeFields() + -301 - Failed to connect to ThingSpeak + -302 - Unexpected failure during write to ThingSpeak + -303 - Unable to parse response + -304 - Timeout waiting for server to respond + -401 - Point was not inserted (most probable cause is exceeding the rate limit) + + Notes: + The read functions will return zero or empty if there is an error. Use this function to retrieve the details. + */ int getLastReadStatus() { return this->lastReadStatus; @@ -1690,41 +1388,15 @@ class ThingSpeakClass 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) + void setPort(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.println("ts::setServer (default)"); - #endif - this->customIP = INADDR_NONE; - this->customHostName = NULL; - this->port = THINGSPEAK_PORT_NUMBER; - }; - + this->port = port; + } + + 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; @@ -1739,39 +1411,16 @@ class ThingSpeakClass 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 + Serial.print(" Connect to default ThingSpeak: "); + Serial.print(THINGSPEAK_URL); + Serial.print(":"); + Serial.print(this->port); + Serial.print("..."); + #endif + connectSuccess = client->connect(THINGSPEAK_URL, this->port); + #ifdef PRINT_DEBUG_MESSAGES if (connectSuccess) @@ -1788,16 +1437,8 @@ class ThingSpeakClass 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("\r\n")) return false; - } - else - { - if (!this->client->print("Host: api.thingspeak.com\r\n")) return false; - } + + if (!this->client->print("Host: api.thingspeak.com\r\n")) return false; if (!this->client->print("Connection: close\r\n")) return false; if (!this->client->print("User-Agent: ")) return false; if (!this->client->print(TS_USER_AGENT)) return false;