Documentation and Usage Guide GitHub IoT Arduino Module

Version 1.0.0 - February 24, 2025

<p align="center"> <img style="width: -webkit-fill-available;"src="https://galihru.github.io/githubiotpy/img/GitHub%20IoT%20Logo.png" alt="GitHubIoT Logo"> </p>

Introduction

The githubiot library enables IoT devices based on ESP8266 or ESP32 microcontrollers to use GitHub as a data storage backend. This innovative approach eliminates the need for dedicated database servers while providing versioning capabilities, web accessibility, and integration with existing GitHub workflows.

This library handles all aspects of GitHub API communication, including authentication, file retrieval, content encoding/decoding, and update operations, allowing developers to focus on their IoT application rather than backend infrastructure.

---

Table of Contents

1. Introduction
2. Features
3. Dependencies
4. Installation
5. Integration GitHub Action
6. Library Components
7. API Reference
8. Usage Examples
9. Technical Background
10. Performance Considerations
11. Troubleshooting
12. Advanced Usage
13. License

---

Features

• GitHub Integration: Store and retrieve data from GitHub repositories
• JSON Support: Native handling of JSON data structures
• Cross-Platform: Compatible with both ESP8266 and ESP32 devices
• Version Control: Automatic handling of GitHub's SHA versioning
• Low Overhead: Minimal memory and processing requirements
• Secure Authentication: Support for GitHub token-based authentication
• Base64 Encoding: Automatic handling of GitHub's content encoding requirements

---

Dependencies

This library requires the following dependencies:

• Arduino Core (ESP8266 or ESP32)
• ArduinoJson (v6.x or later)
• base64 library
• WiFi library (included in ESP cores)
• HTTPClient library (included in ESP cores)

---

Installation

Installation by Search Arduino IDE

1. In the Arduino IDE, navigate to Library Manager > GitHubIoT
2. Klik <mark>INSTALL</mark>
3. Restart the Arduino IDE

Manual Installation

1. Download the library as a ZIP file from the GitHub repository
2. In the Arduino IDE, navigate to Sketch > Include Library > Add .ZIP Library
3. Select the downloaded ZIP file
4. Restart the Arduino IDE

Using Library Manager

1. Open the Arduino IDE
2. Navigate to Sketch > Include Library > Manage Libraries
3. In the search box, type "githubiot"
4. Find the library in the list and click "Install"

Installing Dependencies

Make sure to install all required dependencies using the Arduino Library Manager.

---

Integration GitHub Action

[!NOTE] This module integration with GitHub Action Workflow. Please README Documentation at Repository IoT GitHub

Usage Integration it

[!IMPORTANT]

1. Go to your repository settings, then select the Action menu then select the General menu after that select Read and write permissions The workflow has read and write permissions in the repository for all scopes in the Workflow permissions section.

2. Copy and paste the following snippet into your .yml file. Detail by IoT GitHub Marketplace
3. You can see detail snippet .yml file below

- name: Generate IoT Dashboard
  uses: galihru/iotgithub@v1.0.1
  with:
    json_filename: 'data.json'
    html_filename: 'index.html'
    css_filename: 'styles.css'
    site_title: 'My IoT Dashboard'
    chart_title: 'IoT Data Chart'
- name: Commit and push changes
  run: |
    git config --global user.name "GitHub Actions"
    git config --global user.email "actions@github.com"
    git add .
    if git commit -m "Auto-generated IoT dashboard files"; then
      git push
    else
      echo "No changes to commit."
    fi

---

Library Components

The library consists of two main files:

1. githubiot.h: Header file defining the class interface
2. githubiot.cpp: Implementation file containing the method definitions

Class Structure

class githubiot {
public:
    githubiot(const char* token, const char* repoUrl);
    String get_current_sha();
    void upload_to_github(DynamicJsonDocument doc, String& last_sha);
private:
    const char* _token;
    const char* _repo_url;
    String _last_sha;
};

---

API Reference

Constructor

githubiot::githubiot(const char* token, const char* repo_url)

Creates a new instance of the githubiot class.

Parameters:

• token: GitHub authentication token with 'Bearer ' prefix
• repo_url: GitHub API URL for the file to be updated

Example:

const char* token = "Bearer ghp_xxxxxxxxxxxxxxxxxxxx";
const char* repo_url = "https://api.github.com/repos/username/repo/contents/data.json";
githubiot iot_module(token, repo_url);

Get Current SHA

String githubiot::get_current_sha()

Retrieves the current SHA hash of the file from GitHub.

Returns:

• String containing the SHA hash, or empty string if the operation failed

Example:

String sha = iot_module.get_current_sha();
if (sha != "") {
    Serial.println("Current SHA: " + sha);
} else {
    Serial.println("Failed to get SHA");
}

Upload to GitHub

void githubiot::upload_to_github(DynamicJsonDocument doc, String& last_sha)

Uploads data to GitHub by updating the specified file.

Parameters:

• doc: ArduinoJson DynamicJsonDocument containing the data to upload
• last_sha: Reference to the current SHA string (will be updated with the new SHA)

Example:

DynamicJsonDocument doc(1024);
doc["sensor"] = "temperature";
doc["value"] = 25.5;
doc["timestamp"] = 1645729845;

String sha = iot_module.get_current_sha();
iot_module.upload_to_github(doc, sha);

---

Usage Examples

Basic Data Logging

#include <githubiot.h>

// Configuration
const char* ssid = "WiFi_SSID";
const char* password = "WiFi_Password";
const char* token = "Bearer ghp_xxxxxxxxxxxxxxxxxxxx";
const char* repo_url = "https://api.github.com/repos/username/repo/contents/sensor_log.json";

// Initialize the module
githubiot iot_module(token, repo_url);

void setup() {
    Serial.begin(115200);
    
    // Connect to WiFi
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) {
        delay(1000);
        Serial.print(".");
    }
    Serial.println("Connected to WiFi");
    
    // Get current SHA
    String sha = iot_module.get_current_sha();
    
    // Create data
    DynamicJsonDocument doc(1024);
    doc["device_id"] = "esp32_01";
    doc["readings"][0]["sensor"] = "temperature";
    doc["readings"][0]["value"] = 24.5;
    doc["readings"][1]["sensor"] = "humidity";
    doc["readings"][1]["value"] = 65.2;
    doc["timestamp"] = 1645729845;
    
    // Upload to GitHub
    iot_module.upload_to_github(doc, sha);
    Serial.println("Data uploaded");
}

void loop() {
    // Add periodic data logging as needed
    delay(3600000); // Update every hour
}

Time Series Data Collection

#include <githubiot.h>
#include <ArduinoJson.h>
#include <time.h>

// Configuration
const char* ssid = "WiFi_SSID";
const char* password = "WiFi_Password";
const char* token = "Bearer ghp_xxxxxxxxxxxxxxxxxxxx";
const char* repo_url = "https://api.github.com/repos/username/repo/contents/timeseries.json";
const char* ntpServer = "pool.ntp.org";

// Initialize the module
githubiot iot_module(token, repo_url);

void setup() {
    Serial.begin(115200);
    
    // Connect to WiFi
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) {
        delay(1000);
        Serial.print(".");
    }
    Serial.println("Connected to WiFi");
    
    // Initialize time
    configTime(0, 0, ntpServer);
}

void loop() {
    // Get current time
    time_t now;
    time(&now);
    
    // Read sensor data
    float temperature = readTemperature(); // Your sensor reading function
    
    // Get current SHA
    String sha = iot_module.get_current_sha();
    
    // Create or update time series data
    DynamicJsonDocument doc(2048);
    
    // If we have existing data, we need to parse it first
    if (sha != "") {
        // Here we would retrieve existing data and merge
        // This example simply creates new data each time
    }
    
    // Add new data point
    JsonObject newReading = doc["readings"].createNestedObject();
    newReading["timestamp"] = now;
    newReading["temperature"] = temperature;
    
    // Upload to GitHub
    iot_module.upload_to_github(doc, sha);
    Serial.println("Data uploaded");
    
    // Wait before next reading
    delay(900000); // 15 minutes
}

float readTemperature() {
    // Implementation of your sensor reading
    return 23.5; // Example value
}

---

Technical Background

GitHub API Interaction

The library communicates with the GitHub API using HTTP requests. Each file in a GitHub repository has a unique SHA hash that changes when the file is modified. When updating a file, you must provide the current SHA to ensure you're updating the latest version.

The workflow follows this sequence:

1. Retrieve the current file metadata (including SHA) via GET request
2. Prepare the new content
3. Encode the content in Base64 (GitHub requirement)
4. Send a PUT request with the new content and current SHA
5. Receive the updated file metadata (including new SHA)

JSON Data Format

JSON (JavaScript Object Notation) is used as the data format due to its flexibility and widespread support. The ArduinoJson library provides efficient JSON processing on memory-constrained devices.

Base64 Encoding

GitHub requires