From 167ca67eaa86e9c371ac31db52ec2d902c1dffa0 Mon Sep 17 00:00:00 2001 From: amma Date: Tue, 17 Dec 2019 11:31:49 +0100 Subject: [PATCH 1/8] Virtual Secondaries page added Signed-off-by: amma --- docs/ota-client-guide/modules/ROOT/nav.adoc | 1 + .../ROOT/pages/virtual-secondaries.adoc | 55 +++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc diff --git a/docs/ota-client-guide/modules/ROOT/nav.adoc b/docs/ota-client-guide/modules/ROOT/nav.adoc index d00ec8940f..2dcc67d6e6 100644 --- a/docs/ota-client-guide/modules/ROOT/nav.adoc +++ b/docs/ota-client-guide/modules/ROOT/nav.adoc @@ -78,6 +78,7 @@ ifndef::env-github[:pageroot:] * xref:{pageroot}build-only-ostree.adoc[Build only the OSTree part] * xref:{pageroot}rollback.adoc[Set up rollback behavior] * xref:{pageroot}deb-package-install.adoc[Install the client from a deb package] +* xref:{pageroot}virtual-secondaries.adoc[Use Virtual Secondaries] .Reference // MC: Do in second iteration: * xref:{pageroot}otaconnect-identifiers.adoc[Identifiers] diff --git a/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc b/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc new file mode 100644 index 0000000000..250f1a98f5 --- /dev/null +++ b/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc @@ -0,0 +1,55 @@ += Use of Virtual Secondaries +ifdef::env-github[] + +[NOTE] +==== +We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname}.html[view this article in our documentation portal]. Not all of our articles render correctly in GitHub. +==== +endif::[] + + +Virtual secondary devices can be used as a way to update a configuration file on the primary device (where the primary device is a standard OSTree image running an aktualizr). You can do this in two parts: + +* First you need a virtual secondary configured that can be used to update a configuration file. +* Afterwards you can integrate it into your Yocto build. + + + +== Creating a Virtual Secondary + +. You can create a virtual secondary to run locally by following the steps on how to xref:simulate-device-basic.adoc[simulate a device without building a disk image]. ++ +You can use the provided `.deb` releases mentioned and the `virtualsec.json` file, which you can edit to suit your needs: such as removing one of the two entries and setting the paths and names to whatever you prefer. +. Afterwards, you will be able to download the arbitrary files to the location specified in the "firmware_path" variable, by uploading the files to the https://connect.ota.here.com[OTA Connect Portal]. +. Now go to the *Software versions* tab and click *Add Software*. You should make sure the *ECU Types* field matches the value specified in the "ecu_hardware_id" variable of the `virtualsec.json` file. ++ +NOTE: "ecu_hardware_id" must be unique per each file type that you'll like to deliver, otherwise an update of one of them will rewrite the others. + + +== Updating via Virtual Secondaries + +To issue the update perform the following steps: + +. Go to your *Devices* tab and find your primary device. (You can run 'aktualizr-info' locally to get the device name if you don't know it.) +. Afterwards, select your virtual secondary and the file you uploaded to the *Software versions* tab. ++ +(For future reference, you can use the *Campaigns* tab to send updates to multiple devices simultaneously.) + + + +== Integrating Virtual Secondaries into Yocto + +You can use the files in the repository https://github.com/advancedtelematic/meta-updater/pull/611[here] as an example to get the virtual secondaries to work in Yocto. You can use the files directly or you can copy them to one of your layers and modify them according to your needs. + +To use the example in the repository, you'll need to make sure that the relevant packages are added to your image. You can do so by adding this to your `local.conf`: +---- +IMAGE_INSTALL_append += " aktualizr-virtualsec" +---- + +Currently, if you want to do this on any branch besides master, you'll need to also add the following to your `local.conf` to pull the latest version of aktualizr into your build: + +---- +require classes/sota_bleeding.inc +---- + + From 4b0d0c5b0ed1358826c06627dcc44050df35f8ff Mon Sep 17 00:00:00 2001 From: amma Date: Wed, 18 Dec 2019 16:58:12 +0100 Subject: [PATCH 2/8] Updates for virtual-secondaries.adoc Signed-off-by: amma --- .../ROOT/pages/virtual-secondaries.adoc | 26 ++++++------------- 1 file changed, 8 insertions(+), 18 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc b/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc index 250f1a98f5..82b473bccc 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc @@ -8,7 +8,7 @@ We recommend that you link:https://docs.ota.here.com/ota-client/latest/{docname} endif::[] -Virtual secondary devices can be used as a way to update a configuration file on the primary device (where the primary device is a standard OSTree image running an aktualizr). You can do this in two parts: +Virtual secondaries can be used as a way to update a configuration file on the primary (where the primary is a standard OSTree image running an aktualizr). You can do this in two parts: * First you need a virtual secondary configured that can be used to update a configuration file. * Afterwards you can integrate it into your Yocto build. @@ -20,36 +20,26 @@ Virtual secondary devices can be used as a way to update a configuration file on . You can create a virtual secondary to run locally by following the steps on how to xref:simulate-device-basic.adoc[simulate a device without building a disk image]. + You can use the provided `.deb` releases mentioned and the `virtualsec.json` file, which you can edit to suit your needs: such as removing one of the two entries and setting the paths and names to whatever you prefer. -. Afterwards, you will be able to download the arbitrary files to the location specified in the "firmware_path" variable, by uploading the files to the https://connect.ota.here.com[OTA Connect Portal]. -. Now go to the *Software versions* tab and click *Add Software*. You should make sure the *ECU Types* field matches the value specified in the "ecu_hardware_id" variable of the `virtualsec.json` file. +. Afterwards, you will be able to download the arbitrary files to the location specified in the `firmware_path` variable. +. Upload the files for the virtual secondary to the https://connect.ota.here.com[OTA Connect Portal]. +. Now go to the *Software versions* tab and click *Add Software*. You should make sure the *ECU Types* field matches the value specified in the `ecu_hardware_id` variable of the `virtualsec.json` file. + -NOTE: "ecu_hardware_id" must be unique per each file type that you'll like to deliver, otherwise an update of one of them will rewrite the others. +NOTE: `ecu_hardware_id` must be unique per each file type that you'll like to deliver, otherwise an update of one of them will rewrite the others. == Updating via Virtual Secondaries To issue the update perform the following steps: -. Go to your *Devices* tab and find your primary device. (You can run 'aktualizr-info' locally to get the device name if you don't know it.) +. Go to your *Devices* tab and find your primary. (You can run `aktualizr-info` locally to get the name of the primary if you don't know it.) . Afterwards, select your virtual secondary and the file you uploaded to the *Software versions* tab. + (For future reference, you can use the *Campaigns* tab to send updates to multiple devices simultaneously.) +. After your selection, the primary will begin to download the file. == Integrating Virtual Secondaries into Yocto -You can use the files in the repository https://github.com/advancedtelematic/meta-updater/pull/611[here] as an example to get the virtual secondaries to work in Yocto. You can use the files directly or you can copy them to one of your layers and modify them according to your needs. - -To use the example in the repository, you'll need to make sure that the relevant packages are added to your image. You can do so by adding this to your `local.conf`: ----- -IMAGE_INSTALL_append += " aktualizr-virtualsec" ----- - -Currently, if you want to do this on any branch besides master, you'll need to also add the following to your `local.conf` to pull the latest version of aktualizr into your build: - ----- -require classes/sota_bleeding.inc ----- - +You can use the files in the repository https://github.com/advancedtelematic/meta-updater/blob/master/recipes-sota/config/aktualizr-virtualsec.bb[here] as an example to get the virtual secondaries to work in Yocto. You can use the files directly or you can copy them to one of your layers and modify them according to your needs. From 03eb810f9c1500eb3600c276f0a411b018ae92f7 Mon Sep 17 00:00:00 2001 From: Patrick Vacek Date: Mon, 6 Jan 2020 09:18:47 +0100 Subject: [PATCH 3/8] Update aktualizr dependencies. A few spaces were missing, a package has been upgraded, and a few packages are no longer used. Signed-off-by: Patrick Vacek --- .../modules/ROOT/pages/simulate-device-basic.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/simulate-device-basic.adoc b/docs/ota-client-guide/modules/ROOT/pages/simulate-device-basic.adoc index 7c47ff32c9..119370cc5b 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/simulate-device-basic.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/simulate-device-basic.adoc @@ -91,12 +91,12 @@ Build from source:: Modify as needed for your distro. See https://github.com/advancedtelematic/aktualizr for further instructions [source,sh,subs="attributes"] ---- -sudo apt install asn1c build-essentialclang clang-format-6.0 clang-tidy-6.0 cmake \ -curl doxygen graphviz lcov libarchive-devlibboost-devlibboost-filesystem-dev \ -libboost-log-dev libboost-program-options-dev libboost-serialization-dev \ -libboost-iostreams-dev libcurl4-openssl-dev libdpkg-dev libostree-dev libp11-2 \ -libp11-dev libpthread-stubs0-dev libsodium-devlibsqlite3-devlibssl-devlibsystemd-dev \ -python3-dev python3-openssl python3-venv sqlite3 valgrind +sudo apt install asn1c build-essential clang clang-format-6.0 clang-tidy-6.0 \ +cmake curl doxygen graphviz lcov libarchive-dev libboost-dev \ +libboost-filesystem-dev libboost-log-dev libboost-program-options-dev \ +libcurl4-openssl-dev libostree-dev libp11-3 libp11-dev libpthread-stubs0-dev \ +libsodium-dev libsqlite3-dev libssl-dev python3-dev python3-openssl \ +python3-venv sqlite3 valgrind ---- .Clone the sources from GitHub [source,sh,subs="attributes"] From 568b47bf43338f04ff16bd8e0dd9b3910bac96c9 Mon Sep 17 00:00:00 2001 From: amma Date: Wed, 8 Jan 2020 15:06:36 +0100 Subject: [PATCH 4/8] Minor edits on virtual secondaries Signed-off-by: amma --- .../modules/ROOT/pages/virtual-secondaries.adoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc b/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc index 82b473bccc..d8fed9160b 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc @@ -21,8 +21,7 @@ Virtual secondaries can be used as a way to update a configuration file on the p + You can use the provided `.deb` releases mentioned and the `virtualsec.json` file, which you can edit to suit your needs: such as removing one of the two entries and setting the paths and names to whatever you prefer. . Afterwards, you will be able to download the arbitrary files to the location specified in the `firmware_path` variable. -. Upload the files for the virtual secondary to the https://connect.ota.here.com[OTA Connect Portal]. -. Now go to the *Software versions* tab and click *Add Software*. You should make sure the *ECU Types* field matches the value specified in the `ecu_hardware_id` variable of the `virtualsec.json` file. +. Next, you can upload the files for the virtual secondary. To do so, go to the *Software versions* tab in the https://connect.ota.here.com[OTA Connect Portal] and click *Add Software*. You should make sure the *ECU Types* field matches the value specified in the `ecu_hardware_id` variable of the `virtualsec.json` file. + NOTE: `ecu_hardware_id` must be unique per each file type that you'll like to deliver, otherwise an update of one of them will rewrite the others. @@ -33,9 +32,9 @@ To issue the update perform the following steps: . Go to your *Devices* tab and find your primary. (You can run `aktualizr-info` locally to get the name of the primary if you don't know it.) . Afterwards, select your virtual secondary and the file you uploaded to the *Software versions* tab. -+ -(For future reference, you can use the *Campaigns* tab to send updates to multiple devices simultaneously.) . After your selection, the primary will begin to download the file. ++ +For future reference, you can use the *Campaigns* tab to send updates to multiple devices simultaneously. From 78d27a7378750f0e2abe1b74fec7f7e04bf99dab Mon Sep 17 00:00:00 2001 From: amma Date: Thu, 16 Jan 2020 13:17:49 +0100 Subject: [PATCH 5/8] Edit of third point in integration process Signed-off-by: amma --- .../add-ota-functonality-existing-yocto-project.adoc | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc b/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc index 88609e890b..6927c947ef 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc @@ -13,11 +13,16 @@ endif::[] :page-order: 6 :icons: font -If you already have a Yocto-based project that you want to update using {product-name}, you just need to do four things to get started: +If you already have a Yocto-based project that you want to update using {product-name}, you can perform the four things outlined below. These are the main changes needed to start a functional integration to an existing Yocto project. 1. Clone the https://github.com/advancedtelematic/meta-updater[meta-updater] layer and add it to your https://www.yoctoproject.org/docs/2.6/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf[bblayers.conf]. 2. Clone a 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.6/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 a third-party distro configuration, you can add `INHERIT += " sota"` to it, thus combining the capabilities of your distro with meta-updater features. +3. Set up your https://www.yoctoproject.org/docs/2.6/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 a third-party distro configuration, you can add the following parameters to it, thus combining the capabilities of your distro with meta-updater features. ++ +---- +INHERIT += " sota" +DISTRO_FEATURES_append = " sota systemd usrmerge" +---- 4. {app-url}/#/profile/access-keys[Create a provisioning key, window="_blank"] and add it to your local.conf. 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 push it to OTA Connect. Additionally, a live disk image will be created (normally named `$\{IMAGE_NAME}.wic` e.g. `core-image-minimal-raspberrypi3.wic`). From e8f81977de6da7ed3abcdc16f3501254862ec368 Mon Sep 17 00:00:00 2001 From: amma Date: Thu, 16 Jan 2020 17:17:58 +0100 Subject: [PATCH 6/8] Minor edit of page Add OTA functionality to existing Yocto project Signed-off-by: amma --- .../add-ota-functonality-existing-yocto-project.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc b/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc index 6927c947ef..ac07c920e2 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc @@ -13,17 +13,17 @@ endif::[] :page-order: 6 :icons: font -If you already have a Yocto-based project that you want to update using {product-name}, you can perform the four things outlined below. These are the main changes needed to start a functional integration to an existing Yocto project. +If you already have a Yocto-based project, you can start your functional integration with {product-name} by following these four steps: 1. Clone the https://github.com/advancedtelematic/meta-updater[meta-updater] layer and add it to your https://www.yoctoproject.org/docs/2.6/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf[bblayers.conf]. -2. Clone a 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.6/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 a third-party distro configuration, you can add the following parameters to it, thus combining the capabilities of your distro with meta-updater features. +2. Clone a 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.6/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` or to `poky-sota-systemd`. Alternatively, if you are using your own or a third-party distro configuration, you can add the following parameters to it, thus combining the capabilities of your distro with meta-updater features. + ---- INHERIT += " sota" DISTRO_FEATURES_append = " sota systemd usrmerge" ---- -4. {app-url}/#/profile/access-keys[Create a provisioning key, window="_blank"] and add it to your local.conf. +4. {app-url}/#/profile/access-keys[Create a provisioning key, window="_blank"] and add it to your `local.conf`. 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 push it to OTA Connect. Additionally, a live disk image will be created (normally named `$\{IMAGE_NAME}.wic` e.g. `core-image-minimal-raspberrypi3.wic`). From cc0b12a355699c4f963fdcd79416bee8c9752e03 Mon Sep 17 00:00:00 2001 From: Patrick Vacek Date: Wed, 15 Jan 2020 10:40:32 +0100 Subject: [PATCH 7/8] Changelog: update with recent PRs. Signed-off-by: Patrick Vacek --- CHANGELOG.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ef2bb0669..0ebed56bc6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,18 +2,35 @@ This file summarizes notable changes introduced in aktualizr version. It roughly follows the guidelines from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). -Our versioning scheme is `YEAR.N` where `N` is incremented whenever a new release is deemed necessary. Thus it does not exactly map to months of the year. +Our versioning scheme is `YEAR.N` where `N` is incremented whenever a new release is issued. Thus `N` does not necessarily map to months of the year. ## [??? (unreleased)] + +## [2020.1] - 2020-01-17 + ### Added - Basic file update on IP Secondaries: [PR](https://github.com/advancedtelematic/aktualizr/pull/1518) +### Changed + +- Increased Targets metadata file size limit: [PR](https://github.com/advancedtelematic/aktualizr/pull/1476) +- Check and fetch root metadata according to the Uptane standard: [PR](https://github.com/advancedtelematic/aktualizr/pull/1501) +- Don't fetch Snapshot or Targets metadata if we already have the latest: [PR](https://github.com/advancedtelematic/aktualizr/pull/1503) +- Dynamically link aktualizr and the tests with libaktualizr as shared library: [PR](https://github.com/advancedtelematic/aktualizr/pull/1512) +- Reject all targets if one doesn't match: [PR](https://github.com/advancedtelematic/aktualizr/pull/1510) + ### Fixed +- Do not provision if the Primary times out while connecting to Secondaries: [PR](https://github.com/advancedtelematic/aktualizr/pull/1491) +- Use a bool type instead of a string in the virtual secondary config: [PR](https://github.com/advancedtelematic/aktualizr/pull/1505) +- Correctly read blob data with null terminators from the SQL database: [PR](https://github.com/advancedtelematic/aktualizr/pull/1502) +- Report installation failure if download or target matching fails: [PR](https://github.com/advancedtelematic/aktualizr/pull/1510) +- Disk space is now checked before downloading binary files to ensure sufficient available disk space: [PR](https://github.com/advancedtelematic/aktualizr/pull/1520) - Fixed several issues with OSTree updates on IP Secondaries: [PR](https://github.com/advancedtelematic/aktualizr/pull/1518) + ## [2019.11] - 2019-12-12 ### Added From c471345dfa957393668a34d9ed7419746677ae37 Mon Sep 17 00:00:00 2001 From: Patrick Vacek Date: Fri, 17 Jan 2020 09:03:38 +0100 Subject: [PATCH 8/8] Docs: update with references to 2020.1 release. Signed-off-by: Patrick Vacek --- docs/README.adoc | 1 + .../modules/ROOT/pages/_partials/aktualizr-version.adoc | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/README.adoc b/docs/README.adoc index d27f1c3d5c..ad9b2c005f 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -32,6 +32,7 @@ The link above is for the doxygen docs on master. Doxygen docs for the following * https://advancedtelematic.github.io/aktualizr/2019.9/index.html[2019.9] * https://advancedtelematic.github.io/aktualizr/2019.10/index.html[2019.10] * https://advancedtelematic.github.io/aktualizr/2019.11/index.html[2019.11] +* https://advancedtelematic.github.io/aktualizr/2020.1/index.html[2020.1] ==== == Release process diff --git a/docs/ota-client-guide/modules/ROOT/pages/_partials/aktualizr-version.adoc b/docs/ota-client-guide/modules/ROOT/pages/_partials/aktualizr-version.adoc index 8d0ce93d0d..0b6f79303f 100644 --- a/docs/ota-client-guide/modules/ROOT/pages/_partials/aktualizr-version.adoc +++ b/docs/ota-client-guide/modules/ROOT/pages/_partials/aktualizr-version.adoc @@ -3,4 +3,4 @@ // the version being viewed, but when we are referencing aktualizr from // the other, non-versioned docs, we want to make sure we're using the // latest version. -:aktualizr-version: 2019.11 +:aktualizr-version: 2020.1