Skip to content

Firmware Rollback

Overview

The SMARTA L v2 device incorporates a firmware rollback mechanism as a fail-safe feature. If a newly updated firmware version encounters critical issues or does not perform as expected, the rollback capability allows the device to revert to the previously installed and presumably stable firmware version. This is primarily managed by the OTAHandler library used for HTTP Over-the-Air (OTA) updates.

Purpose of Rollback

  • Stability: Ensures that the device can recover from a problematic firmware update without requiring manual intervention or physical access.
  • Reliability: Increases the overall reliability of the remote update process by providing a path to a known good state.
  • Reduced Downtime: Minimizes device downtime if a new firmware introduces bugs.

How Rollback Works

The rollback functionality relies on the ESP-IDF's partition scheme, which typically includes at least two "app" partitions (e.g., ota_0, ota_1) and an "otadata" partition.

  1. OTA Update Process: When a new firmware is downloaded (e.g., via HTTP OTA), it is written to the inactive app partition. The otadata partition is then updated to mark this newly flashed partition as the one to boot from next.
  2. Previous Version: The previously running firmware remains in the other app partition.
  3. Initiating Rollback: When a rollback is triggered:
    • The otaHandler.performRollback() function is called.
    • This function instructs the bootloader (by modifying the otadata partition) to boot from the app partition that contains the previous firmware version on the next reboot.
  4. Reboot: The device reboots.
  5. Booting Previous Version: The bootloader reads the otadata partition and boots the firmware from the now-active (previous) app partition.

Initiating a Firmware Rollback

A firmware rollback can be initiated through the following method:

Button Interface

  • Navigation: Enter the settings menu by a very long press of the physical button.
  • Selection: Navigate through the menu options using short presses until "Rollback" (or "ROLLBACK FW") is displayed on the OLED screen.
  • Confirmation: Perform a long press on the "Rollback" option to select it.
  • Process:
    • The device will display "ROLLBACK" on the OLED screen.
    • The settingsTask() in SMARTA_L_v2.ino (around case 8) handles this selection.
    • It will publish status messages via MQTT if connected (e.g., publishWifiMqttMessage("status", "ROLLBACK")).
    • Crucially, it calls the handleRollback() function.
  • Feedback & Action (within handleRollback() in main.ino):
    • The OLED displays: printStatusToOLED("Performing rollback...").
    • The core rollback action is attempted: otaHandler.performRollback().
    • If successful:
      • otaHandler.performRollback() returns true.
      • The OLED displays: printStatusToOLED("Rollback successful. Rebooting...").
      • The device will then typically reboot (often as part of performRollback or immediately after) to load the previous firmware.
    • If failed:
      • otaHandler.performRollback() returns false.
      • The OLED displays: printStatusToOLED("Rollback failed.").
      • This might occur if there's no valid previous firmware to roll back to, or an issue with the partition table/otadata.

Other Potential Methods (Not Explicitly Detailed for Rollback)

  • MQTT Command: While not explicitly shown for rollback, a system command via MQTT could be implemented to call handleRollback() remotely.
  • Automatic Rollback: Some OTA systems can be configured to automatically roll back if a new firmware fails to boot correctly multiple times or fails a health check. The current implementation seems to rely on manual initiation.

Important Considerations

  • Two-Stage OTA: Rollback is most effective when the OTA process uses a two-stage approach (having at least two app partitions).
  • otadata Integrity: The otadata partition is critical for managing which firmware version boots. Corruption here can affect OTA and rollback capabilities.
  • No Rollback for MQTT Pushed Updates: The Update.h library, typically used for MQTT OTA data handling (as seen in MQTT.ino), directly writes to the current OTA partition. It does not inherently manage multiple app partitions or an otadata partition in the same way OTAHandler does for HTTP OTA. Therefore, a direct rollback of an MQTT-pushed update using otaHandler.performRollback() might not be possible unless the MQTT OTA process was also designed to use the ota_0/ota_1 scheme and update otadata correctly. The primary documented rollback mechanism is tied to the HTTP OTA process managed by OTAHandler.

Code References

  • Initiation via Button Menu: settingsTask() in SMARTA_L_v2.ino (handles navigation to "Rollback" and calls handleRollback).
  • Core Rollback Logic: handleRollback() in main.ino (calls otaHandler.performRollback() and provides OLED feedback).
  • OTA Handler Library: The OTAHandler object (initialized in SMARTA_L_v2.ino and used in main.ino) provides the performRollback() method.
  • Changelog: CHANGELOG.md mentions the addition of the Rollback function in version 1.10.6.

This rollback feature provides an essential safety net for the remote firmware update process, enhancing the device's resilience in the field.