Merge pull request #81 from pohly/ostro-1.0-fixes

manual pull: several doc and code fixes

Author: mythi

conf/combo-layer.conf

@@ -29,7 +29,7 @@ src_uri = git@github.com:ostroproject/meta-ostro.git
 dest_dir = .
 hook = conf/combo-layerhook-generic.sh
 branch = master
-last_revision = ecf4003a19828c23f714b77dd82dbe5b4ddfe87f
+last_revision = 3c2b33199550139622e5aee5719b847f1320591f
 
 [meta-ostro-fixes]
 src_uri = git@github.com:ostroproject/meta-ostro-fixes.git
@@ -57,7 +57,7 @@ src_uri = git@github.com:ostroproject/meta-appfw.git
 dest_dir = meta-appfw
 hook = conf/combo-layerhook-generic.sh
 branch = master
-last_revision = f400506cdb96eca8ed55bf5c0400cd53b3138e6e
+last_revision = a092a3c5751537e65a580df5aa0f19ad161195ca
 
 [meta-openembedded]
 src_uri = git://git.openembedded.org/meta-openembedded

doc/howtos/howtos.rst

@@ -1,7 +1,7 @@
 .. _howtos:
 
-Ostro |trade| OS Project Notes
-################################
+Ostro |trade| OS Project How-Tos
+#################################
 
 Our technical documentation for the Ostro OS is being developed right along with the OS features.  
 Here are some how-to technical notes that help explain how you can use Ostro OS capabilities and 
@@ -23,6 +23,7 @@ Technical Notes
    firewall-configuration
    ip-address-config
    pull-request-guidelines
+   software-update-server
 
 Process Notes
 =============

doc/howtos/software-update-server.rst

@@ -9,7 +9,7 @@ a repository used for updating devices based on Ostro OS.
 Prerequisites
 =============
 
-- additional (fast) disk space: the SW Update tool is provided as
+- **Additional (fast) disk space**: the SW Update tool is provided as
   an additional layer, therefore it doesn't require any additional
   element.
   The process of generating the bundles and updates can be very
@@ -21,7 +21,7 @@ Prerequisites
   The actual disk footprint depends on the bundles selected and
   defined and will be larger than that produced by a simple typical
   distribution build based on OECore or Yocto Project.
-- signing keys (alternatively testing keys from the :file:`swupd-server`
+- **Signing keys** (alternatively testing keys from the :file:`swupd-server`
   project can be used).
 
 Bundles definition
@@ -42,99 +42,98 @@ from the `Ostro OS download server`_
 
 These are the main steps:
 
-- Optionally, in ``conf/local.conf`` or equivalent location, set the
-  `OS_VERSION` variable to an integer value.
-  If set explicitly, this number must be increased before each build
-  that generates swupd update artefacts.
+#. Optionally, in ``conf/local.conf`` or equivalent location, set the
+   `OS_VERSION` variable to an integer value.
+   If set explicitly, this number must be increased before each build
+   that generates swupd update artefacts.
 
-- Assign a list of bundle names to ``SWUPD_BUNDLES``::
+#. Assign a list of bundle names to ``SWUPD_BUNDLES``::
 
-    SWUPD_BUNDLES = "feature_one feature_two"
+     SWUPD_BUNDLES = "feature_one feature_two"
 
-- For each named bundle, setup a varflag of ``BUNDLE_CONTENTS``
-  that matches the bundle name, and initialize it with a list of
-  packages whose content must be included in the bundle::
+#. For each named bundle, setup a varflag of ``BUNDLE_CONTENTS``
+   that matches the bundle name, and initialize it with a list of
+   packages whose content must be included in the bundle::
 
-    BUNDLE_CONTENTS[feature_one] = "package_one package_three package_six"
+     BUNDLE_CONTENTS[feature_one] = "package_one package_three package_six"
 
 Creating a Custom Image and matching Software Update Repository
 ===============================================================
 
 Some of the steps listed in this section are optional and cover
-advanced configuration functionality.
-Not all the users will need them, if the default configuration of
-the Ostro OS meets their needs.
+advanced configuration functionality that's only needed
+if the default configuration of
+the Ostro OS already meets your needs.
 
 The process is exemplified by using real components and describing
-what each step looks like, when applied to such components.
-Unless stated otherwise, the changes described are intended for
-the file ``conf/local.conf``.
+what each step looks like when applied to such components.
+Unless stated otherwise, the changes described are made in
+the ``conf/local.conf`` file.
 
 
 Step 0: Review and optionally modify the content of the os-core bundle
 ----------------------------------------------------------------------
-The os-core bundle comes with a predefined set of components,
+The ``os-core`` bundle comes with a predefined set of components,
 however each device is likely to have slightly different requirements.
 In some cases it might be necessary to adjust the set of components
-included in os-core.
+included in ``os-core``.
 
 To do this, either modify or extend the ``OSTRO_IMAGE_FEATURES_REFERENCE``
 and the ``OSTRO_IMAGE_INSTALL_REFERENCE`` variables for changes
 respectively to the feature and component sets.
 
-Why modifying os-core? Because it's the only unremovable bundle and
-therefore it is well suited to deliver to the device all those tools
-that must always be available.
+We're modifying ``os-core`` because it's the only unremovable bundle and is
+therefore well suited to deliver tools
+that must always be available to your devices. For many IoT products,
+the actual application would be added to ``os-core`` like this.
 
-Example::
+For example, you can add the content of the ``sudo`` recipe to the 
+``os-core`` bundle by adding this line to your ``local.conf`` file::
 
   ``OSTRO_IMAGE_INSTALL_REFERENCE += "sudo"``
 
-will add the content of the ``sudo`` recipe to the bundle os-core.
-
-.. note::
-   The step shown works only for adding components to os-core.
+Adding recipes this way works only for adding components to ``os-core``
+and is the typical case when customizing Ostro OS, because the
+``os-core`` is a minimal configuration.
 
-   This is the typical case when customizing Ostro OS, because the
-   os-core configuration is very minimal.
+However, if you need to remove something from ``os-core``,
+you'll create either a new image recipe or a new
+``.bbappend file``, where you'll modify the variables that define the
+content of ``os-core``.
 
-   However, in case one needs to remove something from os-core,
-   it is necessary to create either a new image recipe or a new
-   .bbappend file, where to modify the variables that define the
-   content of os-core.
+These are the variable that must be modified::
 
-   These are the variable that must be modified::
+- OSTRO_IMAGE_FEATURES_REFERENCE
+- OSTRO_IMAGE_INSTALL_REFERENCE
+- IMAGE_INSTALL
 
-   - OSTRO_IMAGE_FEATURES_REFERENCE
-   - OSTRO_IMAGE_INSTALL_REFERENCE
-   - IMAGE_INSTALL
-
-   The recommended way is to modify a copy of the original recipe
-   ``ostro-image-swupd.bb`` and refer to ``ostro-image.bbclass``
-   for the values to use.
+We recommend you modify a copy of the original recipe
+``ostro-image-swupd.bb`` and refer to ``ostro-image.bbclass``
+for the values to use.
 
 
 Step 1: Review and optionally modify the list of bundles
 --------------------------------------------------------
 Ostro already defines some bundles, and users can define additional ones.
 
-Example::
+Example:::
 
   SWUPD_BUNDLES += "sudo_bundle"
   BUNDLE_CONTENTS[sudo_bundle] = "sudo"
 
-This example is an alternative to add the component that was shown in
-Step 0.  Instead of extending the content of os-core, put the extra
-component in its own bundle. The main difference is that this
-approach will not install the component by default in any image.
+This example is an alternative way to add the component shown in
+Step 0 above, but has an important difference.  Instead of extending 
+the content of ``os-core``, this alternative way put the extra
+component in its own bundle and will not install the component by default 
+in any image.
 
 
 Step 2: Review and optionally modify the content of the images created
 ----------------------------------------------------------------------
 It is also possible to choose which bundles will be pre-installed on the
 customized image, by:
 
-#. adding to the list of buildable images a new one, which contains the
+#. Adding a new item to the list of buildable images, and list the
    bundle(s) desired.
 
    Example::
@@ -143,7 +142,7 @@ customized image, by:
        pre_installed_content \
      "
 
-#. defining the content of the new buildable image (the image with the
+#. Defining the content of the new buildable image (the image with the
    pre-installed bundles, from the previous point), by adding a varflag
    to SWUPD_IMAGES that enumerates the bundles to pre-install.
 
@@ -158,31 +157,45 @@ customized image, by:
    syntax. The other identifiers are under the developer's control.
 
 
-This will add, to the set of images that are buildable, one referred to as
-``ostro-image-swupd-pre_installed_content``, which contains, besides the
-os-core bundle, also the ``sudo_bundle`` bundle from Step 1 and whatever
+This will add a new image option called
+``ostro-image-swupd-pre_installed_content``
+to the set of images that are buildable. This new image
+contains the
+``os-core`` bundle,  the ``sudo_bundle`` bundle from Step 1, and whatever
 else might have been added.
 
-The main difference, compared to the approach taken in Step 0 is that
-this approach allows for removing the content of the bundle without having to
+If you have ``sudo`` as part of ``os-core``, then you:
+- remove it from the bundle and publish the update, *all* the devices will have sudo removed.
+- add it to the bundle and publish the update, *all* the devices will have sudo installed.
+
+If you have ``sudo`` as ``sudo_bundle``, then you do not automatically install or remove 
+that in any device. You make it available and have an option to be installed or not on each device.
+
+Put another way, the purpose of using a bundle is to allow a feature to be installed 
+or removed *per device* or
+an application that one user may want while another may not. 
+For example, a security system device may optionally install the upnp/dlna media provider to access 
+the recorded files, whle a drone device could have a "camera" bundle installed containing the kernel module (v4l), 
+media pipeline (gstreamer) and a server to stream it.
+
+Compared to the approach taken in Step 0, 
+this approach allows you to remove the content of the bundle without having to
 create an update (and thus a new release).
 
 .. note::
-   Each bundle defined generates a non-negligible amount of load, when
-   building images and SW Update repositories.
-
-   It is therefore recommended to keep enabled only those bundles that
+   Each defined bundle generates an additional workload when
+   building images and SW Update repositories so we recommend
+   you enable only those bundles that
    are effectively useful for the specific use-case targeted.
 
-   In case one wants to modify the set of predefined bundles that come
-   from the defaults of Ostro OS, it is possible to override the variable
-   ``SWUPD_BUNDLES``.
-
-   Doing so will discard anything that was part of the defaults, therefore
-   if any of the pre-defined bundles is still needed, it must be listed
-   again, explicitly.
+Products should override the set of predefined default bundles that come
+from Ostro OS, by editing the
+``SWUPD_BUNDLES`` variable.  Doing so will discard anything that was 
+part of the Ostro OS defaults;
+if any of the pre-defined bundles are still needed, they must be 
+explicitly listed again.
 
-   Example::
+Example::
 
    ``SWUPD_BUNDLES = "sudo_bundle"``
 
@@ -191,20 +204,20 @@ create an update (and thus a new release).
 Step 3: Build the images and the SW Update repositories
 -------------------------------------------------------
 
-The typical invocation for generating the basic Ostro OS image and related
+The typical command for generating the basic Ostro OS image and related
 SW Update stream is::
 
  $ bitbake ostro-image-swupd
 
-However, if one wants to have pre-installed bundles, then the invocation
+However, if one wants to have pre-installed bundles, then the command
 must refer to the specific variant.
 
-  Example (Continuing from Step2)::
+Example (Continuing from Step 2)::
 
-    $ bitbake ostro-image-swupd-pre_installed_content
+  $ bitbake ostro-image-swupd-pre_installed_content
 
-Assuming that the chosen architecture was ``intel-corei7-64``, the yield
-from the command in the Example is:
+Assuming that the chosen architecture defined in ``local.conf`` was ``intel-corei7-64``, 
+the yield from the command in the Example is:
 
 - The image with the chosen pre-installed bundles::
 
@@ -219,26 +232,24 @@ from the command in the Example is:
     tmp-glibc/deploy/swupd/intel-corei7-64/ostro-image-swupd/
 
   This folder contains both data from intermediate steps and the actual
-  SW Update stream.
-
-  Its location is::
+  SW Update stream located here::
 
     tmp-glibc/deploy/swupd/intel-corei7-64/ostro-image-swupd/www/
 
-  This folder will contain also data related to following builds and it is
-  the one that must be exposed to the device in need of maintenance, through
-  a web server, for example nginx or apache.
+  This folder will also contain data related to subsequent builds and
+  must be exposed through a web server (e.g., ``nginx`` or ``apache``) 
+  to the device running the SW update client for getting its maintentance.
 
 
 Step 4: Create an update from the previous step
 -----------------------------------------------
 
 Continuing with the previous example, one possible enhancement is to add a
-new bundle, but it would have been also possible to modify the content of
+new bundle, or modify the content of
 the existing bundle(s).
 
-To keep the execution simple, the bundle will contain only one component,
-which is currently missing from the "Version 10" of the distribution: the
+To keep the execution simple, our example bundle will contain only one component
+currently missing from the, for example, "Version 10" of the distribution: the
 ``sed`` command.
 
 The changes required are:
@@ -263,25 +274,19 @@ The changes required are:
        sed_bundle \
      "
 
-   But it's not required in the example, so this phase will be skipped.
+   But it's not required in this example, so we'll skip this step.
 
 Finally, to generate the desired artefacts, the build command must be
-iterated once more::
+run again::
 
     $ bitbake ostro-image-swupd-pre_installed_content
 
-The yield is similar to the previous invocation, however now it also
+The yield is similar to the previous invocation, however now it also  
 contains the SW Update data for the newly defined bundle containing ``sed``.
 
-
-.. note::
-   Because ``sed`` was introduced in the build ``Version 20``, devices that
-   are on earlier versions will not have access to this bundle.
-
-   Such devices must first upgrade to a version where the bundle is
-   available and only then, they can install the new bundle.
-
+Because ``sed`` was introduced in the build ``Version 20``, devices that
+are using earlier versions will not have access to this bundle. 
+Such devices must first upgrade to a version where the bundle is
+available and only then, they can install the new bundle.
 
 .. _`swupd layer`: http://git.yoctoproject.org/cgit/cgit.cgi/meta-swupd/tree/docs/Guide.md
-
-

meta-appfw/recipes-appfw/iot-app-fw/iot-app-fw_git.bb

@@ -7,12 +7,12 @@ LIC_FILES_CHKSUM = "file://LICENSE-BSD;md5=f9f435c1bd3a753365e799edf375fc42"
 DEPENDS = "json-c systemd"
 
 SRC_URI = " \
-    git://git@github.com/ostroproject/iot-app-fw.git;protocol=https;branch=kli/devel/1.x \
+    git://git@github.com/ostroproject/iot-app-fw.git;protocol=https;branch=kli/devel/1.x-fixes \
     file://80-container-host0.network \
     file://80-container-ve.network \
   "
 
-SRCREV = "e764dfa558e649f64f73bed7b96080f9f844c508"
+SRCREV = "7610344d05199a35103e04a2f08cee50397db7da"
 
 inherit autotools pkgconfig systemd
 

meta-ostro/conf/layer.conf

@@ -4,7 +4,12 @@ BBPATH =. "${LAYERDIR}:"
 
 # We have recipes-* directories, add to BBFILES
 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
-	${LAYERDIR}/recipes-*/*/*.bbappend"
+	${LAYERDIR}/recipes-*/*/*.bbappend \
+        ${LAYERDIR}/fixes/*/recipes-*/*/*.bb \
+        ${LAYERDIR}/fixes/*/recipes-*/*/*.bbappend \
+        ${LAYERDIR}/fixes/*/recipes-*/*/*/*.bb \
+        ${LAYERDIR}/fixes/*/recipes-*/*/*/*.bbappend \
+"
 
 # Set a variable to get to the top of the metadata location
 IMAGE_DSK_BASE := '${LAYERDIR}'