Documentation of intreace_influxdb

code/components/jomjol_influxdb/interface_influxdb.cpp

@@ -10,9 +10,33 @@
 
 static const char *TAG = "INFLUXDB";
 
+/**
+ * @brief Buffer to store the HTTP response.
+ * 
+ * This character array is used to store the output of an HTTP response.
+ * The size of the buffer is defined by the constant MAX_HTTP_OUTPUT_BUFFER.
+ */
 char response_buffer[MAX_HTTP_OUTPUT_BUFFER] = {0};
 
 
+/**
+ * @brief HTTP event handler callback function.
+ *
+ * This function handles various HTTP client events and logs appropriate messages.
+ *
+ * @param evt Pointer to the HTTP client event structure.
+ * @return esp_err_t ESP_OK on success.
+ *
+ * Event types handled:
+ * - HTTP_EVENT_ERROR: Logs an error message when an HTTP error is encountered.
+ * - HTTP_EVENT_ON_CONNECTED: Logs a message when the HTTP client successfully connects.
+ * - HTTP_EVENT_HEADERS_SENT: Logs a message when all request headers are sent.
+ * - HTTP_EVENT_ON_HEADER: Logs the received header key and value.
+ * - HTTP_EVENT_ON_DATA: Logs the length of the received data.
+ * - HTTP_EVENT_ON_FINISH: Logs a message when the HTTP client finishes the request.
+ * - HTTP_EVENT_DISCONNECTED: Logs a message when the HTTP client disconnects.
+ * - HTTP_EVENT_REDIRECT: Logs a message when an HTTP redirect occurs.
+ */
 static esp_err_t http_event_handler(esp_http_client_event_t *evt)
 {
     switch(evt->event_id)
@@ -48,6 +72,16 @@ static esp_err_t http_event_handler(esp_http_client_event_t *evt)
 
 
 
+/**
+ * @brief Initializes the InfluxDB connection with version 1 settings.
+ * 
+ * This function sets up the connection parameters for InfluxDB version 1.
+ * 
+ * @param _influxDBURI The URI of the InfluxDB server.
+ * @param _database The name of the database to connect to.
+ * @param _user The username for authentication.
+ * @param _password The password for authentication.
+ */
 void InfluxDB::InfluxDBInitV1(std::string _influxDBURI, std::string _database, std::string _user, std::string _password) {
     version = INFLUXDB_V1;
     influxDBURI = _influxDBURI;
@@ -56,6 +90,17 @@ static esp_err_t http_event_handler(esp_http_client_event_t *evt)
     password = _password;
 }
 
+/**
+ * @brief Initializes the InfluxDB client with version 2 settings.
+ * 
+ * This function sets up the InfluxDB client to use InfluxDB version 2 by
+ * configuring the URI, bucket, organization, and token.
+ * 
+ * @param _influxDBURI The URI of the InfluxDB server.
+ * @param _bucket The bucket name to store data in.
+ * @param _org The organization name associated with the bucket.
+ * @param _token The authentication token for accessing the InfluxDB server.
+ */
 void InfluxDB::InfluxDBInitV2(std::string _influxDBURI, std::string _bucket, std::string _org, std::string _token) {
     version = INFLUXDB_V2;
     influxDBURI = _influxDBURI;
@@ -64,6 +109,18 @@ static esp_err_t http_event_handler(esp_http_client_event_t *evt)
     token = _token;
 }
 
+/**
+ * @brief Establishes an HTTP connection to the InfluxDB server.
+ *
+ * This function configures and initializes an HTTP client to connect to the InfluxDB server.
+ * It sets up the necessary parameters such as the URL, event handler, buffer size, and user data.
+ * Depending on the InfluxDB version, it also configures the authentication type and credentials.
+ *
+ * @note This function destroys any existing HTTP client before initializing a new one.
+ *
+ * @param None
+ * @return None
+ */
 void InfluxDB::connectHTTP() {
     esp_http_client_config_t config = {};
 
@@ -93,7 +150,12 @@ static esp_err_t http_event_handler(esp_http_client_event_t *evt)
 }
 
 
-    // Destroy the InfluxDB connection
+/**
+ * @brief Destroys the InfluxDB instance by cleaning up the HTTP client.
+ *
+ * This function checks if the HTTP client is initialized. If it is, it cleans up the HTTP client
+ * and logs the cleanup action. The HTTP client pointer is then set to NULL.
+ */
 void InfluxDB::InfluxDBdestroy() {
     if (httpClient) {
         esp_http_client_cleanup(httpClient);
@@ -102,7 +164,21 @@ static esp_err_t http_event_handler(esp_http_client_event_t *evt)
     }
 }
 
-    // Publish data to the InfluxDB server
+/**
+ * @brief Publishes data to an InfluxDB instance.
+ *
+ * This function sends a measurement, key, and content to an InfluxDB server.
+ * It supports both InfluxDB v1 and v2 APIs.
+ *
+ * @param _measurement The measurement name to publish.
+ * @param _key The key associated with the measurement.
+ * @param _content The content or value to publish.
+ * @param _timeUTC The timestamp in UTC. If greater than 0, it will be included in the payload.
+ *
+ * The function logs the process and handles HTTP communication with the InfluxDB server.
+ * It constructs the appropriate API URI based on the InfluxDB version and sends the data
+ * using an HTTP POST request.
+ */
 void InfluxDB::InfluxDBPublish(std::string _measurement, std::string _key, std::string _content, long int _timeUTC) {
     std::string apiURI;        
     std::string payload;

code/components/jomjol_influxdb/interface_influxdb.h

@@ -14,23 +14,68 @@
 #include "esp_log.h"
 
 
-// Interface to InfluxDB v1.x
-// void InfluxDBInit(std::string _influxDBURI, std::string _database, std::string _user, std::string _password);
-// void InfluxDBPublish(std::string _measurement, std::string _key, std::string _content, long int _timeUTC);
-
-// Interface to InfluxDB v2.x
-// void InfluxDB_V2_Init(std::string _uri, std::string _bucket, std::string _org, std::string _token);
-// void InfluxDB_V2_Publish(std::string _measurement, std::string _key, std::string _content, long int _timeUTC);
-
-
-
-void InfluxDBdestroy();
-
 enum InfluxDBVersion {
     INFLUXDB_V1,
     INFLUXDB_V2
 };
 
+/**
+ * @class InfluxDB
+ * @brief A class to handle connections and data publishing to InfluxDB servers.
+ * 
+ * This class supports both InfluxDB v1.x and v2.x versions. It provides methods to initialize
+ * the connection parameters, publish data, and destroy the connection.
+ * 
+ * @private
+ * @var std::string influxDBURI
+ * URI for the InfluxDB server.
+ * 
+ * @var std::string database
+ * Database name for InfluxDB v1.x.
+ * 
+ * @var std::string user
+ * Username for InfluxDB v1.x.
+ * 
+ * @var std::string password
+ * Password for InfluxDB v1.x.
+ * 
+ * @var std::string bucket
+ * Bucket name for InfluxDB v2.x.
+ * 
+ * @var std::string org
+ * Organization name for InfluxDB v2.x.
+ * 
+ * @var std::string token
+ * Token for InfluxDB v2.x.
+ * 
+ * @var InfluxDBVersion version
+ * Version of the InfluxDB server (v1.x or v2.x).
+ * 
+ * @var esp_http_client_handle_t httpClient
+ * HTTP client handle for making requests to the InfluxDB server.
+ * 
+ * @var void connectHTTP()
+ * Establishes an HTTP connection to the InfluxDB server.
+ * 
+ * @public
+ * @fn void InfluxDBInitV1(std::string _influxDBURI, std::string _database, std::string _user, std::string _password)
+ * Initializes the connection parameters for InfluxDB v1.x.
+ * 
+ * @fn void InfluxDBInitV2(std::string _influxDBURI, std::string _bucket, std::string _org, std::string _token)
+ * Initializes the connection parameters for InfluxDB v2.x.
+ * 
+ * @fn void InfluxDBdestroy()
+ * Destroys the InfluxDB connection.
+ * 
+ * @fn void InfluxDBPublish(std::string _measurement, std::string _key, std::string _content, long int _timeUTC)
+ * Publishes data to the InfluxDB server.
+ * 
+ * @param _measurement The measurement name.
+ * @param _key The key for the data point.
+ * @param _content The content or value of the data point.
+ * @param _timeUTC The timestamp in UTC for the data point.
+ */
+
 class InfluxDB {
 private:
     // Information for InfluxDB v1.x
@@ -62,11 +107,6 @@ public:
     void InfluxDBPublish(std::string _measurement, std::string _key, std::string _content, long int _timeUTC);
 };
 
-// Usage example:
-// InfluxDB influxDB;
-// influxDB.InfluxDBInit("http://your-influxdb-url", "your-database", "your-measurement", "user", "password");
-// influxDB.InfluxDBPublish("key", "content", "timestamp");
-// influxDB.InfluxDBdestroy();
 
 
 #endif //INTERFACE_INFLUXDB_H