Main API¶

esp_ghota.h contains the main API for the library.

API Details¶

Typedefs

typedef struct ghota_config_t ghota_config_t¶: Github OTA Configuration.

typedef struct ghota_client_handle_t ghota_client_handle_t¶

Enums

enum ghota_event_e¶

Github OTA events These events are posted to the event loop to track progress of the OTA process.

Values:

enumerator GHOTA_EVENT_START_CHECK¶: Github OTA check started

enumerator GHOTA_EVENT_UPDATE_AVAILABLE¶: Github OTA update available

enumerator GHOTA_EVENT_NOUPDATE_AVAILABLE¶: Github OTA no update available

enumerator GHOTA_EVENT_START_UPDATE¶: Github OTA update started

enumerator GHOTA_EVENT_FINISH_UPDATE¶: Github OTA update finished

enumerator GHOTA_EVENT_UPDATE_FAILED¶: Github OTA update failed

enumerator GHOTA_EVENT_START_STORAGE_UPDATE¶: Github OTA storage update started. If the storage is mounted, you should unmount it when getting this call

enumerator GHOTA_EVENT_FINISH_STORAGE_UPDATE¶: Github OTA storage update finished. You can mount the new storage after getting this call if needed

enumerator GHOTA_EVENT_STORAGE_UPDATE_FAILED¶: Github OTA storage update failed

enumerator GHOTA_EVENT_FIRMWARE_UPDATE_PROGRESS¶: Github OTA firmware update progress

enumerator GHOTA_EVENT_STORAGE_UPDATE_PROGRESS¶: Github OTA storage update progress

enumerator GHOTA_EVENT_PENDING_REBOOT¶: Github OTA pending reboot

Functions

ESP_EVENT_DECLARE_BASE(GHOTA_EVENTS)¶

ghota_client_handle_t *ghota_init(ghota_config_t *config)¶

Initialize the github ota client.

Parameters: config – [in] Configuration for the github ota client
Returns: ghota_client_handle_t* handle to pass to all subsequent calls. If it returns NULL, there is a error in your config

esp_err_t ghota_set_auth(ghota_client_handle_t *handle, const char *username, const char *password)¶

Set the Username and Password to access private repositories or get more API calls.

Anonymus API calls are limited to 60 per hour. If you want to get more calls, you need to set a username and password. Be aware that this will be stored in the flash and can be read by anyone with access to the flash. The password should be a Github Personal Access Token and for good security you should limit what it can do

Parameters

handle – the handle returned by ghota_init
username – the username to authenticate with
password – this Github Personal Access Token

Returns

esp_err_t ESP_OK if all is good, ESP_FAIL if there is an error

esp_err_t ghota_free(ghota_client_handle_t *handle)¶

Free the ghota client handle and all resources.

Parameters: handle – the Handle
Returns: esp_err_t if there was a error

esp_err_t ghota_check(ghota_client_handle_t *handle)¶

Perform a check for updates.

This will just check if there is a available update on Github releases with download resources that match your configuration for firmware and storage files. If it returns ESP_OK, you can call ghota_get_latest_version to get the version of the latest release

Parameters: handle – the ghota_client_handle_t handle
Returns: esp_err_t ESP_OK if there is a update available, ESP_FAIL if there is no update available or an error

esp_err_t ghota_update(ghota_client_handle_t *handle)¶

Downloads and writes the latest firmware and storage partition (if available)

You should only call this after calling ghota_check and ensuring that there is a update available.

Parameters: handle – the ghota_client_handle_t handle
Returns: esp_err_t ESP_FAIL if there is a error. If the Update is successful, it will not return, but reboot the device

semver_t *ghota_get_current_version(ghota_client_handle_t *handle)¶

Get the currently running version of the firmware.

This will return the version of the firmware currently running on your device. consult semver.h for functions to compare versions

Parameters: handle – the ghota_client_handle_t handle
Returns: semver_t the version of the latest release

semver_t *ghota_get_latest_version(ghota_client_handle_t *handle)¶

Get the version of the latest release on Github. Only valid after calling ghota_check.

Parameters: handle – the ghota_client_handle_t handle
Returns: semver_t* the version of the latest release on Github

esp_err_t ghota_start_update_task(ghota_client_handle_t *handle)¶

Start a new Task that will check for updates and update if available.

This is equivalent to calling ghota_check and ghota_update if there is a new update available. If no update is available, it will not update the device.

Progress can be monitored by registering for the GHOTA_EVENTS events on the Global Event Loop

Parameters: handle – ghota_client_handle_t handle
Returns: esp_err_t ESP_OK if the task was started, ESP_FAIL if there was an error

esp_err_t ghota_start_update_timer(ghota_client_handle_t *handle)¶

Install a Timer to automatically check for new updates and update if available.

Install a timer that will check for new updates every updateInterval seconds and update if available.

Parameters: handle – ghota_client_handle_t handle
Returns: esp_err_t ESP_OK if no error, otherwise ESP_FAIL

char *ghota_get_event_str(ghota_event_e event)¶

convience function to return a string representation of events emited by this library

Parameters: event – the eventid passed to the event handler
Returns: char* a string representing the event

struct ghota_config_t

#include <esp_ghota.h>

Github OTA Configuration.

Public Members

char filenamematch[CONFIG_MAX_FILENAME_LEN]¶: Filename to match against on Github indicating this is a firmware file

char storagenamematch[CONFIG_MAX_FILENAME_LEN]¶: Filename to match against on Github indicating this is a storage file

char storagepartitionname[17]¶: Name of the storage partition to update

char *hostname¶: Hostname of the Github server. Defaults to api.github.com

char *orgname¶: Name of the Github organization

char *reponame¶: Name of the Github repository

uint32_t updateInterval¶: Interval in Minutes to check for updates if using the ghota_start_update_timer function