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

diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..f8e8ada --- /dev/null +++ b/README.adoc
@@ -0,0 +1,124 @@
		1	= meta-updater
		2
		3	This layer enables over-the-air updates (OTA) with https://github.com/ostreedev/ostree[OSTree] and https://github.com/advancedtelematic/rvi_sota_client[RVI SOTA client].
		4
		5	https://github.com/ostreedev/ostree[OSTree] is a tool for atomic full file system upgrades with rollback capability. OSTree has several advantages over traditional dual-bank systems, but the most important one is that it minimizes network bandwidth and data storage footprint by sharing files with the same contents across file system deployments.
		6
		7	https://github.com/advancedtelematic/rvi_sota_client[RVI SOTA client] adds authentication and provisioning capabilities to OTA and is integrated with OSTree. It connects to https://github.com/advancedtelematic/rvi_sota_server[RVI SOTA server].
		8
		9	== Build
		10
		11	=== Quickstart
		12
		13	If you don't already have a Yocto project that you want to add OTA to, you can use the https://github.com/advancedtelematic/garage-quickstart-rpi[ATS Garage 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. For a detailed getting started tutorial see the https://github.com/advancedtelematic/garage-quickstart-rpi/blob/master/README.adoc[README].
		14
		15	=== Adding meta-updater capabilities to your build
		16
		17	If you already have a Yocto-based project and you want to add atomic filesystem updates to it, you just need to do three things:
		18
		19	1. Clone the `meta-updater` layer and add it to your https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf[bblayers.conf].
		20	2. Clone BSP integration layer (meta-updater-$\{PLATFORM}, e.g. https://github.com/advancedtelematic/meta-updater-raspberrypi[meta-updater-raspberrypi]) and add it to your conf/bblayers.conf. If your board isn't supported yet, you could write a BSP integration for it yourself. See the <<Adding support for your board>> section for the details.
		21	3. Set up your https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#var-DISTRO[distro]. If you are using "poky", the default distro in Yocto, you can change it in your conf/local.conf to "poky-sota". Alternatively, if you are using your own or third party distro configuration, you can add 'require conf/distro/sota.conf.inc' to it, thus combining capabilities of your distro with meta-updater features.
		22
		23	You can then build your image as usual, with bitbake. After building the root file system, bitbake will then create an https://ostree.readthedocs.io/en/latest/manual/adapting-existing/[OSTree-enabled version] of it, commit it to your local OSTree repo and (optionally) push it to a remote server. Additionally, a live disk image will be created (normally named $\{IMAGE_NAME}.-sdimg-ota e.g. core-image-raspberrypi3.rpi-sdimg-ota). You can control this behaviour through <<variables in your local.conf,OSTree-related variables in your local.conf>>.
		24
		25	=== Build with OpenIVI
		26
		27	=== Build in AGL
		28
		29	With AGL you can just add agl-sota feature while configuring your build environment:
		30
		31	....
		32	source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl-appfw-smack agl-devel agl-sota
		33	....
		34
		35	you can then run
		36
		37	....
		38	bitbake agl-demo-platform
		39	....
		40
		41	and get as a result an "ostree_repo" folder in your images directory (tmp/deploy/images/$\{MACHINE}/ostree_repo). It will contain
		42
		43	* your OSTree repository, with the rootfs committed as an OSTree deployment,
		44	* an 'otaimg' bootstrap image, which is an OSTree physical sysroot as a burnable filesystem image, and optionally
		45	* some machine-dependent live images (e.g. '_.rpi-sdimg-ota' for Raspberry Pi or '_.porter-sdimg-ota' Renesas Porter board).
		46
		47	Although aglsetup.sh hooks provide reasonable defaults for SOTA-related variables, you may want to tune some of them.
		48
		49	== Supported boards
		50
		51	Currently supported platforms are
		52
		53	* https://github.com/advancedtelematic/meta-updater-raspberrypi[Raspberry Pi3]
		54	* https://github.com/advancedtelematic/meta-updater-minnowboard[Minnowboard]
		55	* https://github.com/advancedtelematic/meta-updater-qemux86-64[Native QEMU emulation]
		56
		57	=== Adding support for your board
		58
		59	If your board isn't supported yet, you can add board integration code yourself. The main purpose of this code is to provide a bootloader that will be able to use https://ostree.readthedocs.io/en/latest/manual/atomic-upgrades/[OSTree's boot directory]. In the meta-updater integration layers we have written so far, the basic steps are:
		60
		61	1. Make the board boot into http://www.denx.de/wiki/U-Boot[U-Boot]
		62	2. Make U-boot import variables from /boot/loader/uEnv.txt and load the kernel with initramfs and kernel command line arguments according to what is set in this file.
		63
		64	You may take a look into https://github.com/advancedtelematic/meta-updater-minnowboard[Minnowboard] or https://github.com/advancedtelematic/meta-updater-raspberrypi[Raspberry Pi] integration layers for examples.
		65
		66	Although we have used U-Boot so far, other boot loaders can be configured work with OSTree as well.
		67
		68	== SOTA-related variables in local.conf
		69
		70	* OSTREE_REPO - path to your OSTree repository. Defaults to "$\{DEPLOY_DIR_IMAGE}/ostree_repo"
		71	* OSTREE_BRANCHNAME - the branch your rootfs will be committed to. Defaults to "ota"
		72	* 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".
		73	* OSTREE_INITRAMFS_IMAGE - initramfs/initrd image that is used as a proxy while booting into OSTree deployment. Do not change this setting unless you are sure that your initramfs can serve as such a proxy.
		74	* OSTREE_PUSH_CREDENTIALS - when set, your ostree commit will be pushed to a remote repo as a bitbake step. This should be the path to a JSON credentials file in https://github.com/advancedtelematic/sota-tools#credentials[the format accepted by garage-push].
		75
		76	== Usage
		77
		78	=== OSTree
		79
		80	OSTree includes its own simple http server. It just exposes the whole OSTree repository to the network so that any remote device can pull data from it to device's local repository. To use the OSTree http server, you will need OSTree installed on your build machine. (Alternatively, you could run version built inside Yocto using bitbake's http://www.openembedded.org/wiki/Devshell[devshell].)
		81
		82	To expose your repo, run ostree trivial-httpd using any free port:
		83
		84	....
		85	ostree trivial-httpd tmp/deploy/images/qemux86-64/ostree_repo -P 57556
		86	....
		87
		88	You can then run ostree from inside your device by adding your repo:
		89
		90	....
		91	# agl-remote identifies the remote server in your local repo
		92	ostree remote add --no-gpg-verify my-remote http://192.168.7.1:57556 ota
		93
		94	# ota is a branch name in the remote repo, set in OSTREE_BRANCHNAME
		95	ostree pull my-remote ota
		96
		97	# poky is OS name as set in OSTREE_OSNAME
		98	ostree admin deploy --os=poky my-remote:ota
		99	....
		100
		101	After restarting, you will boot into the newly deployed OS image.
		102
		103	For example, on the raspberry pi you can try this sequence:
		104
		105	....
		106	# add remote
		107	ostree remote add --no-gpg-verify agl-snapshot https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/images/raspberrypi3/ostree_repo/ agl-ota
		108
		109	# pull
		110	ostree pull agl-snapshot agl-ota
		111
		112	# deploy
		113	ostree admin deploy --os=agl agl-snapshot:agl-ota
		114	....
		115
		116	=== SOTA tools
		117
		118	SOTA tools now contains only one tool, garage-push that lets you push the changes in OSTree repository generated by bitbake process. It communicates with an http server capable of querying files with HEAD requests and uploading them with POST requests. In particular, this can be used with http://www.atsgarage.com/[ATS Garage]. garage-push is used as follws:
		119
		120	....
		121	garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=/path/to/credentials.json
		122	....
		123
		124	You can set OSTREE_PUSH_CREDENTIALS in your local.conf to make your build results be automatically synchronized with a remote server. Credentials are stored in the JSON format described in the https://github.com/advancedtelematic/sota-tools#credentials[sota-tools README].


diff --git a/README.md b/README.md deleted file mode 100644 index 4da98c4..0000000 --- a/README.md +++ /dev/null
@@ -1,163 +0,0 @@
1	meta-sota
2	=========
3
4	This layer enables over-the-air updates with OSTree and RVI SOTA client.
5
6	[OSTree](https://github.com/ostreedev/ostree) is a tool for atomic full file
7	system upgrades with rollback capability. Main advantage of OSTree compared
8	to traditional dual partition model is that OSTree minimizes network bandwidth
9	and data storage footprint by sharing files with the same contents across file
10	system deployments.
11
12	[RVI SOTA client](https://github.com/advancedtelematic/rvi_sota_client) adds
13	authentication and provisioning capabilities to OTA and is integrated with
14	OSTree.
15
16	Build
17	-----
18
19	### Quickstart ###
20	[ATS Garage Quickstart](https://github.com/advancedtelematic/garage-quickstart-rpi)
21	is an example yocto-based project combining stadard poky distribution with
22	OSTree capabilities. For detailed getting started tutorial see [README](https://github.com/advancedtelematic/garage-quickstart-rpi/blob/master/README.adoc).
23
24	### Adding meta-updater capabilities to your build ###
25	If you already have a Yocto-base project and you want to add atomic filesystem
26	updates to it you need to do just three things:
27
28	1. Clone meta-updater layer and add it to your [conf/bblayers.conf](https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf).
29	2. Clone BSP integration layer (meta-updater-${PLATFORM}, e.g.
30	meta-updater-raspberrypi) and add it to your conf/bblayers.conf. If your board
31	isn't yet supported, you could write BSP integration work yourself. See [Supported boards](#supported-boards)
32	section for the details.
33	3. Set up your [distro](https://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#var-DISTRO).
34	If you are using "poky", the default distro in Yocto, you can change it in your
35	conf/local.conf to "poky-sota". Alternatively if you are using your own or third
36	party distro configuration, you can add 'require conf/distro/sota.conf.inc' to
37	it, thus combining capabilities of your distro with meta-updater features.
38
39	You can then build your image as usual (bitbake <your-image-name>). After building
40	the root file system bitbake will then create an [OSTree-enabled version](https://ostree.readthedocs.io/en/latest/manual/adapting-existing/)
41	of it, commit it to your local OSTree repo and optionally push it to a remote
42	server. Additionally a live disk image will be created (normally named
43	${IMAGE_NAME}.<boardpref>-sdimg-ota e.g. core-image-raspberrypi3.rpi-sdimg-ota).
44	You can control this behaviour though OSTree-related variables in your
45	local.conf, see [respective section](#sota-related-variables-in-localconf)
46	for details.
47
48	### Build with OpenIVI ###
49	### Build in AGL ###
50
51	With AGL you can just add agl-sota feature while configuring your build
52	environment as in
53
54	source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl-appfw-smack agl-devel agl-sota
55
56	you can then just run
57
58	bitbake agl-demo-platform
59
60	and get as a result "ostree_repo" folder in your images directory
61	(tmp/deploy/images/${MACHINE}/ostree_repo) containing your OSTree repository
62	with rootfs committed as an OSTree deployment, 'otaimg' bootstrap image which
63	is an OSTree physical sysroot as a burnable filesystem image and optionally
64	some machine-dependent live images (e.g. '*.rpi-sdimg-ota' for Raspberry Pi or
65	'*.porter-sdimg-ota' Renesas Porter board).
66
67	Although aglsetup.sh hooks provide reasonable defaults for SOTA-related
68	variables you may want to tune some of them.
69
70	Supported boards
71	----------------
72
73	Currently supported platforms are
74
75	* [Raspberry Pi3](https://github.com/advancedtelematic/meta-updater-raspberrypi)
76	* [Minnowboard](https://github.com/advancedtelematic/meta-updater-minnowboard)
77	* [Native QEMU emulation](https://github.com/advancedtelematic/meta-updater-qemux86-64)
78
79	### Adding support for your board
80	If your board isn't yet supported you can add board integration code yourself.
81	The main purpose of this code is to provide a bootloader that will get use of
82	[OSTree's boot directory](https://ostree.readthedocs.io/en/latest/manual/atomic-upgrades/)
83	In meta-updater integration layers finished so far it is done by
84
85	1. Making the board boot into [U-Boot](http://www.denx.de/wiki/U-Boot)
86	2. Making U-boot import variables from /boot/loader/uEnv.txt and load the
87	kernel with initramfs and kernel command line arguments according to what is
88	set this file.
89
90	You may take a look into [Minnowboard](https://github.com/advancedtelematic/meta-updater-minnowboard)
91	or [Raspberry Pi](https://github.com/advancedtelematic/meta-updater-raspberrypi)
92	integration layers for examples.
93
94	It is still possible to make other loaders work with OSTree as well.
95
96	SOTA-related variables in local.conf
97	------------------------------------
98
99	* OSTREE_REPO - path to your OSTree repository.
100	Defaults to "${DEPLOY_DIR_IMAGE}/ostree_repo"
101	* OSTREE_BRANCHNAME - the branch your rootfs will be committed to.
102	Defaults to "ota"
103	* OSTREE_OSNAME - OS deployment name on your target device. For more
104	information about deployments and osnames see
105	[OSTree documentation](https://ostree.readthedocs.io/en/latest/manual/deployment/)
106	Defaults to "poky".
107	* OSTREE_INITRAMFS_IMAGE - initramfs/initrd image that is used as a proxy while
108	booting into OSTree deployment. Do not change this setting unless you are
109	sure that your initramfs can serve as such proxy.
110	* OSTREE_PUSH_CREDENTIALS - when set adds pushing your ostree commit to a remote
111	repo. sota-tools will then use credentials in the file pointed to by this
112	variable.
113
114	Usage
115	-----
116
117	### OSTree ###
118	OSTree includes its own simple http server. It just exposes the whole OSTree
119	repository to the network so that any remote device can pull data from it to
120	device's local repository. To use OSTree http server you need OSTree installed
121	on your build machine. Alternatively, you could run version built inside Yocto
122	using bitbake's [devshell](http://www.openembedded.org/wiki/Devshell).
123
124	To expose your repo run ostree trivial-httpd using any free port.
125
126	ostree trivial-httpd tmp/deploy/images/qemux86-64/ostree_repo -P 57556
127
128	You can then run from inside your device or QEMU emulation, provided your
129	network is set up correctly.
130
131	# agl-remote identifies the remote server in your local repo
132	ostree remote add --no-gpg-verify agl-remote http://192.168.7.1:57556 agl-ota
133
134	# agl-ota is a branch name in the remote repo, set in OSTREE_BRANCHNAME
135	ostree pull agl-remote agl-ota
136
137	# agl is OS name as set in OSTREE_OSNAME
138	ostree admin deploy --os=agl agl-remote:agl-ota
139
140	After restart you should boot into the newly deployed OS image.
141
142	E.g. for the raspberrypi3 you can try this sequence:
143
144	# add remote
145	ostree remote add --no-gpg-verify agl-snapshot https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/images/raspberrypi3/ostree_repo/ agl-ota
146
147	# pull
148	ostree pull agl-snapshot agl-ota
149
150	# deploy
151	ostree admin deploy --os=agl agl-snapshot:agl-ota
152
153	### SOTA tools ###
154	SOTA tools now contains only one tool, garage-push that lets you push the
155	changes in OSTree repository generated by bitbake process. It communicates with
156	an http server capable of querying files with HEAD requests and uploading them
157	with POST requests. garage-push is used as following:
158
159	garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=~/.sota-tools.json --user=username --password=
160
161	You can set OSTREE_PUSH_CREDENTIALS in your local.conf to make your build
162	results be automatically synchronized with a remote server.
163	Credentials are stored in JSON format which is described in [sota-tools documentation](https://github.com/advancedtelematic/sota-tools/blob/master/README.adoc)