#include <src/dataPublisherBase.h>
dataPublisher
class
The dataPublisher class is a virtual class used by other publishers to distribute data online.
A dataPublisher is a abstract concept. It is something that "watches" the logger for new data and correctly formats and sends that data to some online web service.
Derived classes
- class AWS_IoT_Publisher
- The AWS_
IoT_ Publisher subclass of dataPublisher for publishing data to AWS IoT Core using the MQTT protocol. - class DreamHostPublisher
- The DreamHostPublisher subclass of dataPublisher is for publishing data to the Stroud Center's now-deprecated DreamHost based live sensor data system.
- class EnviroDIYPublisher
- The EnviroDIYPublisher subclass of dataPublisher for publishing data to the Monitor My Watershed/EnviroDIY data portal at https:/
/ monitormywatershed.org/ (formerly at http:/ / data.enviroDIY.org). - class S3PresignedPublisher
- The S3PresignedPublisher subclass of dataPublisher is for publishing data to S3 over a pre-signed URL.
- class ThingSpeakPublisher
- The ThingSpeakPublisher subclass of dataPublisher for publishing data to ThingSpeak using the MQTT protocol.
- class UbidotsPublisher
- The UbidotsPublisher subclass of dataPublisher for publishing data to the Ubidots data portal at https:/
/ ubidots.com.
Constructors, destructors, conversion operators
- dataPublisher()
- Construct a new data publisher object untied to any logger or client.
- dataPublisher(Logger& baseLogger, int sendEveryX = 1) explicit
- Construct a new data publisher object using a single client created on the TinyGSM based logger modem.
- dataPublisher(Logger& baseLogger, Client* inClient, int sendEveryX = 1)
- Construct a new data publisher object.
- ~dataPublisher() virtual
- Destroy the data publisher object - no action is taken.
Public functions
- void setClient(Client* inClient)
- Set the Client object.
- void setSendInterval(int sendEveryX)
- Sets the interval (in units of the logging interval) between attempted data transmissions.
- void attachToLogger(Logger& baseLogger)
- Attach the publisher to a logger.
- void setModemPointer(loggerModem& modemPointer)
- Set the pointer to a loggerModem instance.
- void begin(Logger& baseLogger, Client* inClient)
- Begin the publisher - linking it to the client and logger.
- void begin(Logger& baseLogger)
- Begin the publisher - linking it to the logger but not attaching a client.
- String getEndpoint(void) -> String pure virtual
- Get the destination for published data - generally the host name of the data receiver.
- bool connectionNeeded(void) -> bool virtual
- Checks if the publisher needs an internet connection for the next publishData call (as opposed to just buffering data internally).
- int16_t publishData(Client* outClient, bool forceFlush = false) -> int16_t pure virtual
- Opens a socket to the correct receiver and sends out the formatted data.
- int16_t publishData(bool forceFlush = false) -> int16_t virtual
- Open a socket to the correct receiver and send out the formatted data.
- int16_t publishMetadata(Client* outClient) -> int16_t virtual
- Open a socket to the correct receiver and send out metadata about the current logger setup.
- int16_t publishMetadata() -> int16_t virtual
- Open a socket to the correct receiver and send out metadata about the current logger setup.
- int16_t sendData(Client* outClient) -> int16_t deprecated in v0.22.5 virtual
- Retained for backwards compatibility; use publishData(Client* outClient) in new code.
- int16_t sendData() -> int16_t deprecated in v0.22.5 virtual
- Retained for backwards compatibility; use publishData() in new code.
- String parseMQTTState(int state) -> String
- Translate a PubSubClient code into a String with the code explanation.
Protected static functions
- static void txBufferInit(Client* outClient)
- Initialize the TX buffer to be empty and start writing to the given client.
- static void txBufferAppend(const char* data, size_t length, bool debug_flush = true)
- Append the given data to the TX buffer, flushing if necessary.
- static void txBufferAppend(const char* s, bool debug_flush = true)
- Append the given string to the TX buffer, flushing if necessary.
- static void txBufferAppend(char c, bool debug_flush = true)
- Append the given char to the TX buffer, flushing if necessary.
- static void txBufferFlush(bool debug_flush = true)
- Write the TX buffer contents to the initialized stream and also to the debugging port.
Protected functions
- Client* createClient() -> Client* virtual
- Use the connected base logger's logger modem and underlying TinyGSM instance to create a new client for the publisher.
- void deleteClient(Client* client) virtual
- Delete a created client. We need to pass this through to avoid a memory leak because we cannot delete from the pointer because the destructor for a client in the Arduino core isn't virtual.
Protected static variables
- static char txBuffer
- The buffer for outgoing data.
- static Client* txBufferOutClient
- The pointer to the client instance the TX buffer is writing to.
- static size_t txBufferLen
- The number of used characters in the TX buffer.
- static const char* getHeader
- the text "GET "
- static const char* postHeader
- the text "POST "
- static const char* putHeader
- the text "PUT "
- static const char* HTTPtag
- the text " HTTP/1.1"
- static const char* hostHeader
- the text "\r\nHost: "
Protected variables
- Logger* _baseLogger
- The internal pointer to the logger instance to be used.
- loggerModem* _baseModem
- The internal pointer to the base logger's modem instance to be used.
- Client* _inClient
- The internal pointer to the client instance to be used.
- int _sendEveryX
- Interval (in units of the logging interval) between attempted data transmissions. Not respected by all publishers.
Function documentation
dataPublisher:: dataPublisher()
Construct a new data publisher object untied to any logger or client.
dataPublisher:: dataPublisher(Logger& baseLogger,
int sendEveryX = 1) explicit
Construct a new data publisher object using a single client created on the TinyGSM based logger modem.
Parameters | |
---|---|
baseLogger | The logger supplying the data to be published |
sendEveryX | Interval (in units of the logging interval) between attempted data transmissions. Not respected by all publishers. |
dataPublisher:: dataPublisher(Logger& baseLogger,
Client* inClient,
int sendEveryX = 1)
Construct a new data publisher object.
Parameters | |
---|---|
baseLogger | The logger supplying the data to be published |
inClient | An Arduino client instance to use to print data to. Allows the use of any type of client and multiple clients tied to a single TinyGSM modem instance |
sendEveryX | Interval (in units of the logging interval) between attempted data transmissions. Not respected by all publishers. |
void dataPublisher:: setClient(Client* inClient)
Set the Client object.
Parameters | |
---|---|
inClient | A pointer to an Arduino client instance |
Gives the publisher a client instance to use to "print" data.
void dataPublisher:: setSendInterval(int sendEveryX)
Sets the interval (in units of the logging interval) between attempted data transmissions.
Parameters | |
---|---|
sendEveryX | Interval (in units of the logging interval) between attempted data transmissions. Not respected by all publishers. |
void dataPublisher:: attachToLogger(Logger& baseLogger)
Attach the publisher to a logger.
Parameters | |
---|---|
baseLogger | A reference to the ModularSensors logger instance |
The publisher must be tied to a data logger to provide it with the data to be published.
void dataPublisher:: setModemPointer(loggerModem& modemPointer)
Set the pointer to a loggerModem instance.
Parameters | |
---|---|
modemPointer | A reference to the ModularSensors loggerModem instance |
void dataPublisher:: begin(Logger& baseLogger,
Client* inClient)
Begin the publisher - linking it to the client and logger.
Parameters | |
---|---|
baseLogger | The logger supplying the data to be published |
inClient | An Arduino client instance to use to print data to. Allows the use of any type of client and multiple clients tied to a single TinyGSM modem instance |
This can be used as an alternative to adding the logger and client in the constructor.
String dataPublisher:: getEndpoint(void) pure
virtual
Get the destination for published data - generally the host name of the data receiver.
Returns | String The URL or HOST to receive published data |
---|
bool dataPublisher:: connectionNeeded(void) virtual
Checks if the publisher needs an internet connection for the next publishData call (as opposed to just buffering data internally).
Returns | bool True if an internet connection is needed for the next publish. |
---|
int16_t dataPublisher:: publishData(Client* outClient,
bool forceFlush = false) pure
virtual
Opens a socket to the correct receiver and sends out the formatted data.
Parameters | |
---|---|
outClient | An Arduino client instance to use to print data to. Allows the use of any type of client and multiple clients tied to a single TinyGSM modem instance |
forceFlush | Ask the publisher to flush buffered data immediately. |
Returns | int16_t The result of publishing data. May be an http response code or a result code from PubSubClient. |
This depends on an internet connection already having been made and a client being available.
int16_t dataPublisher:: publishData(bool forceFlush = false) virtual
Open a socket to the correct receiver and send out the formatted data.
Parameters | |
---|---|
forceFlush | Ask the publisher to flush buffered data immediately. |
Returns | int16_t The result of publishing data. May be an http response code or a result code from PubSubClient. Defaults to -2 if the publisher fails to create a client. |
This depends on an internet connection already having been made and either a client having been linked to the publisher or a logger modem having been linked to the logger linked to the publisher.
int16_t dataPublisher:: publishMetadata(Client* outClient) virtual
Open a socket to the correct receiver and send out metadata about the current logger setup.
Parameters | |
---|---|
outClient | An Arduino client instance to use to print data to. Allows the use of any type of client and multiple clients tied to a single TinyGSM modem instance |
Returns | int16_t The result of publishing data. May be an http response code or a result code from PubSubClient. |
This is to be used only when the logger is starting up! As the metadata doesn't generally change after start up, there's no reason to call this function any other time. There is no sensor data included in this metadata! If there is metadata that has to be included with each data post, that should be included in the publishData function. Because there is no sensor data included in this metadata and it's only to be called at boot, there's no forceFlush
option for this function.
This depends on an internet connection already having been made and a client being available.
int16_t dataPublisher:: publishMetadata() virtual
Open a socket to the correct receiver and send out metadata about the current logger setup.
Returns | int16_t The result of publishing data. May be an http response code or a result code from PubSubClient. |
---|
This is to be used only when the logger is starting up! As the metadata doesn't generally change after start up, there's no reason to call this function any other time. There is no sensor data included in this metadata! If there is metadata that has to be included with each data post, that should be included in the publishData function. Because there is no sensor data included in this metadata and it's only to be called at boot, there's no forceFlush
option for this function.
This depends on an internet connection already having been made and a client being available.
int16_t dataPublisher:: sendData(Client* outClient) virtual deprecated in v0.22.5
Retained for backwards compatibility; use publishData(Client* outClient) in new code.
Parameters | |
---|---|
outClient | An Arduino client instance to use to print data to. Allows the use of any type of client and multiple clients tied to a single TinyGSM modem instance |
Returns | int16_t The result of publishing data. May be an http response code or a result code from PubSubClient. |
int16_t dataPublisher:: sendData() virtual deprecated in v0.22.5
Retained for backwards compatibility; use publishData() in new code.
Returns | int16_t The result of publishing data. May be an http response code or a result code from PubSubClient. |
---|
String dataPublisher:: parseMQTTState(int state)
Translate a PubSubClient code into a String with the code explanation.
Parameters | |
---|---|
state | A result code returned by a PubSubClient action |
Returns | String The meaning of the code |
static void dataPublisher:: txBufferInit(Client* outClient) protected
Initialize the TX buffer to be empty and start writing to the given client.
Parameters | |
---|---|
outClient | The client to transmit to. |
static void dataPublisher:: txBufferAppend(const char* data,
size_t length,
bool debug_flush = true) protected
Append the given data to the TX buffer, flushing if necessary.
Parameters | |
---|---|
data | The data start pointer. |
length | The number of bytes to add. |
debug_flush | If true, flush the TX buffer to the debugging port. |
static void dataPublisher:: txBufferAppend(const char* s,
bool debug_flush = true) protected
Append the given string to the TX buffer, flushing if necessary.
Parameters | |
---|---|
s | The null-terminated string to append. |
debug_flush | If true, flush the TX buffer to the debugging port. |
static void dataPublisher:: txBufferAppend(char c,
bool debug_flush = true) protected
Append the given char to the TX buffer, flushing if necessary.
Parameters | |
---|---|
c | The char to append. |
debug_flush | If true, flush the TX buffer to the debugging port. |
static void dataPublisher:: txBufferFlush(bool debug_flush = true) protected
Write the TX buffer contents to the initialized stream and also to the debugging port.
Parameters | |
---|---|
debug_flush | If true, flush the TX buffer to the debugging port. |
Client* dataPublisher:: createClient() virtual protected
Use the connected base logger's logger modem and underlying TinyGSM instance to create a new client for the publisher.
Returns | Client* A pointer to an Arduino client instance |
---|
void dataPublisher:: deleteClient(Client* client) virtual protected
Delete a created client. We need to pass this through to avoid a memory leak because we cannot delete from the pointer because the destructor for a client in the Arduino core isn't virtual.
Parameters | |
---|---|
client | The client to delete |