Technical Details

---

Technical-Details

Technical Details

This page explains the technical aspects of how the GitHub IoT Arduino Module works.

GitHub API Interaction

API Workflow

The library interacts with GitHub's REST API through the following workflow:

1. Authentication: Each request includes a GitHub Personal Access Token
2. GET Request: Retrieves file metadata, including the SHA hash
3. Content Processing: Prepares and encodes new content
4. PUT Request: Updates the file with new content and the current SHA
5. Response Handling: Processes the API response, including the new SHA

GitHub Content API Endpoints

The library uses GitHub's Contents API endpoints:

• GET /repos/:owner/:repo/contents/:path - Get file contents
• PUT /repos/:owner/:repo/contents/:path - Update file contents

Base64 Encoding

GitHub requires file contents to be Base64 encoded in API requests. The encoding process follows mathematical principles:

$$ \text{Base64}(M) = \text{concat}(B_1, B_2, \ldots, B_n) $$

Where each block $B_i$ is computed from 3 octets of the input message $M$:

$$ B_i = \text{enc}(M_{3i-2}, M_{3i-1}, M_{3i}) $$

For the last block, if the input length is not a multiple of 3, padding is applied:

$$ \text{padding} = \begin{cases} \text{''} & \text{if } |M| \equiv 0 \pmod{3} \\ \text{'='} & \text{if } |M| \equiv 2 \pmod{3} \\ \text{'=='} & \text{if } |M| \equiv 1 \pmod{3} \end{cases} $$

HTTP Headers and Status Codes

The library uses the following HTTP headers for API requests:

For GET requests:

Authorization: Bearer {token}

For PUT requests:

Authorization: Bearer {token}
Content-Type: application/json

The library handles various HTTP status codes:

Status Code	Description	Library Action
200 (OK)	Request successful	Process response
401 (Unauthorized)	Invalid token	Return error
404 (Not Found)	File or repo not found	Return error
409 (Conflict)	SHA mismatch	Return error
422 (Unprocessable Entity)	Validation failed	Return error

JSON Structure

The library uses ArduinoJson to handle JSON data. The JSON document structure is determined by the user, but the library handles the GitHub API-specific JSON structures.

Example GitHub API PUT payload:

{
  "message": "Update data",
  "content": "eyJzZW5zb3IiOiJ0ZW1wZXJhdHVyZSIsInZhbHVlIjoyMy41fQ==",
  "sha": "f5f369a7a67a6c2c59daa9e10f65c22c17d9c643"
}

Where:

• message: Commit message
• content: Base64-encoded JSON data
• sha: Current file SHA hash

Memory Considerations

The memory required for a JSON document can be estimated with:

$$ \text{requiredSize} \approx \text{jsonLength} \times 1.1 + 10 $$

For ESP8266 devices, the maximum document size is more constrained than on ESP32 devices.

For more information on performance optimization, see the Performance Optimization page.

---