127 lines
4.1 KiB
Markdown
127 lines
4.1 KiB
Markdown
# xteink-github-sync
|
||
|
||
Sync `.epub` files (and an optional `sleep.bmp`) from a GitHub repository to your CrossPoint/xteink device at boot.
|
||
|
||
This repo contains:
|
||
1. The device-side C++ implementation (`GitHubSync.*`, `GitHubSyncSettingsActivity.*`)
|
||
2. A Python patcher (`patch.py`) that injects the feature into your CrossPoint Reader codebase and uploads the firmware (with a prompt to connect via USB first).
|
||
|
||
## What it syncs
|
||
|
||
- All files in the root of your GitHub repo ending in `.epub`
|
||
- `sleep.bmp` in the repo root (optional)
|
||
|
||
The device compares GitHub blob SHAs against cached SHAs stored on the SD card and downloads only what changed.
|
||
|
||
## GitHub repo setup
|
||
|
||
1. Create a **private** GitHub repo (example: `xteink`)
|
||
2. Add `.epub` files to the **root** of the repo
|
||
3. Optionally add `sleep.bmp` (152x152 grayscale BMP)
|
||
4. Create a Personal Access Token (PAT):
|
||
- Token type: classic or a fine-grained token with equivalent access
|
||
- Scopes/permissions: `contents: read-only` (or equivalent for reading repository contents)
|
||
5. In the device UI (or during initial setup), configure:
|
||
- GitHub username
|
||
- PAT
|
||
- Repo name
|
||
- Branch (default: `main`)
|
||
|
||
## How the sync works (device behavior)
|
||
|
||
- After WiFi connects, the firmware calls the GitHub Contents API
|
||
- For each candidate file in the repo root (`*.epub` and `sleep.bmp`), it:
|
||
- Fetches the GitHub blob SHA
|
||
- Compares it to the cached SHA stored at `/.crosspoint/github_sha/` on the SD card
|
||
- Downloads the raw file if the SHA differs or is missing locally
|
||
- Download destinations on the SD card:
|
||
- `/sleep.bmp` for the sleep image
|
||
- `/<filename>.epub` for book files
|
||
- Files are **not** deleted automatically
|
||
|
||
## Requirements (local machine)
|
||
|
||
- `git`
|
||
- `platformio` (PlatformIO CLI, provides `pio`)
|
||
- `esptool.py` (used by PlatformIO for uploading)
|
||
- `esp-idf-nvs-partition-gen` (used to build an NVS partition for flashing credentials)
|
||
- Python packages the script may prompt to install (press `Enter` when asked):
|
||
- `platformio`
|
||
- `esptool`
|
||
- `esp-idf-nvs-partition-gen`
|
||
- `certifi` (recommended on macOS to avoid `CERTIFICATE_VERIFY_FAILED`)
|
||
|
||
## Usage
|
||
|
||
Run the patcher:
|
||
|
||
```bash
|
||
python3 patch.py
|
||
```
|
||
|
||
Optional arguments:
|
||
|
||
```bash
|
||
python3 patch.py /path/to/destination [usb_upload_port]
|
||
```
|
||
|
||
What it does:
|
||
|
||
1. Clones/updates `crosspoint-reader` into `destination/crosspoint-reader`
|
||
2. Copies the C++ files into the correct CrossPoint locations
|
||
3. Injects the startup sync call into the CrossPoint boot path
|
||
4. Adds a “GitHub Sync” entry to the settings menu
|
||
5. Optionally writes NVS credentials (username/PAT/repo/branch) into the device
|
||
6. Prompts you to connect the device via USB before uploading
|
||
7. Runs `pio run --target upload`
|
||
|
||
## Prompts and validation
|
||
|
||
During setup, `patch.py` will prompt for:
|
||
|
||
- GitHub username
|
||
- Validates reachability via `GET https://api.github.com/users/{username}`
|
||
- PAT
|
||
- Validates via `GET https://api.github.com/user`
|
||
- Repo name
|
||
- Validates via `GET https://api.github.com/repos/{owner}/{repo}` using your PAT
|
||
|
||
Before uploading firmware, it prompts you to:
|
||
- Connect the xteink device via **USB data** (not charge-only)
|
||
- Press `Enter` once connected
|
||
- It then shows likely serial ports and PlatformIO’s device list to help you choose the correct upload port.
|
||
|
||
## Troubleshooting
|
||
|
||
### `CERTIFICATE_VERIFY_FAILED` talking to GitHub
|
||
|
||
On macOS, Python can miss the system CA bundle. Recommended fix:
|
||
|
||
```bash
|
||
pip3 install certifi
|
||
```
|
||
|
||
The script uses `certifi` automatically when available.
|
||
|
||
If you *must* bypass SSL verification (insecure), you can run:
|
||
|
||
```bash
|
||
export GITHUB_SYNC_SSL_NO_VERIFY=1
|
||
python3 patch.py
|
||
```
|
||
|
||
### Upload picks the wrong serial device (e.g. Bluetooth)
|
||
|
||
Make sure you use a **data** USB cable and that the device is connected.
|
||
|
||
Use the prompt (or pass the upload port explicitly) so PlatformIO/esptool doesn’t auto-detect a non-ESP32 serial device.
|
||
|
||
If you still have trouble, try:
|
||
- Unplugging Bluetooth devices temporarily
|
||
- Passing `usb_upload_port` explicitly to `patch.py`
|
||
|
||
## Integration details
|
||
|
||
See `INTEGRATION.md` for the file injection locations and the CrossPoint-side integration checklist.
|
||
|