summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormerltron <30755179+merltron@users.noreply.github.com>2019-09-03 10:39:55 +0200
committerGitHub <noreply@github.com>2019-09-03 10:39:55 +0200
commitdf3c9b3e3e723530016a3148ed27e42e53a77905 (patch)
tree1918a3c3a7e05b1277411b50d7cc63ae93d855fb
parent7559eca501a2fc37ff60b1a51225c1829b7ee7df (diff)
parent230d0b58f65a9261099f0c75eb166147cd958de0 (diff)
downloadmeta-updater-df3c9b3e3e723530016a3148ed27e42e53a77905.tar.gz
Merge pull request #592 from advancedtelematic/docs/OTA-3594/antora-merge
OTA-3594: adding restructured Antora-friendly content
-rw-r--r--README.adoc323
-rw-r--r--docs/antora.yml5
-rw-r--r--docs/modules/ROOT/nav.adoc17
-rw-r--r--docs/modules/ROOT/pages/build.adoc62
-rw-r--r--docs/modules/ROOT/pages/dev-config.adoc46
-rw-r--r--docs/modules/ROOT/pages/meta-updater-testing.adoc44
-rw-r--r--docs/modules/ROOT/pages/meta-updater-usage.adoc87
-rw-r--r--docs/modules/ROOT/pages/provisioning-methods.adoc22
-rw-r--r--docs/modules/ROOT/pages/sota-variables.adoc44
-rw-r--r--docs/modules/ROOT/pages/supported-boards.adoc47
10 files changed, 407 insertions, 290 deletions
diff --git a/README.adoc b/README.adoc
index bcbcf96..97b9987 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,8 +1,11 @@
1= meta-updater 1= meta-updater
2:toc: macro 2:toc: macro
3:toc-title: 3:toc-title:
4:meta-updater-github-url: https://github.com/advancedtelematic/meta-updater/tree/master/
4 5
5This layer enables over-the-air updates (OTA) with https://github.com/ostreedev/ostree[OSTree] and https://github.com/advancedtelematic/aktualizr[Aktualizr]. 6ifndef::env-github[:meta-updater-github-url:]
7
8Meta-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].
6 9
7https://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. 10https://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.
8 11
@@ -11,299 +14,39 @@ https://github.com/advancedtelematic/aktualizr[Aktualizr] (and https://github.co
11[discrete] 14[discrete]
12== Table of Contents 15== Table of Contents
13 16
14toc::[] 17The following documentation focuses on tasks that involve the meta-updater layer. If you want to get an idea of the overall developer workflow in OTA Connect, see the link:https://docs.ota.here.com/ota-client/dev/index.html[OTA Connect Developer Guide].
15
16== Build
17
18=== Quickstart
19
20If you don't already have a Yocto project that you want to add OTA to, you can use the https://docs.atsgarage.com/quickstarts/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.
21
22=== Dependencies
23
24In addition to the link:https://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html#required-packages-for-the-build-host[standard Yocto dependencies], meta-updater generally requires a few additional dependencies, depending on your use case and target platform. To install these additional packages on Debian/Ubuntu, run this:
25
26....
27sudo apt install cpu-checker default-jre parted
28....
29
30To build for https://github.com/advancedtelematic/meta-updater-minnowboard[Minnowboard] with GRUB, you will also need to install https://github.com/tianocore/tianocore.github.io/wiki/OVMF[TianoCore's ovmf] package on your host system. On Debian/Ubuntu, you can do so with this command:
31
32....
33sudo apt install ovmf
34....
35
36=== Adding meta-updater capabilities to your build
37
38If you already have a Yocto-based project and you want to add atomic filesystem updates to it, you just need to do three things:
39
401. Clone the `meta-updater` layer and add it to your https://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf[bblayers.conf].
412. 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 <<Adding support for your board>> section for the details.
423. Set up your https://www.yoctoproject.org/docs/current/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.
43
44You 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 <<sota-related-variables-in-localconf,variables in your local.conf>>.
45
46=== Build in AGL
47
48With AGL you can just add agl-sota feature while configuring your build environment:
49
50....
51source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl-appfw-smack agl-devel agl-sota
52....
53
54You can then run:
55
56....
57bitbake agl-demo-platform
58....
59
60and get as a result an `ostree_repo` folder in your images directory (`tmp/deploy/images/$\{MACHINE}/ostree_repo`). It will contain:
61
62* your OSTree repository, with the rootfs committed as an OSTree deployment,
63* an `ota-ext4` bootstrap image, which is an OSTree physical sysroot as a burnable filesystem image, and optionally
64* some machine-dependent live images (e.g. `.wic` for Raspberry Pi or `.porter-sdimg-ota` for Renesas Porter board).
65
66Although `aglsetup.sh` hooks provide reasonable defaults for SOTA-related variables, you may want to tune some of them.
67
68=== Build problems
69
70Ubuntu users that encounter an error due to missing `Python.h` should install `libpython2.7-dev` on their host machine.
71
72== Supported boards
73
74Currently supported platforms are:
75
76* https://github.com/advancedtelematic/meta-updater-raspberrypi[Raspberry Pi 2 and 3]
77* https://github.com/advancedtelematic/meta-updater-minnowboard[Intel Minnowboard]
78* https://github.com/advancedtelematic/meta-updater-qemux86-64[Native QEMU emulation]
79* Renesas R-Car H3 and M3
80* https://github.com/advancedtelematic/meta-updater-ti/[TI BeagleBone Black] (rocko only, using TI SDK 05.03)
81* https://github.com/advancedtelematic/meta-updater-ti/[TI AM65x industrial development kit] (rocko only, using TI SDK 05.03)
82
83Additionally, there is community support for https://github.com/ricardosalveti/meta-updater-riscv[RISC-V] boards, in particular the Freedom U540.
84
85We also historically supported the https://github.com/advancedtelematic/meta-updater-porter[Renesas Porter] board.
86
87=== Adding support for your board
88
89If 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:
90
911. Make the board boot into http://www.denx.de/wiki/U-Boot[U-Boot]
922. 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.
93
94You 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.
95
96Although we have focused on U-Boot and GRUB so far, other bootloaders can be configured to work with OSTree as well.
97
98Your images will also need network connectivity to be able to reach an actual OTA backend. Our 'poky-sota' distribution does not mandate or install a default network manager but our supported platforms use the `virtual/network-configuration` recipe, which can be used as a starting example.
99
100== SOTA-related variables in local.conf
101
102* `OSTREE_BRANCHNAME` - OSTree branch name. Defaults to `${SOTA_HARDWARE_ID}`. Particularly useful for grouping similar images.
103* `OSTREE_REPO` - path to your OSTree repository. Defaults to `$\{DEPLOY_DIR_IMAGE}/ostree_repo`
104* `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".
105* `OSTREE_COMMIT_BODY` - Message attached to OSTree commit. Empty by default.
106* `OSTREE_COMMIT_SUBJECT` - Commit subject used by OSTree. Defaults to `Commit-id: ${IMAGE_NAME}`
107* `OSTREE_UPDATE_SUMMARY` - Set this to '1' to update summary of OSTree repository on each commit. '0' by default.
108* `OSTREE_DEPLOY_DEVICETREE` - Set this to '1' to include devicetree(s) to boot
109* `GARAGE_SIGN_AUTOVERSION` - Set this to '1' to automatically fetch the last version of the garage tools installed by the aktualizr-native. Otherwise use the fixed version specified in the recipe.
110* `GARAGE_TARGET_URL` - sets the `--url` parameter of `garage-sign targets add`, which sets a custom URL for the Image repository targets.
111* `GARAGE_TARGET_EXPIRES` - sets the `--expires` parameter of `garage-sign targets sign`. Format is a UTC instant such as '2018-01-01T00:01:00Z'.
112* `GARAGE_TARGET_EXPIRE_AFTER` - sets the `--expire-after` parameter of `garage-sign targets sign`. Format is in years, months, and days (each optional, but in that order), such as '1Y3M5D'.
113* `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.
114* `SOTA_PACKED_CREDENTIALS` - when set, your ostree commit will be pushed to a remote repo as a bitbake step. This should be the path to a zipped credentials file in https://github.com/advancedtelematic/aktualizr/blob/master/docs/credentials.adoc[the format accepted by garage-push].
115* `SOTA_DEPLOY_CREDENTIALS` - when set to '1' (default value), deploys credentials to the built image. Override it in `local.conf` to built a generic image that can be provisioned manually after the build.
116* `SOTA_CLIENT_PROV` - which provisioning method to use. Valid options are `aktualizr-shared-prov`, `aktualizr-device-prov`, and `aktualizr-device-prov-hsm`. For more information on these provisioning methods, see the https://docs.ota.here.com/client-config/client-provisioning-methods.html[OTA Connect documentation]. The default is `aktualizr-shared-prov`. This can also be set to an empty string to avoid using a provisioning recipe.
117* `SOTA_CLIENT_FEATURES` - extensions to aktualizr. The only valid options are `hsm` (to build with HSM support) and `secondary-network` (to set up a simulated 'in-vehicle' network with support for a primary node with a DHCP server and a secondary node with a DHCP client).
118* `SOTA_SECONDARY_CONFIG` - a file containing JSON configuration for secondaries. It will be installed into `/etc/sota/ecus` on the device and automatically provided to aktualizr. See link:https://github.com/advancedtelematic/aktualizr/blob/master/docs/posix-secondaries-bitbaking.adoc[here] for more details.
119* `SOTA_HARDWARE_ID` - a custom hardware ID that will be written to the aktualizr config. Defaults to MACHINE if not set.
120* `SOTA_MAIN_DTB` - base device tree to use with the kernel. Used together with FIT images. You can change it, and the device tree will also be changed after the update.
121* `SOTA_DT_OVERLAYS` - whitespace-separated list of used device tree overlays for FIT image. This list is OSTree-updateable as well.
122* `SOTA_EXTRA_CONF_FRAGS` - extra https://lxr.missinglinkelectronics.com/uboot/doc/uImage.FIT/overlay-fdt-boot.txt[configuration fragments] for FIT image.
123* `RESOURCE_xxx_pn-aktualizr` - controls maximum resource usage of the aktualizr service, when `aktualizr-resource-control` is installed on the image. See <<aktualizr service resource control>> for details.
124* `SOTA_POLLING_SEC` - sets polling interval for aktualizr to check for updates if aktualizr-polling-interval is included in the image.
125
126== Usage
127
128=== OSTree
129
130OSTree used to include a simple HTTP server as part of the ostree binary, but this has been removed in more recent versions. However, OSTree repositories are self-contained directories, and can be trivially served over the network using any HTTP server. For example, you could use Python's SimpleHTTPServer:
131
132....
133cd tmp/deploy/images/qemux86-64/ostree_repo
134python -m SimpleHTTPServer <port> # port defaults to 8000
135....
136
137You can then run ostree from inside your device by adding your repo:
138
139....
140# This behaves like adding a Git remote; you can name it anything
141ostree remote add --no-gpg-verify my-remote http://<your-ip>:<port>
142
143# If OSTREE_BRANCHNAME is set in local.conf, that will be the name of the
144# branch. If not set, it defaults to the value of MACHINE (e.g. qemux86-64).
145ostree pull my-remote <branch>
146
147# poky is the OS name as set in OSTREE_OSNAME
148ostree admin deploy --os=poky my-remote:<branch>
149....
150
151After restarting, you will boot into the newly deployed OS image.
152
153For example, on the raspberry pi you can try this sequence:
154
155....
156# add remote
157ostree remote add --no-gpg-verify agl-snapshot https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/images/raspberrypi3/ostree_repo/ agl-ota
158
159# pull
160ostree pull agl-snapshot agl-ota
161
162# deploy
163ostree admin deploy --os=agl agl-snapshot:agl-ota
164....
165
166=== garage-push
167
168The https://github.com/advancedtelematic/aktualizr[aktualizr repo] contains a tool, garage-push, which 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 https://connect.ota.here.com/[HERE OTA Connect]. garage-push is used as follows:
169
170....
171garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=/path/to/credentials.zip
172....
173
174You can set `SOTA_PACKED_CREDENTIALS` in your `local.conf` to automatically synchronize your build results with a remote server. Credentials are stored in an archive as described in the https://github.com/advancedtelematic/aktualizr/blob/master/docs/credentials.adoc[aktualizr documentation].
175
176=== aktualizr configuration
177
178https://github.com/advancedtelematic/aktualizr[Aktualizr] supports a variety of https://github.com/advancedtelematic/aktualizr/blob/master/docs/configuration.adoc[configuration options via a configuration file and the command line]. There are two primary ways to control aktualizr's configuration from meta-updater.
179 18
180First, you can set `SOTA_CLIENT_PROV` to control which provisioning recipe is used. Each recipe installs an appropriate `sota.toml` file from aktualizr according to the provisioning needs. See the <<sota-related-variables-in-localconf,SOTA-related variables in local.conf>> section for more information. 19* xref:{meta-updater-github-url}docs/modules/ROOT/pages/build.adoc[Build]
181
182Second, you can write recipes to install additional config files with customized options. A few recipes already exist to address common needs and provide an example:
183
184* link:recipes-sota/config/aktualizr-auto-reboot.bb[aktualizr-auto-reboot.bb] configures aktualizr to automatically reboot after new updates are installed in order to apply the updates immediately. This is only relevant for package managers (such as OSTree) that require a reboot to complete the installation process. If this is not enabled, you will need to reboot the system through other means.
185* link:recipes-sota/config/aktualizr-disable-send-ip.bb[aktualizr-disable-send-ip.bb] disables the reporting of networking information to the server. This is enabled by default and supported by https://connect.ota.here.com/[HERE OTA Connect]. However, if you are using a different server that does not support this feature, you may want to disable it in aktualizr.
186* link:recipes-sota/config/aktualizr-log-debug.bb[aktualizr-log-debug.bb] sets the log level of aktualizr to 0 (trace). The default is 2 (info). This recipe is intended for development and debugging purposes.
187
188To use these recipes, you will need to add them to your image with a line such as `IMAGE_INSTALL_append = " aktualizr-log-debug "` in your `local.conf`.
189
190=== aktualizr service resource control
191
192With systemd based images, it is possible to set resource policies for the aktualizr service. The main use case is to provide a safeguard against resource exhaustion during an unforeseen failure scenario.
193
194To enable it, install `aktualizr-resource-control` on the target image and optionally override the default resource limits set in link:recipes-sota/aktualizr/aktualizr_git.bb[aktualizr_git.bb], from your `local.conf`.
195
196For example:
197
198....
199IMAGE_INSTALL_append += " aktualizr-resource-control "
200RESOURCE_CPU_WEIGHT_pn-aktualizr = "50"
201....
202
203=== garage-sign configuration
204
205The https://github.com/advancedtelematic/ota-tuf/tree/master/cli[garage-sign] tool can be configured with variables described in the <<sota-related-variables-in-localconf,SOTA-related variables in local.conf>> section.
206
207Of particular importance is controlling the expiration of the Targets metadata signed with garage-sign. This is described in detail in the https://docs.ota.here.com/ota-client/dev/metadata-expiry.html[OTA Connect documentation]. To set a manual expiration date, you can use either of the variables `GARAGE_TARGET_EXPIRES` or `GARAGE_TARGET_EXPIRE_AFTER`. Both cannot be supplied simultaneously. If neither are provided, a default of one month will be used.
208
209== Development configuration
210
211=== Logging
212
213To troubleshoot problems that you might encounter during development, we recommend that you enable persistent `systemd` logging. This setting is enabled by default for newly configured environments (see link:conf/local.conf.sample.append[]). To enable it manually, put this to your `local.conf`:
214
215....
216IMAGE_INSTALL_append += " systemd-journald-persistent"
217....
218
219It may also be helpful to run with debug logging enabled in aktualizr. To do so, add this to your `local.conf`:
220
221....
222IMAGE_INSTALL_append += " aktualizr-log-debug"
223....
224
225=== Custom aktualizr versions
226
227You can override the version of aktualizr included in your image. This requires that the version you wish to run is pushed to the https://github.com/advancedtelematic/aktualizr[aktualizr github repo]. You can then use these settings in your `local.conf` to simplify the development process:
228
229[options="header"]
230|======================
231| Option | Effect
232| `require classes/sota_bleeding.inc` | Build the latest head (by default, using the master branch) of Aktualizr
233| `BRANCH_pn-aktualizr = "mybranch"`
234
235`BRANCH_pn-aktualizr-native = "mybranch"` | Build `mybranch` of Aktualizr. Note that both of these need to be set. This is normally used in conjunction with `require classes/sota_bleeding.inc`
236| `SRCREV_pn-aktualizr = "1004efa3f86cef90c012b34620992b5762b741e3"`
237
238`SRCREV_pn-aktualizr-native = "1004efa3f86cef90c012b34620992b5762b741e3"` | Build the specified revision of Aktualizr. Note that both of these need to be set. This can be used in conjunction with `BRANCH_pn-aktualizr` and `BRANCH_pn-aktualizr-native` but will conflict with `require classes/sota_bleeding.inc`
239| `TOOLCHAIN_HOST_TASK_append = " nativesdk-cmake "` | Use with `bitbake -c populate_sdk core-image-minimal` to build an SDK. See the https://github.com/advancedtelematic/aktualizr#developing-against-an-openembedded-system[aktualizr repo] for more information.
240|======================
241
242=== Overriding target version
243*Warning: overriding target version is a dangerous operation, make sure you understand this section completely before doing it.*
244
245Every time you build an image with `SOTA_PACKED_CREDENTIALS` set, a new entry in your Uptane metadata is created and you can see it in the OTA Garage UI if you're using one. Normally this version will be equal to OSTree hash of your root file system. If you want it to be different though you can override is using one of two methods:
246
2471. Set `GARAGE_TARGET_VERSION` variable in your `local.conf`.
2482. Write a recipe or a bbclass to write the desired version to `${STAGING_DATADIR_NATIVE}/target_version`. An example of such bbclass can be found in `classes/target_version_example.bbclass`.
249
250Please note that [target name, target version] pairs are expected to be unique in the system. If you build a new target with the same target version as a previously built one, the old package will be overwritten on the update server. It can have unpredictable effect on devices that have this version installed, and it is not guaranteed that information will be reported correctly for such devices or that you will be able to update them (we're doing our best though). The easiest way to avoid problems is to make sure that your overriding version is as unique as an OSTree commit hash.
251
252== QA with oe-selftest
253
254This layer relies on the test framework oe-selftest for quality assurance. Currently, you will need to run this in a build directory with `MACHINE` set to `qemux86-64`. Follow the steps below to run the tests:
255
2561. Append the line below to `conf/local.conf` to disable the warning about supported operating systems:
257+ 20+
258``` 21Learn how to use this layer to build a basic disk image and add it to your own Yocto project.
259SANITY_TESTED_DISTROS = ""
260```
261
2622. If your image does not already include an ssh daemon such as dropbear or openssh, add this line to `conf/local.conf` as well:
263+ 22+
264``` 23* xref:{meta-updater-github-url}docs/modules/ROOT/pages/supported-boards.adoc[Supported boards]
265IMAGE_INSTALL_append = " dropbear "
266```
267
2683. Some tests require that `SOTA_PACKED_CREDENTIALS` is set in your `conf/local.conf`. See the <<sota-related-variables-in-localconf,SOTA-related variables in local.conf>> section.
269
2704. To be able to build an image for the GRUB tests, you will need to install the ovmf package as described in the <<Dependencies,dependencies>>.
271
2725. Run oe-selftest:
273+ 24+
274``` 25Find out if your board is supported and learn about the minimum hardware requirements.
275oe-selftest -r updater_native updater_qemux86_64 updater_minnowboard updater_raspberrypi updater_qemux86_64_ptest 26+
276``` 27* xref:{meta-updater-github-url}docs/modules/ROOT/pages/sota-variables.adoc[SOTA-related variables in local.conf]
277 28+
278For more information about oe-selftest, including details about how to run individual test modules or classes, please refer to the https://wiki.yoctoproject.org/wiki/Oe-selftest[Yocto Project wiki]. 29Learn how to configure OTA-related functionality when building disk images.
279 30+
280== Aktualizr test suite with ptest 31* xref:{meta-updater-github-url}docs/modules/ROOT/pages/meta-updater-usage.adoc[Usage]
281 32+
282The meta-updater layer includes support for running parts of the aktualizr test suite on deployed devices through link:https://wiki.yoctoproject.org/wiki/Ptest[Yocto's ptest functionality]. Since it adds significant build time cost, it is currently disabled by default. To enable it, add the following to your `conf/local.conf`: 33Learn about the `garage-push` and `garage-sign` utilities, aktualizr configuration and service resource control, and OSTree.
283 34+
284``` 35* xref:{meta-updater-github-url}docs/modules/ROOT/pages/dev-config.adoc[Development configuration]
285PTEST_ENABLED_pn-aktualizr = "1" 36+
286IMAGE_INSTALL_append += " aktualizr-ptest ptest-runner " 37Learn how to configure logging, install custom versions of aktualizr, and override the version indicator for sofware updates.
287``` 38+
288 39* xref:{meta-updater-github-url}docs/modules/ROOT/pages/meta-updater-testing.adoc#_qa_with_oe_selftest[QA with oe-selftest]
289Be aware that it will add several hundreds of MB to the generated file system. 40+
290 41Learn how to use the `oe-selftest` framework for quality assurance.
291The aktualizr tests will now be part of the deployed ptest suite, which can be run by calling `ptest-runner`. Alternatively, the required files and run script can be found in `/usr/lib/aktualizr/ptest`. 42+
292 43* xref:{meta-updater-github-url}docs/modules/ROOT/pages/meta-updater-testing.adoc#_aktualizr_test_suite_with_ptest[Aktualizr test suite with ptest]
293== Manual provisoning 44+
294 45Learn how to enable Yocto's package test functionality and run parts of the aktualizr test suite.
295As described in <<sota-related-variables-in-localconf,SOTA-related variables in local.conf>> section you can set `SOTA_DEPLOY_CREDENTIALS` to `0` to prevent deploying credentials to the built `wic` image. In this case you get a generic image that you can use e.g. on a production line to flash a series of devices. The cost of this approach is that this image is half-baked and should be provisioned before it can connect to the backend. 46+
296 47* xref:{meta-updater-github-url}docs/modules/ROOT/pages/provisioning-methods.adoc[Provisoning methods]
297Provisioning procedure depends on your provisioning recipe, i.e. the value of `SOTA_CLIENT_PROV` (equal to `aktualizr-shared-prov` by default): 48+
298 49Learn how to enable different methods for provisioning devices.
299* For `aktualizr-shared-prov` put your `credentials.zip` to `/var/sota/sota_provisioning_credentials.zip` on the filesystem of a running device. If you have the filesystem of our device mounted to your build machine, prefix all paths with `/ostree/deploy/poky` as in `/ostree/deploy/poky/var/sota/sota_provisioning_credentials.zip`.
300* For `aktualizr-device-prov`
301** put URL to the backend server (together with protocol prefix and port number) at `/var/sota/gateway.url`. If you're using HERE OTA Connect, you can find the URL in the `autoprov.url` file in your credentials archive.
302** put client certificate, private key and root CA certificate (for the *server*, not for the *device*) at `/var/sota/import/client.pem`, `/var/sota/import/pkey.pem` and `/var/sota/import/root.crt` respectively.
303* For `aktualizr-device-prov-hsm`
304** put URL to the server backend (together with protocol prefix and port number) at `/var/sota/gateway.url`. If you're using HERE OTA Connect, you can find the URL in the `autoprov.url` file in your credentials archive.
305** put root CA certificate (for the *server*, not for the *device*) at `/var/sota/import/root.crt`.
306** put client certificate and private key to slots 1 and 2 of the PKCS#11-compatible device.
307 50
308== License 51== License
309 52
diff --git a/docs/antora.yml b/docs/antora.yml
new file mode 100644
index 0000000..5ed1239
--- /dev/null
+++ b/docs/antora.yml
@@ -0,0 +1,5 @@
1name: ota-build
2title: OTA Connect Build Tools
3version: dev
4nav:
5- modules/ROOT/nav.adoc
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
new file mode 100644
index 0000000..d4b577b
--- /dev/null
+++ b/docs/modules/ROOT/nav.adoc
@@ -0,0 +1,17 @@
1// MC: NOTE ABOUT TOC
2// Adding "pageroot" attr so that TOC that will also work directly in GitHub. Because...
3// In Antora the "pages" subdir is implcit added to the xref path at build time.
4// if you add "/pages" Antora will intepret it as "pages/pages".
5// The pages subdir is NOT implicit when viewing source files in Github.
6
7ifdef::env-github[:pageroot: pages/]
8ifndef::env-github[:pageroot:]
9
10.Guide to the Build Tools
11* xref:{pageroot}metaupdater-whatis.adoc[What are the build tools?]
12* xref:{pageroot}build.adoc[Build a disk image]
13* xref:{pageroot}supported-boards.adoc[Supported Boards]
14* xref:{pageroot}meta-updater-usage.adoc[How to]
15* xref:{pageroot}sota-variables.adoc[Configuration reference]
16* xref:{pageroot}dev-config.adoc[Development configuration]
17* xref:{pageroot}meta-updater-testing.adoc[Testing] \ No newline at end of file
diff --git a/docs/modules/ROOT/pages/build.adoc b/docs/modules/ROOT/pages/build.adoc
new file mode 100644
index 0000000..135d468
--- /dev/null
+++ b/docs/modules/ROOT/pages/build.adoc
@@ -0,0 +1,62 @@
1= Build
2:meta-updater-github-url: https://github.com/advancedtelematic/meta-updater/tree/master
3
4== Quickstart
5
6If you don't already have a Yocto project that you want to add OTA to, you can use the xref:dev@getstarted::raspberry-pi.adoc[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.
7
8== Dependencies
9
10//MC: TOMERGE: These "dependencies" mostly just duplicates the prerequisite sections: https://main.gitlab.in.here.com/olp/edge/ota/documentation/ota-connect-docs/blob/master/docs/getstarted/modules/ROOT/pages/raspberry-pi.adoc
11
12In addition to the link:https://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html#required-packages-for-the-build-host[standard Yocto dependencies], meta-updater generally requires a few additional dependencies, depending on your use case and target platform. To install these additional packages on Debian/Ubuntu, run this:
13
14....
15sudo apt install cpu-checker default-jre parted
16....
17
18To build for https://github.com/advancedtelematic/meta-updater-minnowboard[Minnowboard] with GRUB, you will also need to install https://github.com/tianocore/tianocore.github.io/wiki/OVMF[TianoCore's ovmf] package on your host system. On Debian/Ubuntu, you can do so with this command:
19
20....
21sudo apt install ovmf
22....
23
24== Adding meta-updater capabilities to your build
25
26// MC: TOMERGE: This content mosty duplicates https://github.com/advancedtelematic/aktualizr/blob/master/docs/ota-client-guide/modules/ROOT/pages/add-ota-functonality-existing-yocto-project.adoc
27
28If you already have a Yocto-based project and you want to add atomic filesystem updates to it, you just need to do three things:
29
301. Clone the `meta-updater` layer and add it to your https://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf[bblayers.conf].
312. 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 <<Adding support for your board>> section for the details.
323. Set up your https://www.yoctoproject.org/docs/current/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.
33
34You 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 <<sota-related-variables-in-localconf,variables in your local.conf>>.
35
36== Build in AGL
37
38// MC: TOMERGE: This content duplicates https://main.gitlab.in.here.com/olp/edge/ota/documentation/ota-connect-docs/blob/master/docs/getstarted/modules/ROOT/pages/automotive-grade-linux.adoc (except that it is a lot sparser)
39
40With AGL you can just add agl-sota feature while configuring your build environment:
41
42....
43source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl-appfw-smack agl-devel agl-sota
44....
45
46You can then run:
47
48....
49bitbake agl-demo-platform
50....
51
52and get as a result an `ostree_repo` folder in your images directory (`tmp/deploy/images/$\{MACHINE}/ostree_repo`). It will contain:
53
54* your OSTree repository, with the rootfs committed as an OSTree deployment,
55* an `ota-ext4` bootstrap image, which is an OSTree physical sysroot as a burnable filesystem image, and optionally
56* some machine-dependent live images (e.g. `.wic` for Raspberry Pi or `.porter-sdimg-ota` for Renesas Porter board).
57
58Although `aglsetup.sh` hooks provide reasonable defaults for SOTA-related variables, you may want to tune some of them.
59
60== Build problems
61
62Ubuntu users that encounter an error due to missing `Python.h` should install `libpython2.7-dev` on their host machine.
diff --git a/docs/modules/ROOT/pages/dev-config.adoc b/docs/modules/ROOT/pages/dev-config.adoc
new file mode 100644
index 0000000..60002a5
--- /dev/null
+++ b/docs/modules/ROOT/pages/dev-config.adoc
@@ -0,0 +1,46 @@
1= Development configuration
2:meta-updater-github-url: https://github.com/advancedtelematic/meta-updater/tree/master
3
4//MC: The dev guide already has a recommended config topic: https://github.com/advancedtelematic/aktualizr/blob/master/docs/ota-client-guide/modules/ROOT/pages/recommended-clientconfig.adoc
5// This content pretty much serves the same purpose except 'local.conf' instead of 'sota_conf.toml' Clean this up and use an :include: ref reuse in that topic?
6
7== Logging
8
9To troubleshoot problems that you might encounter during development, we recommend that you enable persistent `systemd` logging. This setting is enabled by default for newly configured environments (see link:{meta-updater-github-url}/conf/local.conf.sample.append[]). To enable it manually, put this to your `local.conf`:
10
11....
12IMAGE_INSTALL_append += " systemd-journald-persistent"
13....
14
15It may also be helpful to run with debug logging enabled in aktualizr. To do so, add this to your `local.conf`:
16
17....
18IMAGE_INSTALL_append += " aktualizr-log-debug"
19....
20
21== Custom aktualizr versions
22
23You can override the version of aktualizr included in your image. This requires that the version you wish to run is pushed to the https://github.com/advancedtelematic/aktualizr[aktualizr github repo]. You can then use these settings in your `local.conf` to simplify the development process:
24
25[options="header"]
26|======================
27| Option | Effect
28| `require classes/sota_bleeding.inc` | Build the latest head (by default, using the master branch) of Aktualizr
29| `BRANCH_pn-aktualizr = "mybranch"`
30
31`BRANCH_pn-aktualizr-native = "mybranch"` | Build `mybranch` of Aktualizr. Note that both of these need to be set. This is normally used in conjunction with `require classes/sota_bleeding.inc`
32| `SRCREV_pn-aktualizr = "1004efa3f86cef90c012b34620992b5762b741e3"`
33
34`SRCREV_pn-aktualizr-native = "1004efa3f86cef90c012b34620992b5762b741e3"` | Build the specified revision of Aktualizr. Note that both of these need to be set. This can be used in conjunction with `BRANCH_pn-aktualizr` and `BRANCH_pn-aktualizr-native` but will conflict with `require classes/sota_bleeding.inc`
35| `TOOLCHAIN_HOST_TASK_append = " nativesdk-cmake "` | Use with `bitbake -c populate_sdk core-image-minimal` to build an SDK. See the https://github.com/advancedtelematic/aktualizr#developing-against-an-openembedded-system[aktualizr repo] for more information.
36|======================
37
38== Overriding target version
39*Warning: overriding target version is a dangerous operation, make sure you understand this section completely before doing it.*
40
41Every time you build an image with `SOTA_PACKED_CREDENTIALS` set, a new entry in your Uptane metadata is created and you can see it in the OTA Garage UI if you're using one. Normally this version will be equal to OSTree hash of your root file system. If you want it to be different though you can override is using one of two methods:
42
431. Set `GARAGE_TARGET_VERSION` variable in your `local.conf`.
442. Write a recipe or a bbclass to write the desired version to `${STAGING_DATADIR_NATIVE}/target_version`. An example of such bbclass can be found in `classes/target_version_example.bbclass`.
45
46Please note that [target name, target version] pairs are expected to be unique in the system. If you build a new target with the same target version as a previously built one, the old package will be overwritten on the update server. It can have unpredictable effect on devices that have this version installed, and it is not guaranteed that information will be reported correctly for such devices or that you will be able to update them (we're doing our best though). The easiest way to avoid problems is to make sure that your overriding version is as unique as an OSTree commit hash.
diff --git a/docs/modules/ROOT/pages/meta-updater-testing.adoc b/docs/modules/ROOT/pages/meta-updater-testing.adoc
new file mode 100644
index 0000000..1e20c87
--- /dev/null
+++ b/docs/modules/ROOT/pages/meta-updater-testing.adoc
@@ -0,0 +1,44 @@
1= Testing
2
3//MC: No overlap with any content currently in the developer guide, but probably useful content to clean up and include.
4
5== QA with oe-selftest
6
7This layer relies on the test framework oe-selftest for quality assurance. Currently, you will need to run this in a build directory with `MACHINE` set to `qemux86-64`. Follow the steps below to run the tests:
8
91. Append the line below to `conf/local.conf` to disable the warning about supported operating systems:
10+
11```
12SANITY_TESTED_DISTROS = ""
13```
14
152. If your image does not already include an ssh daemon such as dropbear or openssh, add this line to `conf/local.conf` as well:
16+
17```
18IMAGE_INSTALL_append = " dropbear "
19```
20
213. Some tests require that `SOTA_PACKED_CREDENTIALS` is set in your `conf/local.conf`. See the xref:dev@ota-build::sota-variables.adoc[SOTA-related variables in local.conf].
22
234. To be able to build an image for the GRUB tests, you will need to install the `ovmf` package as described in the xref:dev@ota-build::build.adoc#_dependencies[dependencies section].
24
255. Run oe-selftest:
26+
27```
28oe-selftest -r updater_native updater_qemux86_64 updater_minnowboard updater_raspberrypi updater_qemux86_64_ptest
29```
30
31For more information about oe-selftest, including details about how to run individual test modules or classes, please refer to the https://wiki.yoctoproject.org/wiki/Oe-selftest[Yocto Project wiki].
32
33== Aktualizr test suite with ptest
34
35The meta-updater layer includes support for running parts of the aktualizr test suite on deployed devices through link:https://wiki.yoctoproject.org/wiki/Ptest[Yocto's ptest functionality]. Since it adds significant build time cost, it is currently disabled by default. To enable it, add the following to your `conf/local.conf`:
36
37```
38PTEST_ENABLED_pn-aktualizr = "1"
39IMAGE_INSTALL_append += " aktualizr-ptest ptest-runner "
40```
41
42Be aware that it will add several hundreds of MB to the generated file system.
43
44The aktualizr tests will now be part of the deployed ptest suite, which can be run by calling `ptest-runner`. Alternatively, the required files and run script can be found in `/usr/lib/aktualizr/ptest`.
diff --git a/docs/modules/ROOT/pages/meta-updater-usage.adoc b/docs/modules/ROOT/pages/meta-updater-usage.adoc
new file mode 100644
index 0000000..cc53a9f
--- /dev/null
+++ b/docs/modules/ROOT/pages/meta-updater-usage.adoc
@@ -0,0 +1,87 @@
1= Usage
2:meta-updater-github-url: https://github.com/advancedtelematic/meta-updater/tree/master
3:metadata-expiry-article: xref:dev@ota-client::metadata-expiry.adoc[OTA Connect documentation]
4ifdef::env-github[:metadata-expiry-article: link:https://docs.ota.here.com/ota-client/dev/metadata-expiry.html[OTA Connect documentation]]
5
6//MC: No overlap with any content currently in the developer guide, but probably useful content to clean up and include. eg: use cases.
7
8== OSTree
9
10OSTree used to include a simple HTTP server as part of the ostree binary, but this has been removed in more recent versions. However, OSTree repositories are self-contained directories, and can be trivially served over the network using any HTTP server. For example, you could use Python's SimpleHTTPServer:
11
12....
13cd tmp/deploy/images/qemux86-64/ostree_repo
14python -m SimpleHTTPServer <port> # port defaults to 8000
15....
16
17You can then run ostree from inside your device by adding your repo:
18
19....
20# This behaves like adding a Git remote; you can name it anything
21ostree remote add --no-gpg-verify my-remote http://<your-ip>:<port>
22
23# If OSTREE_BRANCHNAME is set in local.conf, that will be the name of the
24# branch. If not set, it defaults to the value of MACHINE (e.g. qemux86-64).
25ostree pull my-remote <branch>
26
27# poky is the OS name as set in OSTREE_OSNAME
28ostree admin deploy --os=poky my-remote:<branch>
29....
30
31After restarting, you will boot into the newly deployed OS image.
32
33For example, on the raspberry pi you can try this sequence:
34
35....
36# add remote
37ostree remote add --no-gpg-verify agl-snapshot https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/images/raspberrypi3/ostree_repo/ agl-ota
38
39# pull
40ostree pull agl-snapshot agl-ota
41
42# deploy
43ostree admin deploy --os=agl agl-snapshot:agl-ota
44....
45
46== garage-push
47
48The https://github.com/advancedtelematic/aktualizr[aktualizr repo] contains a tool, garage-push, which 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 https://connect.ota.here.com/[HERE OTA Connect]. garage-push is used as follows:
49
50....
51garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=/path/to/credentials.zip
52....
53
54You can set `SOTA_PACKED_CREDENTIALS` in your `local.conf` to automatically synchronize your build results with a remote server. Credentials are stored in an archive as described in the xref:dev@ota-client::provisioning-methods-and-credentialszip.adoc[aktualizr documentation].
55
56== aktualizr configuration
57
58https://github.com/advancedtelematic/aktualizr[Aktualizr] supports a variety of xref:dev@ota-client::aktualizr-config-options.adoc[configuration options via a configuration file and the command line]. There are two primary ways to control aktualizr's configuration from meta-updater.
59
60First, you can set `SOTA_CLIENT_PROV` to control which provisioning recipe is used. Each recipe installs an appropriate `sota.toml` file from aktualizr according to the provisioning needs. See the xref:dev@ota-build::sota-variables.adoc[SOTA-related variables in local.conf] section for more information.
61
62Second, you can write recipes to install additional config files with customized options. A few recipes already exist to address common needs and provide an example:
63
64* link:{meta-updater-github-url}/recipes-sota/config/aktualizr-auto-reboot.bb[aktualizr-auto-reboot.bb] configures aktualizr to automatically reboot after new updates are installed in order to apply the updates immediately. This is only relevant for package managers (such as OSTree) that require a reboot to complete the installation process. If this is not enabled, you will need to reboot the system through other means.
65* link:{meta-updater-github-url}/recipes-sota/config/aktualizr-disable-send-ip.bb[aktualizr-disable-send-ip.bb] disables the reporting of networking information to the server. This is enabled by default and supported by https://connect.ota.here.com/[HERE OTA Connect]. However, if you are using a different server that does not support this feature, you may want to disable it in aktualizr.
66* link:{meta-updater-github-url}/recipes-sota/config/aktualizr-log-debug.bb[aktualizr-log-debug.bb] sets the log level of aktualizr to 0 (trace). The default is 2 (info). This recipe is intended for development and debugging purposes.
67
68To use these recipes, you will need to add them to your image with a line such as `IMAGE_INSTALL_append = " aktualizr-log-debug "` in your `local.conf`.
69
70== aktualizr service resource control
71
72With systemd based images, it is possible to set resource policies for the aktualizr service. The main use case is to provide a safeguard against resource exhaustion during an unforeseen failure scenario.
73
74To enable it, install `aktualizr-resource-control` on the target image and optionally override the default resource limits set in link:{meta-updater-github-url}/recipes-sota/aktualizr/aktualizr_git.bb[aktualizr_git.bb], from your `local.conf`.
75
76For example:
77
78....
79IMAGE_INSTALL_append += " aktualizr-resource-control "
80RESOURCE_CPU_WEIGHT_pn-aktualizr = "50"
81....
82
83=== garage-sign configuration
84
85The https://github.com/advancedtelematic/ota-tuf/tree/master/cli[garage-sign] tool can be configured with variables described in the xref:sota-variables.adoc[SOTA-related variables in local.conf] section.
86
87Of particular importance is controlling the expiration of the Targets metadata signed with garage-sign. This is described in detail in the {metadata-expiry-article}. To set a manual expiration date, you can use either of the variables `GARAGE_TARGET_EXPIRES` or `GARAGE_TARGET_EXPIRE_AFTER`. Both cannot be supplied simultaneously. If neither are provided, a default of one month will be used. \ No newline at end of file
diff --git a/docs/modules/ROOT/pages/provisioning-methods.adoc b/docs/modules/ROOT/pages/provisioning-methods.adoc
new file mode 100644
index 0000000..c376c78
--- /dev/null
+++ b/docs/modules/ROOT/pages/provisioning-methods.adoc
@@ -0,0 +1,22 @@
1= Manual provisoning
2
3//MC: TOMERGE: Looks mostly like a duplicate of this topic: https://github.com/advancedtelematic/aktualizr/blob/master/docs/ota-client-guide/modules/ROOT/pages/simulate-device-cred-provtest.adoc
4
5As described in the xref:xref:dev@ota-build::sota-variables.adoc[configuration reference], you can set `SOTA_DEPLOY_CREDENTIALS` to `0` to prevent deploying credentials to the built `wic` image. In this case you get a generic image that you can use e.g. on a production line to flash a series of devices. The cost of this approach is that this image is half-baked and should be provisioned before it can connect to the backend.
6
7Provisioning procedure depends on your provisioning recipe, i.e. the value of `SOTA_CLIENT_PROV` (equal to `aktualizr-shared-prov` by default):
8
9* For `aktualizr-shared-prov` put your `credentials.zip` to `/var/sota/sota_provisioning_credentials.zip` on the filesystem of a running device. If you have the filesystem of our device mounted to your build machine, prefix all paths with `/ostree/deploy/poky` as in `/ostree/deploy/poky/var/sota/sota_provisioning_credentials.zip`.
10* For `aktualizr-device-prov`
11** put URL to the backend server (together with protocol prefix and port number) at `/var/sota/gateway.url`. If you're using HERE OTA Connect, you can find the URL in the `autoprov.url` file in your credentials archive.
12** put client certificate, private key and root CA certificate (for the *server*, not for the *device*) at `/var/sota/import/client.pem`, `/var/sota/import/pkey.pem` and `/var/sota/import/root.crt` respectively.
13* For `aktualizr-device-prov-hsm`
14** put URL to the server backend (together with protocol prefix and port number) at `/var/sota/gateway.url`. If you're using HERE OTA Connect, you can find the URL in the `autoprov.url` file in your credentials archive.
15** put root CA certificate (for the *server*, not for the *device*) at `/var/sota/import/root.crt`.
16** put client certificate and private key to slots 1 and 2 of the PKCS#11-compatible device.
17
18For more extensive information on provisioning methods, see the following topics from the OTA Connect Developer guide:
19
20//MC: Web links because this topic is only viewable in Github
21* link:https://docs.ota.here.com/ota-client/dev/client-provisioning-methods.html[Device provisioning methods]
22* link:https://docs.ota.here.com/ota-client/dev/enable-device-cred-provisioning.html[Enable device-credential provisioning and install device certificates] \ No newline at end of file
diff --git a/docs/modules/ROOT/pages/sota-variables.adoc b/docs/modules/ROOT/pages/sota-variables.adoc
new file mode 100644
index 0000000..7614a8a
--- /dev/null
+++ b/docs/modules/ROOT/pages/sota-variables.adoc
@@ -0,0 +1,44 @@
1= Build Configuration Options
2:page-partial:
3// MC: Included in aktualizr/docs/ota-client-guide/modules/ROOT/pages/build-configuration.adoc
4
5.OTA-related options for building disk images
6[cols="1,2a",options="header"]
7|====================
8| Option | Description
9| `OSTREE_BRANCHNAME`|OSTree branch name. Defaults to `${SOTA_HARDWARE_ID}`. Particularly useful for grouping similar images.
10| `OSTREE_REPO`|Path to your OSTree repository. Defaults to `$\{DEPLOY_DIR_IMAGE}/ostree_repo`
11| `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".
12| `OSTREE_COMMIT_BODY`|Message attached to OSTree commit. Empty by default.
13| `OSTREE_COMMIT_SUBJECT`|Commit subject used by OSTree. Defaults to `Commit-id: ${IMAGE_NAME}`
14| `OSTREE_UPDATE_SUMMARY`|Set this to '1' to update summary of OSTree repository on each commit. '0' by default.
15| `OSTREE_DEPLOY_DEVICETREE`|Set this to '1' to include devicetree(s) to boot
16| `GARAGE_SIGN_AUTOVERSION`|Set this to '1' to automatically fetch the last version of the garage tools installed by the aktualizr-native. Otherwise use the fixed version specified in the recipe.
17| `GARAGE_TARGET_URL` | Sets the `--url` parameter of `garage-sign targets add`, which sets a custom URL for the Image repository targets.
18| `GARAGE_TARGET_EXPIRES` | Sets the `--expires` parameter of `garage-sign targets sign`. Format is a UTC instant such as '2018-01-01T00:01:00Z'.
19ifndef::env-github[]
20[NOTE]
21====
22Currently, this only works when using the master branch of meta-updater.
23====
24endif::[]
25| `GARAGE_TARGET_EXPIRE_AFTER` | Sets the `--expire-after` parameter of `garage-sign targets sign`. Format is in years, months, and days (each optional, but in that order), such as '1Y3M5D'.
26ifndef::env-github[]
27[NOTE]
28====
29Currently, this only works when using the master branch of meta-updater.
30====
31endif::[]
32| `INITRAMFS_IMAGE`|The 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.
33| `SOTA_PACKED_CREDENTIALS`|When set, your ostree commit will be pushed to a remote repo as a bitbake step. This should be the path to a zipped credentials file in xref:dev@ota-build::provisioning-methods-and-credentialszip.adoc[the format accepted by garage-push].
34| `SOTA_DEPLOY_CREDENTIALS`|When set to '1' (default value), deploys credentials to the built image. Override it in `local.conf` to built a generic image that can be provisioned manually after the build.
35| `SOTA_CLIENT_PROV`|Which provisioning method to use. Valid options are `aktualizr-shared-prov`, `aktualizr-device-prov`, and `aktualizr-device-prov-hsm`. For more information on these provisioning methods, see the xref:dev@ota-client::client-provisioning-methods.adoc[OTA Connect documentation]. The default is `aktualizr-shared-prov`. This can also be set to an empty string to avoid using a provisioning recipe.
36| `SOTA_CLIENT_FEATURES`|Extensions to aktualizr. The only valid options are `hsm` (to build with HSM support) and `secondary-network` (to set up a simulated 'in-vehicle' network with support for a primary node with a DHCP server and a secondary node with a DHCP client).
37| `SOTA_SECONDARY_CONFIG`|A file containing JSON configuration for secondaries. It will be installed into `/etc/sota/ecus` on the device and automatically provided to aktualizr. See xref:dev@ota-client::posix-secondaries-bitbaking.adoc[here] for more details.
38| `SOTA_HARDWARE_ID`|A custom hardware ID that will be written to the aktualizr config. Defaults to MACHINE if not set.
39| `SOTA_MAIN_DTB`|The base device tree to use with the kernel. Used together with FIT images. You can change it, and the device tree will also be changed after the update.
40| `SOTA_DT_OVERLAYS`|A whitespace-separated list of used device tree overlays for FIT image. This list is OSTree-updateable as well.
41| `SOTA_EXTRA_CONF_FRAGS`|Extra https://lxr.missinglinkelectronics.com/uboot/doc/uImage.FIT/overlay-fdt-boot.txt[configuration fragments] for FIT image.
42| `RESOURCE_xxx_pn-aktualizr`|Controls maximum resource usage of the aktualizr service, when `aktualizr-resource-control` is installed on the image. See xref:dev@ota-build::meta-updater-usage.adoc#_aktualizr_service_resource_control[aktualizr service resource control] for details.
43| `SOTA_POLLING_SEC`|Sets polling interval for aktualizr to check for updates if aktualizr-polling-interval is included in the image.
44|==================== \ No newline at end of file
diff --git a/docs/modules/ROOT/pages/supported-boards.adoc b/docs/modules/ROOT/pages/supported-boards.adoc
new file mode 100644
index 0000000..c3b29bf
--- /dev/null
+++ b/docs/modules/ROOT/pages/supported-boards.adoc
@@ -0,0 +1,47 @@
1= Supported boards
2:page-partial:
3// MC: Included in aktualizr/docs/ota-client-guide/modules/ROOT/pages/supported-boards.adoc
4Currently supported platforms are:
5
6* https://github.com/advancedtelematic/meta-updater-raspberrypi[Raspberry Pi 2 and 3]
7* https://github.com/advancedtelematic/meta-updater-minnowboard[Intel Minnowboard]
8* https://github.com/advancedtelematic/meta-updater-qemux86-64[Native QEMU emulation]
9* Renesas R-Car H3 and M3
10* https://github.com/advancedtelematic/meta-updater-ti/[TI BeagleBone Black] (rocko only, using TI SDK 05.03)
11* https://github.com/advancedtelematic/meta-updater-ti/[TI AM65x industrial development kit] (rocko only, using TI SDK 05.03)
12
13Additionally, there is community support for https://github.com/ricardosalveti/meta-updater-riscv[RISC-V] boards, in particular the Freedom U540.
14
15We also historically supported the https://github.com/advancedtelematic/meta-updater-porter[Renesas Porter] board.
16
17== Adding support for your board
18
19If 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:
20
211. Make the board boot into http://www.denx.de/wiki/U-Boot[U-Boot]
222. 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.
23
24Take a look at the https://github.com/advancedtelematic/meta-updater-minnowboard[Minnowboard] or https://github.com/advancedtelematic/meta-updater-raspberrypi[Raspberry Pi] integration layers for examples.
25
26If you want our developers to add support for your board, contact us at mailto:otaconnect.support@here.com[] and we can discuss a potential NRE (Non-recurring Engineering) aggreement.
27
28[NOTE]
29====
30Although we have focused on U-Boot and GRUB so far, other bootloaders can be configured to work with OSTree as well. If you want to use a different bootloader, contact us at mailto:otaconnect.support@here.com[].
31====
32
33Your images will also need network connectivity to be able to reach an actual OTA backend. Our 'poky-sota' distribution does not mandate or install a default network manager but our supported platforms use the `virtual/network-configuration` recipe, which can be used as a starting example.
34
35== Minimum hardware requirements for controllers (ECUs)
36
37The aktuallizr binary is a lightweight {cpp} application between 2-5 MB in size. It uses a miniumum about of resources when idle.
38
39The following hardware is required for your primary ECU:
40
41* At a minimum, aktualizr needs **16 MB of RAM** and **128 MB of storage** to run.
42* We recommend that you use a controller with **128 MB of RAM** and **512 MB storage** -- especially if you if your plan to process large, complex sofware updates.
43
44[NOTE]
45====
46If you plan to send updates to secondary, low-performance ECUs, you can also use a more minimal implementaton called link:https://github.com/advancedtelematic/aktualizr/tree/master/partial/libuptiny[`libuptiny`]. This utility is only 10 KB and performs a minimal verification of software metadata that is less resource intensive. For more information on `libuptiny`, contact us at mailto:otaconnect.support@here.com[].
47==== \ No newline at end of file