Merge pull request #1517 from advancedtelematic/docs/prep-2020.1

Changelog: update with recent PRs.

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

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

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]

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

docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc

@@ -13,12 +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 just need to do four things to get started:
+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 <<Adding support for your board>> 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.
-4.  {app-url}/#/profile/access-keys[Create a provisioning key, window="_blank"] and add it to your local.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 <<Adding support for your board>> 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`.
 
 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`).
 

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"]

docs/ota-client-guide/modules/ROOT/pages/virtual-secondaries.adoc

@@ -0,0 +1,44 @@
+= 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 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.
+
+
+
+== 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.
+. 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.
+
+
+== Updating via Virtual Secondaries
+
+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.
+. 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.
+
+
+
+== Integrating Virtual Secondaries into Yocto
+
+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.
+