xteink-github-sync/MANUAL_INTEGRATION.md

GitHub Sync — Manual Integration (Advanced)

If you prefer not to use the auto-patcher (patch.py), follow these steps to integrate GitHub Sync into a CrossPoint/xteink firmware tree manually.

Files to copy into your CrossPoint repo

Copy the files from this repository into your CrossPoint firmware repo at the following destinations:

Source (this repo)	Destination (CrossPoint repo)
GitHubSync.h	include/GitHubSync.h
GitHubSync.cpp	src/github_sync/GitHubSync.cpp
GitHubSyncSettingsActivity.h	include/GitHubSyncSettingsActivity.h
GitHubSyncSettingsActivity.cpp	src/activities/settings/GitHubSyncSettingsActivity.cpp

Notes:

• Ensure the destination folders exist (src/github_sync/, src/activities/settings/).
• Your CrossPoint repo may use slightly different folder names; the important part is that your build system compiles the .cpp files and that includes resolve from include/.

1) platformio.ini dependency

Make sure ArduinoJson v7 is available in lib_deps:

bblanchon/ArduinoJson @ ^7

If your project already depends on ArduinoJson, do not duplicate it.

2) Call sync after WiFi connects (boot/startup path)

Find your boot path after WiFi is connected (often near where OTA update checks happen) and add:

#include "GitHubSync.h"

// After WiFi is up:
if (GitHubSync::isConfigured()) {
    GitHubSyncResult result = GitHubSync::sync();
    if (result != GitHubSyncResult::OK) {
        // Replace this with your project's preferred UI/logging mechanism.
        // (Some CrossPoint forks use LOG_ERR; others use Serial; some show a toast.)
        LOG_ERR("SYNC", "%s", GitHubSync::resultMessage(result));
        // Or: Serial.printf("[SYNC] %s\n", GitHubSync::resultMessage(result));
    }
}

Important:

• The return type is GitHubSyncResult (not SyncResult).
• If your firmware does not define LOG_ERR, use whatever logging you already use (or Serial.printf).

3) Add a Settings entry ("GitHub Sync")

In your settings menu implementation (commonly something like SettingsActivity.cpp):

1. Include the activity:

#include "GitHubSyncSettingsActivity.h"

2. Add a new item in the settings list that navigates to the activity.

The exact code depends on your UI framework, but the action should instantiate/push:

std::make_unique<GitHubSyncSettingsActivity>(renderer, mappedInput)

3. Add a translation string (if your project uses translations):

• Add a string ID similar to STR_GITHUB_SYNC
• Map it to the label GitHub Sync in your translation files

4) (Optional) Web settings editor schema

If your CrossPoint fork has a web settings editor that can read/write NVS keys, add these keys:

{ "ns": "github_sync", "key": "username", "label": "GitHub Username", "type": "text" },
{ "ns": "github_sync", "key": "pat",      "label": "GitHub PAT",      "type": "password" },
{ "ns": "github_sync", "key": "repo",     "label": "Repo name",       "type": "text" },
{ "ns": "github_sync", "key": "branch",   "label": "Branch",          "type": "text" }

Namespace/keys used by firmware:

• Namespace: github_sync
• Keys: username, pat, repo, branch

5) GitHub repo setup (for content)

1. Create a GitHub repo (private recommended)
2. Add .epub files to the repo root
3. Optionally add sleep.bmp to the repo root (152x152 grayscale BMP)
4. Create a PAT with permission to read repository contents
5. On device: Settings → GitHub Sync:
   • username
   • PAT
   • repo
   • branch

Behavior summary

• On boot (after WiFi connects), the device calls the GitHub Contents API for the repo root.
• For each *.epub and sleep.bmp found:
  • Compare GitHub blob SHA to cached SHA stored in /.crosspoint/github_sha/ on the SD card
  • Download only when SHA differs or is missing locally
• Download destinations:
  • sleep.bmp → /sleep.bmp
  • *.epub → /<filename>.epub (SD card root)
• No automatic deletions are performed.

RAM note

The GitHub Contents API directory listing is small (one JSON object per file). Downloads are streamed directly to SD using a small buffer.