• InfluxDB Arduino Client
    • Basic code for InfluxDB 2
    • Basic code for InfluxDB 1
    • Connecting to InfluxDB Cloud 2
    • Writing in Batches
      • Timestamp
      • Configure Time
      • Batch Size
    • Buffer Handling and Retrying
    • Write Options
    • HTTP Options
    • Secure Connection
      • InfluxDb 2
      • InfluxDb 1
    • Querying
    • Original API
      • Initialization
      • Sending a single measurement
      • Write multiple data points at once
    • Troubleshooting
    • Contributing
    • License

    Arduino - 图1InfluxDB Arduino Client

    Simple Arduino client for writing and reading data from InfluxDB, it doesn’t matter whether a local server or InfluxDB Cloud. Library supports authentication, secure communication over TLS, batching, automatic retrying on server backpressure and connection failure.

    It also allows setting data in various formats, automatically escapes special characters and offers specifying timestamp in various precisions.

    Library support both InfluxDB 2 and InfluxDB 1.

    This is a new implementation and API, original API is still supported.

    Supported devices: ESP8266 (2.7+) and ESP32 (1.0.3+).

    Arduino - 图2Basic code for InfluxDB 2

    Using client is very easy. After seting up InfluxDB 2 server, first define connection parameters and a client instance:

    1. // InfluxDB 2 server url, e.g. http://192.168.1.48:8086 (Use: InfluxDB UI -> Load Data -> Client Libraries)
    2. #define INFLUXDB_URL "influxdb-url"
    3. // InfluxDB 2 server or cloud API authentication token (Use: InfluxDB UI -> Load Data -> Tokens -> <select token>)
    4. #define INFLUXDB_TOKEN "token"
    5. // InfluxDB 2 organization name or id (Use: InfluxDB UI -> Settings -> Profile -> <name under tile> )
    6. #define INFLUXDB_ORG "org"
    7. // InfluxDB 2 bucket name (Use: InfluxDB UI -> Load Data -> Buckets)
    8. #define INFLUXDB_BUCKET "bucket"
    10. // Single InfluxDB instance
    11. InfluxDBClient client(INFLUXDB_URL, INFLUXDB_ORG, INFLUXDB_BUCKET, INFLUXDB_TOKEN);

    The next step is adding data. Single data row is represented by the Point class. It consists of measurement name (like a table name), tags (which labels data) and fields (values to store):

    1. // Define data point with measurement name 'device_status`
    2. Point pointDevice("device_status");
    3. // Set tags
    4. pointDevice.addTag("device", "ESP8266");
    5. pointDevice.addTag("SSID", WiFi.SSID());
    6. // Add data
    7. pointDevice.addField("rssi", WiFi.RSSI());
    8. pointDevice.addField("uptime", millis());

    And finally, write data to db:

    1. // Write data
    2. client.writePoint(pointDevice);

    Complete source code is available in BasicWrite example.

    Data can be seen in the InfluxDB UI immediately. Use Data Explorer or create a Dashboard.

    Arduino - 图3Basic code for InfluxDB 1

    Using InfluxDB Arduino client for InfluxDB 1 is almost the same as for InfluxDB 2. The only difference is that InfluxDB 1 uses database as classic name for data storage instead of bucket and the server is unsecured by default. There is just different InfluxDBClient contructor and setConnectionParametersV1 function for setting also security params. Everything else remains the same.

    1. // InfluxDB server url, e.g. http://192.168.1.48:8086 (don't use localhost, always server name or ip address)
    2. #define INFLUXDB_URL "influxdb-url"
    3. // InfluxDB database name 
    4. #define INFLUXDB_DB_NAME "database"
    6. // Single InfluxDB instance
    7. InfluxDBClient client(INFLUXDB_URL, INFLUXDB_DB_NAME);
    9. // Define data point with measurement name 'device_status`
    10. Point pointDevice("device_status");
    11. // Set tags
    12. pointDevice.addTag("device", "ESP8266");
    13. pointDevice.addTag("SSID", WiFi.SSID());
    14. // Add data
    15. pointDevice.addField("rssi", WiFi.RSSI());
    16. pointDevice.addField("uptime", millis());
    18. // Write data
    19. client.writePoint(pointDevice);

    Complete source code is available in BasicWrite example

    Arduino - 图4Connecting to InfluxDB Cloud 2

    Instead of setting up local InfluxDB 2 server, it is possible to quickly start with InfluxDB Cloud 2 with Free Plan.

    Connecting Arduino client to InfuxDB Cloud server requires few additional steps. InfluxDBCloud uses secure communication (https) and we need to tell the client to trust this connection. Connection parameters are almost the same as above, the only difference is that server URL now points to the InfluxDB Cloud 2, where you’ve got after you’ve finished creating InfluxDB Cloud 2 subscription. You will find correct server URL in InfluxDB UI -> Load Data -> Client Libraries.

    1. //Include also InfluxClould 2 CA certificate
    2. #include <InfluxDbCloud.h>
    3. // InfluxDB 2 server or cloud url, e.g. https://eu-central-1-1.aws.cloud2.influxdata.com (Use: InfluxDB UI -> Load Data -> Client Libraries)
    4. #define INFLUXDB_URL "influxdb-url"
    5. // InfluxDB 2 server or cloud API authentication token (Use: InfluxDB UI -> Load Data -> Tokens -> <select token>)
    6. #define INFLUXDB_TOKEN "token"
    7. // InfluxDB 2 organization name or id (Use: InfluxDB UI -> Settings -> Profile -> <name under tile> )
    8. #define INFLUXDB_ORG "org"
    9. // InfluxDB 2 bucket name (Use: InfluxDB UI -> Load Data -> Buckets)
    10. #define INFLUXDB_BUCKET "bucket"

    You need to pass an additional parameter to the client constructor, which is a certificate of the server to trust. Constant InfluxDbCloud2CACert contains the InfluxDB Cloud 2 CA certificate, which is predefined in this library:

    1. // Single InfluxDB instance
    2. InfluxDBClient client(INFLUXDB_URL, INFLUXDB_ORG, INFLUXDB_BUCKET, INFLUXDB_TOKEN, InfluxDbCloud2CACert);

    Read more about secure connection.

    Additionally, time needs to be synced:

    1. // Synchronize time with NTP servers and set timezone
    2. // Accurate time is necessary for certificate validaton and writing in batches
    3. // For the fastest time sync find NTP servers in your area: https://www.pool.ntp.org/zone/
    4. configTzTime(TZ_INFO "pool.ntp.org", "time.nis.gov");

    Read more about time synchronization in Configure Time.

    Defining data and writing it to the DB is the same as in the case of BasicWrite:

    1. // Define data point with measurement name 'device_status`
    2. Point pointDevice("device_status");
    3. // Set tags
    4. pointDevice.addTag("device", "ESP8266");
    5. pointDevice.addTag("SSID", WiFi.SSID());
    6. // Add data
    7. pointDevice.addField("rssi", WiFi.RSSI());
    8. pointDevice.addField("uptime", millis());
    10. // Write data
    11. client.writePoint(pointDevice);

    Complete source code is available in SecureWrite example.

    Arduino - 图5Writing in Batches

    InfluxDB client for Arduino can write data in batches. A batch is simply a set of points that will be sent at once. To create a batch, the client will keep all points until the number of points reaches the batch size and then it will write all points at once to the InfluDB server. This is often more efficient than writing each point separately.

    Arduino - 图6Timestamp

    If using batch writes, the timestamp should be employed. Timestamp specifies the time where data was gathered and it is used in the form of a number of seconds (milliseconds, etc) from epoch (1.1.1970) UTC. If points have no timestamp assigned, InfluxDB assigns timestamp at the time of writing, which could happen much later than the data has been obtained, because final batch write will happen when the batch is full (or when flush buffer is forced).

    InfuxDB allows sending timestamp in various precisions - nanoseconds, microseconds, milliseconds or seconds. The milliseconds precision is usually enough for using on Arduino. Maximum avavailable precision is microseconds. Setting to nanosecond will just add zeroes for microseconds fraction.

    The client has to be configured with a time precision. The default settings is not using the timestamp, which means server will assign timestamp. The setWriteOptions functions allow setting custom WriteOptions params and one of them is write precision:

    1. // Set write precision to milliseconds. Leave other parameters default.
    2. client.setWriteOptions(WriteOptions().writePrecision(WritePrecision::MS));

    When a write precision is configured, the client will automatically assign current time to the timestamp of each written point, which doesn’t have a timestamp assigned.

    If you want to manage timestamp on your own, there are several ways how to set timestamp explicitly.

    • setTime(WritePrecision writePrecision) - Sets timestamp to actual time in desired precision
    • setTime(unsigned long long timestamp) - Sets timestamp in an offset since epoch. Correct precision must be set InfluxDBClient::setWriteOptions.
    • setTime(String timestamp) - Sets timestamp in an offset since epoch. Correct precision must be set InfluxDBClient::setWriteOptions.

    The getTime() method allows copying timestamp between points.

    Arduino - 图7Configure Time

    Dealing with timestamps, and also validating server or CA certificate, requires the device has correctly set time. This can be done with just one line of code:

    1. // Synchronize time with NTP servers and set timezone
    2. // Accurate time is necessary for certificate validaton and writing in batches
    3. // For the fastest time sync find NTP servers in your area: https://www.pool.ntp.org/zone/
    4. configTzTime("PST8PDT", "pool.ntp.org", "time.nis.gov");

    The configTzTime function starts the time synchronization with NTP servers. The first parameter specifies timezone information, which is important for distinguishing UTC and a local timezone and for daylight saving changes. The last two string parameters are the internet addresses of NTP servers. Check pool.ntp.org for address of some local NTP servers.

    Timezone string details are described at https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html. Values for some timezones:

    • Central Europe: CET-1CEST,M3.5.0,M10.5.0/3
    • Eastern: EST5EDT
    • Japanesse: JST-9
    • Pacific Time: PST8PDT

    There is also another function for syncing the time, which takes timezone and DST offset. As DST info is set via static offset it will create local time problem when DST change will occur. It’s declaration is following:

    1. configTime(long gmtOffset_sec, int daylightOffset_sec, const char* server1, const char* server2 = nullptr, const char* server3 = nullptr);

    In the example code it would be:

    1. // Synchronize time with NTP servers
    2. // Accurate time is necessary for certificate validaton and writing in batches
    3. configTime(3600, 3600, "pool.ntp.org", "time.nis.gov");

    Both configTzTime and configTime functions are asynchronous. This means that calling the functions just starts the time synchronization. Time is often not synchronized yet upon returning from call.

    There is a helper function timeSync provided with the this library. The function starts time synchronization by calling the configTzTime and waits maximum 20 seconds for time is synchronized. It prints progress info and final local time to the Serial. timeSync has the same signature and configTzTime and it is included with the main header file InfluxDbClient.h:

    1. // Synchronize time with NTP servers and waits for completition. Prints waiting progress and final synchronized time to the Serial.
    2. // Accurate time is necessary for certificate validion and writing points in batch
    3. // For the fastest time sync find NTP servers in your area: https://www.pool.ntp.org/zone/
    4. void timeSync(const char *tzInfo, const char* ntpServer1, const char* ntpServer2 = nullptr, const char* ntpServer3 = nullptr);

    Arduino - 图8Batch Size

    Setting batch size depends on data gathering and DB updating strategy.

    If data is written in short periods (seconds), batch size should be according to expected write periods and update frequency requirements. For example, if you would like to see updates (on the dashboard or in processing) each minute and you are measuring single data (1 point) each 10s (6 points per minute), batch size should be 6. In case it is enough to update each hour and you are creating 1 point at once each minute, your batch size should be 60. The maximum recommended batch size is 200. It depends on the RAM of the device (80KB for ESP8266 and 512KB for ESP32).

    In case that data should be written in longer periods and gathered data consists of several points batch size should be set to an expected number of points.

    To set batch size we use WriteOptions object and setWriteOptions function:

    1. // Enable messages batching
    2. client.setWriteOptions(WriteOptions().batchSize(10));

    Writing point will add a point to the underlying buffer until the batch size is reached:

    1. // Write first point to the buffer
    2. // Buffered write always returns `true`
    3. client.writePoint(point1);
    4. // Write second point to the buffer
    5. client.writePoint(point2);
    6. ..
    7. // Write nineth point to the buffer
    8. client.writePoint(point9);
    9. // Writing tenth point will cause flushing buffer and returns actual write result.
    10. if(!client.writePoint(point10)) {
    11.     Serial.print("InfluxDB write failed: ");
    12.     Serial.println(client.getLastErrorMessage());
    13. }

    In case of a number of points is not always the same, set batch size to the maximum number of points and use the flushBuffer() function to force writing to DB. See Buffer Handling for more details.

    Arduino - 图9Buffer Handling and Retrying

    InfluxDB contains an underlying buffer for handling writing in batches and automatic retrying on server backpressure and connection failure.

    Its size is controled by the bufferSize param of WriteOptions object:

    1. // Increase buffer to allow caching of failed writes
    2. client.setWriteOptions(WriteOptions().bufferSize(50));

    The recommended size is at least 2 x batch size.

    State of the buffer can be determined via two functions:

    • isBufferEmpty() - Returns true if buffer is empty
    • isBufferFull() - Returns true if buffer is full

    Full buffer can occur when there is a problem with an internet connection or the InfluxDB server is overloaded. In such cases, points to write remains in buffer. When more points are added and connection problem remains, the buffer will reach the top and new points will overwrite older points.

    Each attempt to write a point will try to send older points in the buffer. So, the isBufferFull() function can be used to skip low priority points.

    The flushBuffer() function can be used to force writing, even the number of points in the buffer is lower than the batch size. With the help of the isBufferEmpty() function a check can be made before a device goes to sleep:

    1.  // Check whether buffer in not empty
    2.  if (!client.isBufferEmpty()) {
    3.      // Write all remaining points to db
    4.      client.flushBuffer();
    5.  }

    Other functions for dealing with buffer:

    • checkBuffer() - Checks point buffer status and flushes if the number of points reaches batch size or flush interval runs out. This main function for controlling buffer and it is used internally.
    • resetBuffer() - Clears the buffer.

    Check SecureBatchWrite example for example code of buffer handling functions.

    Arduino - 图10Write Options

    Writing points can be controlled via WriteOptions, which is set in setWriteOptions function:

    ParameterDefault ValueMeaning
    writePrecisionWritePrecision::NoTimeTimestamp precision of written data
    batchSize1Number of points that will be written to the database at once
    bufferSize5Maximum number of points in buffer. Buffer contains new data that will be written to the database and also data that failed to be written due to network failure or server overloading
    flushInterval60Maximum time(in seconds) data will be held in buffer before are written to the db

    Arduino - 图11HTTP Options

    HTTPOptions controls some aspects of HTTP communication and they are set via setHTTPOptions function:

    ParameterDefault ValueMeaning
    reuseConnectionfalseWhether HTTP connection should be kept open after inital communicaton. Usable for frequent writes/queries.
    httpReadTimeout5000Timeout (ms) for reading server response

    Arduino - 图12Secure Connection

    Connecting to a secured server requires configuring client to trust the server. This is achieved by providing client with a server certificate, certificate authority certificate or certificate SHA1 fingerprint.

    Note: HTTPClient in the current ESP32 arduino SDK (1.0.4) doesn’t validate server certificate, so providing server certificate is not necessary. But it is definitely safer to do it, as it can change in the future. Other limitation of ESP32 arduino SDK (1.0.4) is that WiFiClientSecure doesn’t support fingerprint to validate server certificate.

    Certificate (in PEM format) or SHA1 fingerprint can be placed in flash memory to save initial RAM:

    1. // Certificate of Certificate Authority of InfluxData Cloud 2 servers
    2. const char InfluxDbCloud2CACert[] PROGMEM =  R"EOF( 
    3. -----BEGIN CERTIFICATE-----
    4. MIIGEzCCA/ugAwIBAgIQfVtRJrR2uhHbdBYLvFMNpzANBgkqhkiG9w0BAQwFADCB
    5. iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl
    6. cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV
    7. BAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTgx
    8. MTAyMDAwMDAwWhcNMzAxMjMxMjM1OTU5WjCBjzELMAkGA1UEBhMCR0IxGzAZBgNV
    9. BAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UEBxMHU2FsZm9yZDEYMBYGA1UE
    10. ChMPU2VjdGlnbyBMaW1pdGVkMTcwNQYDVQQDEy5TZWN0aWdvIFJTQSBEb21haW4g
    11. VmFsaWRhdGlvbiBTZWN1cmUgU2VydmVyIENBMIIBIjANBgkqhkiG9w0BAQEFAAOC
    12. AQ8AMIIBCgKCAQEA1nMz1tc8INAA0hdFuNY+B6I/x0HuMjDJsGz99J/LEpgPLT+N
    13. TQEMgg8Xf2Iu6bhIefsWg06t1zIlk7cHv7lQP6lMw0Aq6Tn/2YHKHxYyQdqAJrkj
    14. eocgHuP/IJo8lURvh3UGkEC0MpMWCRAIIz7S3YcPb11RFGoKacVPAXJpz9OTTG0E
    15. oKMbgn6xmrntxZ7FN3ifmgg0+1YuWMQJDgZkW7w33PGfKGioVrCSo1yfu4iYCBsk
    16. Haswha6vsC6eep3BwEIc4gLw6uBK0u+QDrTBQBbwb4VCSmT3pDCg/r8uoydajotY
    17. uK3DGReEY+1vVv2Dy2A0xHS+5p3b4eTlygxfFQIDAQABo4IBbjCCAWowHwYDVR0j
    18. BBgwFoAUU3m/WqorSs9UgOHYm8Cd8rIDZsswHQYDVR0OBBYEFI2MXsRUrYrhd+mb
    19. +ZsF4bgBjWHhMA4GA1UdDwEB/wQEAwIBhjASBgNVHRMBAf8ECDAGAQH/AgEAMB0G
    20. A1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAbBgNVHSAEFDASMAYGBFUdIAAw
    21. CAYGZ4EMAQIBMFAGA1UdHwRJMEcwRaBDoEGGP2h0dHA6Ly9jcmwudXNlcnRydXN0
    22. LmNvbS9VU0VSVHJ1c3RSU0FDZXJ0aWZpY2F0aW9uQXV0aG9yaXR5LmNybDB2Bggr
    23. BgEFBQcBAQRqMGgwPwYIKwYBBQUHMAKGM2h0dHA6Ly9jcnQudXNlcnRydXN0LmNv
    24. bS9VU0VSVHJ1c3RSU0FBZGRUcnVzdENBLmNydDAlBggrBgEFBQcwAYYZaHR0cDov
    25. L29jc3AudXNlcnRydXN0LmNvbTANBgkqhkiG9w0BAQwFAAOCAgEAMr9hvQ5Iw0/H
    26. ukdN+Jx4GQHcEx2Ab/zDcLRSmjEzmldS+zGea6TvVKqJjUAXaPgREHzSyrHxVYbH
    27. 7rM2kYb2OVG/Rr8PoLq0935JxCo2F57kaDl6r5ROVm+yezu/Coa9zcV3HAO4OLGi
    28. H19+24rcRki2aArPsrW04jTkZ6k4Zgle0rj8nSg6F0AnwnJOKf0hPHzPE/uWLMUx
    29. RP0T7dWbqWlod3zu4f+k+TY4CFM5ooQ0nBnzvg6s1SQ36yOoeNDT5++SR2RiOSLv
    30. xvcRviKFxmZEJCaOEDKNyJOuB56DPi/Z+fVGjmO+wea03KbNIaiGCpXZLoUmGv38
    31. sbZXQm2V0TP2ORQGgkE49Y9Y3IBbpNV9lXj9p5v//cWoaasm56ekBYdbqbe4oyAL
    32. l6lFhd2zi+WJN44pDfwGF/Y4QA5C5BIG+3vzxhFoYt/jmPQT2BVPi7Fp2RBgvGQq
    33. 6jG35LWjOhSbJuMLe/0CjraZwTiXWTb2qHSihrZe68Zk6s+go/lunrotEbaGmAhY
    34. LcmsJWTyXnW0OMGuf1pGg+pRyrbxmRE1a6Vqe8YAsOf4vmSyrcjC8azjUeqkk+B5
    35. yOGBQMkKW+ESPMFgKuOXwIlCypTPRpgSabuY0MLTDXJLR27lk8QyKGOHQ+SwMj4K
    36. 00u/I5sUKUErmgQfky3xxzlIPK1aEn8=
    37. -----END CERTIFICATE-----
    38. )EOF";
    40. // Fingerprint of Certificate Authority of InfluxData Cloud 2 servers
    41. const char InfluxDbCloud2CAFingerprint[] PROGMEM = "9B:62:0A:63:8B:B1:D2:CA:5E:DF:42:6E:A3:EE:1F:19:36:48:71:1F";

    Arduino - 图13InfluxDb 2

    There are two ways to set certificate or fingerprint to trust a server:

    • Use full param constructor
    1. // InfluxDB client instance with preconfigured InfluxCloud certificate
    2. InfluxDBClient client(INFLUXDB_URL, INFLUXDB_ORG, INFLUXDB_BUCKET, INFLUXDB_TOKEN, InfluxDbCloud2CACert);
    • Use setConnectionParams function:
    1. // InfluxDB client instance 
    2. InfluxDBClient client;
    4. void setup() {
    5.     // configure client
    6.     client.setConnectionParams(INFLUXDB_URL, INFLUXDB_ORG, INFLUXDB_BUCKET, INFLUXDB_TOKEN, InfluxDbCloud2CACert);
    7. }

    Arduino - 图14InfluxDb 1

    Use setConnectionParamsV1 function:

    1. // InfluxDB client instance 
    2. InfluxDBClient client;
    4. void setup() {
    5.     // configure client
    6.     client.setConnectionParamsV1(INFLUXDB_URL, INFLUXDB_DATABASE, INFLUXDB_USER, INFLUXDB_PASSWORD, InfluxDbCloud2CACert);
    7. }

    Another important prerequisity to sucessfully validate server or CA certificate is to have properly synchronized time. More on this in Configure Time.

    Note: Time synchronization is not required for validating server certificate via SHA1 fingerprint.

    Arduino - 图15Querying

    InfluxDB 2 and InfluxDB 1.7+ (with enabled flux) uses Flux to process and query data. InfluxDB client for Arduino offers a simple, but powerful, way how to query data with query function. It parses response line by line, so it can read a huge responses (thousands data lines), without consuming a lot device memory.

    The query returns FluxQueryResult object, which parses response and provides useful getters for accessing values from result set.

    InfluxDB flux query result set is returned in the CSV format. In the example bellow, the first line contains type information and the second columns name and the rest is data:

    1. #datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,long,string,string,string,string
    2. ,result,table,_start,_stop,_time,_value,SSID,_field,_measurement,device
    3. ,_result,0,2020-05-18T15:06:00.475253281Z,2020-05-19T15:06:00.475253281Z,2020-05-19T13:07:13Z,-55,667G,rssi,wifi_status,ESP32
    4. ,_result,0,2020-05-18T15:06:00.475253281Z,2020-05-19T15:06:00.475253281Z,2020-05-19T13:07:27Z,-54,667G,rssi,wifi_status,ESP32
    5. ,_result,0,2020-05-18T15:06:00.475253281Z,2020-05-19T15:06:00.475253281Z,2020-05-19T13:07:40Z,-54,667G,rssi,wifi_status,ESP32
    6. ,_result,0,2020-05-18T15:06:00.475253281Z,2020-05-19T15:06:00.475253281Z,2020-05-19T13:07:54Z,-54,667G,rssi,wifi_status,ESP32
    7. ,_result,0,2020-05-18T15:06:00.475253281Z,2020-05-19T15:06:00.475253281Z,2020-05-19T13:08:07Z,-55,667G,rssi,wifi_status,ESP32
    8. ,_result,0,2020-05-18T15:06:00.475253281Z,2020-05-19T15:06:00.475253281Z,2020-05-19T13:08:20Z,-56,667G,rssi,wifi_status,ESP32

    Accessing data using FluxQueryResult requires knowing the query result structure, especially the name and the type of the column. The best practise is to tune query in the InfluxDB Data Explorer and use the final query with this library.

    Browsing thought the result set is done by repeatedly calling the next() method, until it returns false. Unsuccesful reading is distinqushed by non empty value from the getError() method. As a flux query result can contain several tables, differing by grouping key, use the hasTableChanged() method to know when there is a new table. Single values are returned using the getValueByIndex() or getValueByName() methods. All row values at once are retreived by the getValues() method. Always call the close() method at the of reading.

    A value in the flux query result column, retrieved by the getValueByIndex() or getValueByName() methods, is represented by the FluxValue object. It provides getter methods for supported flux types:

    Flux typeGetterC type
    longgetLong()long
    unsignedLonggetUnsignedLong()unsingned long
    dateTime:RFC3339, dateTime:RFC3339NanogetDateTime()FluxDateTime
    boolgetBool()bool
    doublebooldouble
    string, base64binary, durationgetString()String

    Calling improper type getter will result in a zero (empty) value.

    Check for null (missing) value usig the isNull() method.

    Use the getRawValue() method for getting original string form.

    1. // Construct a Flux query
    2. // Query will find RSSI for last 24 hours for each connected WiFi network with this device computed by given selector function
    3. String query = "from(bucket: \"my-bucket\") |> range(start: -24h) |> filter(fn: (r) => r._measurement == \"wifi_status\" and r._field == \"rssi\"";
    4. query += "and r.device == \"ESP32\")";
    5. query += "|> max()";
    7. // Send query to the server and get result
    8. FluxQueryResult result = client.query(query);
    10. // Iterate over rows. Even there is just one row, next() must be called at least once.
    11. while (result.next()) {
    12.   // Get typed value for flux result column 'SSID'
    13.   String ssid = result.getValueByName("SSID").getString();
    14.   Serial.print("SSID '");
    15.   Serial.print(ssid);
    17.   Serial.print("' with RSSI ");
    19.   // Get converted value for flux result column '_value' where there is RSSI value
    20.   long value = result.getValueByName("_value").getLong();
    21.   Serial.print(value);
    23.   // Format date-time for printing
    24.   // Format string according to http://www.cplusplus.com/reference/ctime/strftime/
    25.   String timeStr = time.format("%F %T");
    27.   Serial.print(" at ");
    28.   Serial.print(timeStr);
    30.   Serial.println();
    31. }
    33. // Check if there was an error
    34. if(result.getError() != "") {
    35.   Serial.print("Query result error: ");
    36.   Serial.println(result.getError());
    37. }

    Complete source code is available in QueryAggregated example.

    Arduino - 图16Original API

    Arduino - 图17Initialization

    1.  #define INFLUXDB_HOST "192.168.0.32"
    2.  #define INFLUXDB_PORT 1337
    3.  #define INFLUXDB_DATABASE "test"
    4.  //if used with authentication
    5.  #define INFLUXDB_USER "user"
    6.  #define INFLUXDB_PASS "password"
    8.  // connect to WiFi
    10.  Influxdb influx(INFLUXDB_HOST); // port defaults to 8086
    11.  // or to use a custom port
    12.  Influxdb influx(INFLUXDB_HOST, INFLUXDB_PORT);
    14.  // set the target database
    15.  influx.setDb(INFLUXDB_DATABASE);
    16.  // or use a db with auth
    17.  influx.setDbAuth(INFLUXDB_DATABASE, INFLUXDB_USER, INFLUXDB_PASS) // with authentication
    19. // To use the v2.0 InfluxDB
    20. influx.setVersion(2);
    21. influx.setOrg("myOrganization");
    22. influx.setBucket("myBucket");
    23. influx.setToken("myToken");
    24. influx.setPort(8086);

    Arduino - 图18Sending a single measurement

    Using an InfluxData object:

    1. // create a measurement object
    2. InfluxData measurement ("temperature");
    3. measurement.addTag("device", d2);
    4. measurement.addTag("sensor", "dht11");
    5. measurement.addValue("value", 24.0);
    7. // write it into db
    8. influx.write(measurement);

    Using raw-data

    1.  influx.write("temperature,device=d2,sensor=dht11 value=24.0")

    Arduino - 图19Write multiple data points at once

    Batching measurements and send them with a single request will result in a much higher performance.

    1. InfluxData measurement1 = readTemperature()
    2. influx.prepare(measurement1)
    4. InfluxData measurement2 = readLight()
    5. influx.prepare(measurement2)
    7. InfluxData measurement3 = readVoltage()
    8. influx.prepare(measurement3)
    10. // writes all prepared measurements with a single request into db.
    11. boolean success = influx.write();

    Arduino - 图20Troubleshooting

    All db methods return status. Value false means something went wrong. Call getLastErrorMessage() to get the error message.

    When error message doesn’t help to explain the bad behavior, go to the library sources and in the file src/InfluxDBClient.cpp uncomment line 44:

    1. // Uncomment bellow in case of a problem and rebuild sketch
    2. #define INFLUXDB_CLIENT_DEBUG

    Then upload your sketch again and see the debug output in the Serial Monitor.

    If you couldn’t solve a problem by yourself, please, post an issue including the debug output.

    Arduino - 图21Contributing

    If you would like to contribute code you can do through GitHub by forking the repository and sending a pull request into the master branch.

    Arduino - 图22License

    The InfluxDB Arduino Client is released under the MIT License.