Skip to content

Over-the-Air (OTA) Updates

Overview

The system supports Over-the-Air (OTA) updates, allowing firmware updates to be applied remotely. This ensures that the device remains up to date with the latest features, security patches, and performance improvements without requiring physical access.

OTA updates can be delivered via two primary mechanisms: 1. HTTP OTA: The device checks a web server for new firmware versions and downloads them directly. This is typically an automatic process. 2. MQTT OTA: Firmware updates can be pushed to the device via MQTT messages. This method allows for more targeted updates and can be initiated from a backend server or a script (like pushOTA.sh).

How HTTP OTA Updates Work (Automatic)

  1. Firmware Deployment:
    • The latest firmware binary (.bin file) is uploaded to a web server.
    • A corresponding version file (e.g., latest.txt containing the version string) is also updated on the server.
  2. Automatic Version Check:
    • After 30 seconds of a stable Wi-Fi connection (and if not currently pumping), the initializeOTA() function (main.ino) is called. This check is performed once per boot cycle (otaChecked flag).
    • The OTAHandler class (likely from an external library, configured in SMARTA_L_v2.ino with WebServer server(80); OTAHandler otaHandler(server);) contacts the baseUrl (defined in config.h) to compare the currentVersion (from config.h) with the version on the server.
  3. Update Process:
    • If a newer version is detected, the OTAHandler downloads and applies the update.
    • The updateCallback function (main.ino) can be used to display progress messages on the OLED screen (e.g., "Checking version...", "Updating...").
    • The device will typically reboot after a successful update.

How MQTT OTA Updates Work (Pushed)

  1. Initiation:
    • An external script or server (e.g., pushOTA.sh) initiates the OTA process by publishing messages to specific MQTT topics.
    • The pushOTA.sh script takes the DEVICE_ID (MAC address) as an argument.
  2. Process:
    • Start: A message is sent to ota/<DEVICE_ID>/start with the total firmware size as the payload.
      • The device, upon receiving this message (handled in wifiCallback or modemCallback in MQTT.ino), prepares for the update using Update.begin(otaTotalSize).
      • Other tasks (BLE, Pump, Connectivity, Settings) are suspended during the MQTT OTA process.
    • Data Transfer: The firmware binary is sent in chunks (e.g., 512 bytes by pushOTA.sh) to the ota/<DEVICE_ID>/data topic.
      • The device writes these chunks using Update.write(payload, length).
      • Progress can be displayed on the OLED ("OTA Progress: X%").
    • Completion/Cancellation:
      • Once all chunks are received (otaReceived >= otaTotalSize), Update.end(true) finalizes the update, and the device reboots.
      • An OTA update can be cancelled by publishing to ota/<DEVICE_ID>/cancel. The device will call Update.abort() and resume normal tasks.
  3. MQTT Broker:
    • The MQTT broker details (server, port, user, password) are defined in config.h and used by pushOTA.sh and the device.

Key Features

Automatic & Pushed Updates

  • The device automatically checks for updates via HTTP on boot (after Wi-Fi connection).
  • Firmware can also be pushed via MQTT for more direct control.

Fail-Safe Mechanism (Rollback)

  • The OTAHandler library used for HTTP OTA includes a rollback feature.
  • The handleRollback() function (main.ino) can be triggered (e.g., via the settings menu accessed by the touch button, as seen in settingsTask in SMARTA_L_v2.ino) to revert to the previously working firmware version if an update fails or causes issues.
  • otaHandler.performRollback() attempts the rollback.
  • The OLED displays "Performing rollback..." and success/failure messages.

Minimal User Interaction

  • HTTP OTA updates are largely automatic.
  • MQTT OTA updates are initiated remotely.

Status Indication

  • The OLED display provides feedback during the OTA process (e.g., "Checking version...", "Updating...", "OTA Progress X%", "Rollback successful").

Best Practices for OTA Updates

  • Ensure the device remains powered on during an update.
  • Maintain a stable internet connection (Wi-Fi for HTTP OTA, Wi-Fi/LTE for MQTT OTA) to avoid disruptions.
  • If the device reboots unexpectedly, allow it to complete any ongoing update or rollback process.
  • The pushOTA.sh script includes a sleep 0.05 between chunks for MQTT OTA to manage flow control.

Code References

  • HTTP OTA:
    • main.ino: initializeOTA(), updateCallback(), handleRollback()
    • SMARTA_L_v2.ino: OTAHandler otaHandler; initialization.
    • config.h: baseUrl, currentVersion.
  • MQTT OTA:
    • MQTT.ino: wifiCallback(), modemCallback(), handling of ota/<DEVICE_ID>/start, ota/<DEVICE_ID>/data, ota/<DEVICE_ID>/cancel topics. Variables otaInProgress, otaTotalSize, otaReceived. Uses the standard <Update.h> library.
    • pushOTA.sh: Script to initiate and send firmware via MQTT.
  • Settings Menu (for Rollback):
    • SMARTA_L_v2.ino: settingsTask() handles button presses to navigate to Rollback option.