Update OS and Firmware via OSTree and Capsule Updates¶

The goal of this page is to provide a guide for updating Linux OS using OSTree and the firmware using capsule updates instead of flashing an entirely new image. This allows for over the air updates if the device is on the network.

Update Linux OS using OSTree¶

OSTree is used for version-controlled, atomic updates on Linux operating systems. The OSTree repository includes the kernel, kernel modules, and filesystem files. It does NOT include the devicetree or the devicetree fragments.

Yocto and Generating "ostree_repo"¶

This processes requires the use of Yocto, which our instructions for can be found here. Upon running a Yocto build, the "sota" recipe should already be included by default which creates a "ostree_repo" directory in the output folder (${YOCTO_BUILD_DIR}/build-qcom-wayland/tmp-glibc/deploy/images/qcs6490-mitysom-devkit/ostree_repo) alongside the image. In this directory, OSTree creates a running repository of builds/OS changes. Any changes made to the kernel, kernel modules, and filesystem files will be present in "ostree_repo".

A simple use case would be adding a new package to the filesystem. To achieve this, the package can be added to IMAGE_INSTALL:append in ${YOCTO_BUILD_DIR}/layers/meta-mitysom-qc6490-5430-devkit/recipes-products/images/qcom-multimedia-image.bbappend. Once you have made the desired changes and generated an "ostree_repo" directory via a Yocto build the changes can be applied through the steps below.

IMPORTANT NOTE: The default configuration requires that the meta data for the repository be updated manually (in the folder) each time you build with the following command, ostree -u summary. To avoid having to do this each build, you can force the Yocto bitbake to update it automatically by adding the following to your local.conf file, OSTREE_UPDATE_SUMMARY="1" (recommended).

Updating the SOM with OSTree¶

1. On the SOM, check current deployment with ostree admin status
   • Example Output (* marks deployment SOM has booted with):
     

     root@qcs6490-mitysom-devkit:~# ostree admin status
     * poky 7b2f0a7cb1b3cfb72d0312005e417d7b3bd0fae092c45dda01bd117f1e413989.0
         Version: 1.5-ver.1.1
         origin refspec: poky:qcs6490-mitysom-devkit
     

2. Copy the previously mentioned ostree_repo (located at ${YOCTO_BUILD_DIR}/build-qcom-wayland/tmp-glibc/deploy/images/qcs6490-mitysom-devkit/ostree_repo) onto the SOM (no particular location although using /tmp is recommended). This can be achieved with adb through USB-C or scp with a Wi-Fi module or USB-A to Ethernet adapter
   • From host PC: scp -r <path to ostree_repo> <user>@<IP_address>:/tmp
   • From host PC: adb push <path to ostree_repo> /tmp
3. Pull the copied OSTree repo on the SOM with ostree pull-local /tmp/<ostree_repo> <branch_name>. The branch_name can be determined by running ostree refs (example output: poky:qcs6490-mitysom-devkit, where qcs6490-mitysom-devkit is the branch name)
4. Create the deployment on the SOM with ostree admin deploy <branch_name>
5. Reboot the SOM with reboot
6. Check if the SOM rebooted with the created deployment with ostree admin status
   • Example Output:
     

     root@qcs6490-mitysom-devkit:~# ostree admin status
     * poky 1d8d235b66cec43954e448e1d6df19aac4c721a7b9055b8fa8d5a9ff258b1106.0
         Version: 1.5-ver.1.1
         origin refspec: qcs6490-mitysom-devkit
       poky 7b2f0a7cb1b3cfb72d0312005e417d7b3bd0fae092c45dda01bd117f1e413989.0 (rollback)
         Version: 1.5-ver.1.1
         origin refspec: poky:qcs6490-mitysom-devkit
     

The SOM should now reflect any changes made to the kernel, kernel modules, and filesystem files in the Yocto build.

References¶

• Qualcomm's instructions

Update Firmware via Capsule Updates¶

Capsule updates are a method of updating firmware by packaging the firmware into a binary format and deploying it to the EFI partition. This is handled on reboots by the UEFI, which processes the capsule and actually applies the capsule update to the firmware.

Capsule updates are still currently under investigation but should allow for OTA firmware updates. This page will be updated with any findings and instructions. For the time being, the references below can provide further information.

References¶

• Qualcomm's instructions
• Capsule generation tool