= meta-updater Meta-updater is a link:https://www.yoctoproject.org/software-overview/layers/[Yocto layer] that enables over-the-air updates (OTA) with https://github.com/ostreedev/ostree[OSTree] and https://github.com/advancedtelematic/aktualizr[Aktualizr] -- the default client for link:https://www.here.com/products/automotive/ota-technology[HERE OTA Connect]. https://github.com/ostreedev/ostree[OSTree] is a tool for atomic full file system upgrades with rollback capability. OSTree has several advantages over traditional dual-bank systems, but the most important one is that it minimizes network bandwidth and data storage footprint by sharing files with the same contents across file system deployments. https://github.com/advancedtelematic/aktualizr[Aktualizr] (and https://github.com/advancedtelematic/rvi_sota_client[RVI SOTA client]) add authentication and provisioning capabilities to OTA and are integrated with OSTree. You can connect with these open-source applications or sign up for a free account at https://connect.ota.here.com/[HERE OTA Connect] to get started. For the most up-to-date documentation for HERE OTA Connect, meta-updater, and aktualizr, please visit our link:https://docs.ota.here.com/[documentation portal]. == Build === Quickstart If you don't already have a Yocto project that you want to add OTA to, you can use the https://docs.ota.here.com/getstarted/dev/raspberry-pi.html[HERE OTA Connect Quickstart] project to rapidly get up and running on a Raspberry Pi. It takes a standard https://www.yoctoproject.org/tools-resources/projects/poky[poky] distribution, and adds OTA and OSTree capabilities. === Adding meta-updater capabilities to your build If you already have a Yocto-based project and you want to add atomic filesystem updates to it, you just need to do three things: 1. Clone the `meta-updater` layer and add it to your https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf[bblayers.conf]. 2. Clone BSP integration layer (meta-updater-$\{PLATFORM}, e.g. https://github.com/advancedtelematic/meta-updater-raspberrypi[meta-updater-raspberrypi]) and add it to your conf/bblayers.conf. If your board isn't supported yet, you could write a BSP integration for it yourself. See the <> section for the details. 3. Set up your https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#var-DISTRO[distro]. If you are using "poky", the default distro in Yocto, you can change it in your conf/local.conf to "poky-sota". Alternatively, if you are using your own or third party distro configuration, you can add 'INHERIT += " sota"' to it, thus combining capabilities of your distro with meta-updater features. You can then build your image as usual, with bitbake. After building the root file system, bitbake will then create an https://ostree.readthedocs.io/en/latest/manual/adapting-existing/[OSTree-enabled version] of it, commit it to your local OSTree repo and (optionally) push it to a remote server. Additionally, a live disk image will be created (normally named $\{IMAGE_NAME}.-sdimg-ota e.g. core-image-raspberrypi3.rpi-sdimg-ota). You can control this behaviour through <>. === Build with OpenIVI === Build in AGL With AGL you can just add agl-sota feature while configuring your build environment: .... source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl-appfw-smack agl-devel agl-sota .... you can then run .... bitbake agl-demo-platform .... and get as a result an "ostree_repo" folder in your images directory (tmp/deploy/images/$\{MACHINE}/ostree_repo). It will contain * your OSTree repository, with the rootfs committed as an OSTree deployment, * an 'otaimg' bootstrap image, which is an OSTree physical sysroot as a burnable filesystem image, and optionally * some machine-dependent live images (e.g. '_.rpi-sdimg-ota' for Raspberry Pi or '_.porter-sdimg-ota' Renesas Porter board). Although aglsetup.sh hooks provide reasonable defaults for SOTA-related variables, you may want to tune some of them. == Supported boards Currently supported platforms are * https://github.com/advancedtelematic/meta-updater-raspberrypi[Raspberry Pi3] * https://github.com/advancedtelematic/meta-updater-minnowboard[Minnowboard] * https://github.com/advancedtelematic/meta-updater-qemux86-64[Native QEMU emulation] === Adding support for your board If your board isn't supported yet, you can add board integration code yourself. The main purpose of this code is to provide a bootloader that will be able to use https://ostree.readthedocs.io/en/latest/manual/atomic-upgrades/[OSTree's boot directory]. In the meta-updater integration layers we have written so far, the basic steps are: 1. Make the board boot into http://www.denx.de/wiki/U-Boot[U-Boot] 2. Make U-boot import variables from /boot/loader/uEnv.txt and load the kernel with initramfs and kernel command line arguments according to what is set in this file. You may take a look into https://github.com/advancedtelematic/meta-updater-minnowboard[Minnowboard] or https://github.com/advancedtelematic/meta-updater-raspberrypi[Raspberry Pi] integration layers for examples. Although we have used U-Boot so far, other boot loaders can be configured work with OSTree as well. == SOTA-related variables in local.conf * OSTREE_REPO - path to your OSTree repository. Defaults to "$\{DEPLOY_DIR_IMAGE}/ostree_repo" * OSTREE_BRANCHNAME - the branch your rootfs will be committed to. Defaults to "ota" * OSTREE_OSNAME - OS deployment name on your target device. For more information about deployments and osnames see the https://ostree.readthedocs.io/en/latest/manual/deployment/[OSTree documentation]. Defaults to "poky". * OSTREE_INITRAMFS_IMAGE - initramfs/initrd image that is used as a proxy while booting into OSTree deployment. Do not change this setting unless you are sure that your initramfs can serve as such a proxy. * OSTREE_PUSH_CREDENTIALS - when set, your ostree commit will be pushed to a remote repo as a bitbake step. This should be the path to a JSON credentials file in https://github.com/advancedtelematic/sota-tools#credentials[the format accepted by garage-push]. == Usage === OSTree OSTree includes its own simple http server. It just exposes the whole OSTree repository to the network so that any remote device can pull data from it to device's local repository. To use the OSTree http server, you will need OSTree installed on your build machine. (Alternatively, you could run version built inside Yocto using bitbake's http://www.openembedded.org/wiki/Devshell[devshell].) To expose your repo, run ostree trivial-httpd using any free port: .... ostree trivial-httpd tmp/deploy/images/qemux86-64/ostree_repo -P 57556 .... You can then run ostree from inside your device by adding your repo: .... # agl-remote identifies the remote server in your local repo ostree remote add --no-gpg-verify my-remote http://192.168.7.1:57556 ota # ota is a branch name in the remote repo, set in OSTREE_BRANCHNAME ostree pull my-remote ota # poky is OS name as set in OSTREE_OSNAME ostree admin deploy --os=poky my-remote:ota .... After restarting, you will boot into the newly deployed OS image. For example, on the raspberry pi you can try this sequence: .... # add remote ostree remote add --no-gpg-verify agl-snapshot https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/images/raspberrypi3/ostree_repo/ agl-ota # pull ostree pull agl-snapshot agl-ota # deploy ostree admin deploy --os=agl agl-snapshot:agl-ota .... === SOTA tools SOTA tools now contains only one tool, garage-push that lets you push the changes in OSTree repository generated by bitbake process. It communicates with an http server capable of querying files with HEAD requests and uploading them with POST requests. In particular, this can be used with http://www.atsgarage.com/[ATS Garage]. garage-push is used as follws: .... garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=/path/to/credentials.json .... You can set OSTREE_PUSH_CREDENTIALS in your local.conf to make your build results be automatically synchronized with a remote server. Credentials are stored in the JSON format described in the https://github.com/advancedtelematic/sota-tools#credentials[sota-tools README].