..
 # SPDX-FileCopyrightText: Copyright (c) 2025, Linaro Limited.
 #
 # SPDX-License-Identifier: MIT

.. _mender_capsule_update_label:

*********************
Mender Capsule Update
*********************

.. _mender_capsule_update_note:
.. note::
  Before executing mender capsule updates, ensure that the
  firmware is capable of handling UEFI capsules.

  Additionally, ``BootOrder`` needs to be set once to prioritize
  booting from EFI/UpdateCapsule before any updates.

  For example, via these steps in U-Boot shell:

  .. code-block:: console

    # Add a new boot option: Boot1001 that boots from
    # EFI/UpdateCapsule
    # mmc <device-index>:<partition> should be the ESP partition
    # where EFI/UpdateCapsule is located
    efidebug boot add -b 1001 cap mmc <device-index>:<partition> EFI/UpdateCapsule

    # Prepend the new boot option to the current order
    # <existing_boot_options> can be checked via
    # `efidebug boot order` command without any arguments.
    efidebug boot order 1001 <existing_boot_options>

Once the Mender server is running and the Device Under Test
(DUT) is provisioned, the next step is to deliver your update
payloads to the server for performing capsule update on DUT

Requirements:

  * :ref:`Mender artifact <build_with_mender_support_label>`
  * :ref:`Artifacts are uploaded <artifact_upload_label>`
  * :ref:`Running Mender server <setup_mender_server_label>`
  * :ref:`Device Under Test (DUT) is provisioned <dut_provisioning_label>`
  * :ref:`Copy artifact key on DUT <copy_artifact_key_label>`

This section covers only the compatible capsule scenario.

* **Update module**

  The uefi-capsule update module is part of Cassini image by default.

* **Deploying Updates** :

  To trigger an **compatible rollback capsule update**, 
  we deploy a compatible-rollback-capsule-update.

  .. code-block:: console

    create_artifact_deployment "compatible-rollback-capsule-update"

  Expected outcome:

    * The mender capsule passes signature validation.
    * The DUT downloads the artifact by checking the compatibility.
    * The update module will install the capsule to
      ``/boot/efi/EFI/UpdateCapsule`` directory.
    * The DUT will be rebooted automatically.
    * The firmware will handle capsule update automatically
      after :ref:`this modification <mender_capsule_update_note>`.
    * The firmware detects that the capsule is tampered and rejects the update.
    * After booting into Linux, the update module will verify
      new ESRT table against the received capsule information.
    * But ESRT entries do not match the expected versions,
      causing the update to fail.
    * Mender triggers an automatic rollback and
      the DUT will be rebooted automatically.
    * On the next boot, the update module runs rollback verification by
      comparing current ESRT entries with the previous versions.
    * Upon success, these logs will be visible in ``journalctl -u mender-updated``:

      .. code-block:: console

        Rollback succeeded for <guid>
        Rollback succeeded for all firmware entries

  To trigger an **compatible capsule update**, we deploy a compatible-capsule-update.

  .. code-block:: console

    create_artifact_deployment "compatible-capsule-update"

  Expected outcome:

    * The mender capsule passes signature validation.
    * The DUT downloads the artifact by checking the compatibility.
    * The update module will install the capsule to
      ``/boot/efi/EFI/UpdateCapsule`` directory.
    * The DUT will be rebooted automatically.
    * The firmware will handle capsule update automatically
      after :ref:`this modification <mender_capsule_update_note>`.
    * After booting into Linux, the update module will verify
      new ESRT table against the received capsule information.
    * Upon success, these logs will be visible in ``journalctl -u mender-updated``:

      .. code-block:: console

        Update succeeded for <guid>
        Update succeeded for all capsule payloads