Callbacks

The ElegantOTA library offers three callbacks that allow you to customize the behavior of your OTA update process. These callbacks enable you to execute specific functions at different stages of the update process, giving you control over the update flow. Here are the available callbacks:

1. onStart(void callable(void));
2. onProgress(void callable(size_t current, size_t final));
3. onEnd(void callable(bool success));

ElegantOTA Pro adds a fourth for its Auto:

4. onUpdateAvailable(void callable(const char* version, const char* notes));

Let’s delve into the details of each callback and how to use them effectively.

onStart Callback

The onStart callback is triggered when the OTA update process begins. It’s a convenient way to perform any setup or initialization tasks before the update process starts. You can use this callback to prepare your device for the update, such as saving important data, configuring pins, or setting up any required resources.

Example:

ElegantOTA.onStart([]() {
  Serial.println("OTA update process started.");
  // Add your initialization tasks here.
});

onProgress Callback

The onProgress callback is called periodically during the OTA update to provide information about the progress of the update. It’s useful for tracking the percentage of completion or displaying progress information to the user. This callback passes two parameters: current (the number of bytes transferred so far) and final (the total number of bytes to be transferred).

Note: onProgress callback can be called very frequently while the update is getting downloaded. It’s neccessary to defer any tasks or logging so that core is not overloaded. Please refer to ‘demo’ example where progress is logged after every second.

Example:

ElegantOTA.onProgress([](size_t current, size_t final) {
  Serial.printf("Progress: %u%%\n", (current * 100) / final);
});

onEnd Callback

The onEnd callback is invoked when the OTA update process completes, whether it succeeds or fails. It passes a boolean parameter success indicating the outcome of the update. You can use this callback to perform cleanup tasks or take action based on whether the update was successful or not.

Example:

ElegantOTA.onEnd([](bool success) {
  if (success) {
    Serial.println("OTA update completed successfully.");
    // Add success handling here.
  } else {
    Serial.println("OTA update failed.");
    // Add failure handling here.
  }
});

onUpdateAvailable Callback

This feature is only available in ElegantOTA Pro

The onUpdateAvailable callback is Pro-only and fires when a check against your Auto finds a build newer than the one running. It hands you the version being offered and the release notes from the manifest, and lets you decide whether now is a good moment to install.

Example:

ElegantOTA.onUpdateAvailable([](const char* version, const char* notes) {
  Serial.printf("Version %s is available\n", version);
 
  // Install it whenever suits your product - right away, overnight,
  // or once someone has confirmed on a display.
  ElegantOTA.installUpdate();
});

If you would rather not make the decision at all, ElegantOTA.setAutoInstall(true) installs every newer build as it is found.

Knowing where an update came from

The three main callbacks fire for every update, no matter how it reached the device. In Pro, ElegantOTA.source() tells you which route it took:

ElegantOTA.onStart([]() {
  switch (ElegantOTA.source()) {
    case OTA_SOURCE_UPLOAD:  Serial.println("uploaded from the portal"); break;
    case OTA_SOURCE_DIRECT:  Serial.println("downloaded by the device"); break;
    case OTA_SOURCE_CHANNEL: Serial.println("from the update channel"); break;
  }
});

Auto RebootHardware ID