TelemetryHarborSDK for C++ (Arduino)

A C++ client SDK for sending telemetry data to the Telemetry Harbor service, designed for Arduino-based microcontrollers like the ESP32 and ESP8266.

This library simplifies sending sensor data by handling HTTP communication, JSON serialization, and robust error handling with automatic retries.

Repo Link: https://github.com/TelemetryHarbor/harbor-sdk-c-plus-plus

Features

• ✅ Simple Interface: Easily send data with send() and sendBatch() methods.
• 📦 JSON Handling: Automatically serializes data structs into the required JSON format.
• ⚙️ Robust Retries: Implements exponential backoff to automatically retry sending data on network or server errors.
• 📡 ESP32 & ESP8266 Ready: Built for the most popular Wi-Fi enabled microcontrollers in the Arduino ecosystem.
• 🔌 Extensible: Easily add new data structures for different telemetry types.

Installation

1. Install from Library Manager:
   • Open the Arduino IDE.
   • Go to Sketch > Include Library > Manage Libraries....
   • Search for "TelemetryHarborSDK" and click "Install".
   • The IDE will prompt you to also install its dependency, "ArduinoJson". Click "Install all".
2. Manual Installation:
   • Download the latest release from the repository as a ZIP file.
   • In the Arduino IDE, go to Sketch > Include Library > Add .ZIP Library... and select the downloaded file.
   • Install the ArduinoJson library separately from the Library Manager.

Quickstart Guide

Here is a basic example of how to use the library to send a single sensor reading.

#include <WiFi.h>
#include "HarborClient.h"

const char* ssid = "Harbor-WIFI";
const char* password = "";

// Replace with your actual endpoint and API key
const char* harborEndpoint = "ENDPOINT";
const char* harborApiKey = "API_KEY";

HarborClient harbor(harborEndpoint, harborApiKey);

void setup() {
  Serial.begin(115200);
  delay(1000);

  Serial.println("Connecting to WiFi...");
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println(" Connected!");
}

void loop() {
  GeneralReading reading;
  reading.ship_id = "esp32-freighter-01";
  reading.cargo_id = "temperature-hold-3";
  reading.value = 25.5 + random(-2, 2); // Simulated sensor reading
  reading.time = "2025-06-24T19:24:00.948Z";

  Serial.println("Sending a reading...");
  int statusCode = harbor.send(reading);

  if (statusCode >= 200 && statusCode < 300) {
    Serial.printf("✅ Successfully sent data (Status: %d)\n", statusCode);
  } else {
    Serial.printf("❌ Failed to send data (Status: %d)\n", statusCode);
  }

  delay(30000); // Wait 30 seconds
}

---

API Reference

HarborClient(const char* endpoint, const char* api_key)

The constructor for the client.

• endpoint: The URL of your Telemetry Harbor ingestion endpoint.
• api_key: Your unique API key for authentication.

int send(const GeneralReading& reading)

Sends a single telemetry reading.

• reading: A GeneralReading struct containing the data.
• Returns: The final HTTP status code after all retries.

int sendBatch(const GeneralReading readings[], int count)

Sends an array of readings in a single HTTP request.

• readings: A C-style array of GeneralReading structs.
• count: The number of elements in the array.
• Returns: The final HTTP status code.

GeneralReading Struct

The primary data structure for telemetry.

struct GeneralReading {
    String ship_id;
    String cargo_id;
    float value;
    String time; // Optional, ISO8601 format (e.2025-07-17T10:08:55Z)
};