diff --git a/doc/source/building-with-yocto.rst b/doc/source/building-with-yocto.rst
new file mode 100644
index 0000000..0e0702c
--- /dev/null
+++ b/doc/source/building-with-yocto.rst
@@ -0,0 +1,115 @@
+==================================
+meta-swupdate: building with Yocto
+==================================
+
+Overview
+========
+
+The Yocto-Project_ is a community project under the umbrella of the Linux
+Foundation that provides tools and template to create the own custom Linux-based
+software for embedded systems.
+
+.. _Yocto-Project: http://www.yoctoproject.org
+.. _meta-SWUpdate:  https://github.com/sbabic/meta-swupdate.git
+
+Add-on features can be added using *layers*. meta-swupdate_ is the layer to
+cross-compile the SWUpdate application and to generate the compound SWU images
+containing the release of the product. As described in Yocto's documentation
+about layers, you should include it in your *bblayers.conf* file to use it.
+
+The swupdate class
+==================
+
+meta-swupdate contains a class specific for SWUpdate. It helps to generate the
+SWU image starting from images built inside the Yocto. It requires that all
+components, that means the artifacts that are part of the SWU image, are present
+in the Yocto's deploy directory.  This class should be inherited by recipes
+generating the SWU. The class defines new variables, all of them have the prefix
+*SWUPDATE_* in the name.
+
+- **SWUPDATE_IMAGES** : this is a list of the artifacts to be packaged together.
+  The list contains the name of images without any extension for MACHINE or
+  filetype, that are added automatically.
+  Example :
+
+::
+
+        SWUPDATE_IMAGES = "core-image-full-cmdline uImage"
+
+- **SWUPDATE_IMAGES_FSTYPES** : extension of the artifact. Each artifact can
+  have multiple extension according to the IMAGE_FSTYPES variable.
+  For example, an image can be generated as tarball and as UBIFS for target.
+  Setting the variable for each artifact telles the class which file must
+  be packed into the SWU image.
+
+
+::
+
+        SWUPDATE_IMAGES_FSTYPES[core-image-full-cmdline] = ".ubifs"
+
+- **SWUPDATE_IMAGES_NOAPPEND_MACHINE** : flag to use drop the machine name from the
+  artifact file. Most images in *deploy* have the name of the Yocto's machine in the
+  filename. The class adds automatically the name of the MACHINE to the file, but some
+  artifacts can be deploes without it.
+
+::
+
+        SWUPDATE_IMAGES_NOAPPEND_MACHINE[my-image] = "1"
+
+- **SWUPDATE_SIGNING** : if set, the SWU is signed.
+- **SWUPDATE_SIGN_TOOL** : instead of using openssl, use SWUPDATE_SIGN_TOOL to sign
+  the image. A typical use case is together with a hardware key.
+- **SWUPDATE_PRIVATE_KEY** : this is the file with the private key used to sign the
+  image.
+- **SWUPDATE_PASSWORD_FILE** : an optional file containing the password for the private
+  key.
+
+Automatic sha256 in sw-description
+----------------------------------
+
+The swupdate class takes care of computing and inserting sha256 hashes in the
+sw-description file. The attribute *sha256* **must** be set in case the image
+is signed. Each artifact must have the attribute:
+
+::
+
+        sha256 = "@artifact-file-name@"
+
+For example, to add sha256 to the standard Yocto core-image-full-cmdline:
+
+::
+
+        sha256 = "@core-image-full-cmdline-machine.ubifs";
+
+
+The name of the file must be the same as in deploy directory.
+
+
+Template for recipe using the class
+-----------------------------------
+
+::
+
+        DESCRIPTION = "Example recipe generating SWU image"
+        SECTION = ""
+
+        LICENSE = ""
+
+        # Add all local files to be added to the SWU
+        # sw-description must always be in the list.
+        # You can extend with scripts or wahtever you need
+        SRC_URI = " \
+            file://sw-description \
+            "
+
+        # images to build before building swupdate image
+        IMAGE_DEPENDS = "core-image-full-cmdline virtual/kernel"
+
+        # images and files that will be included in the .swu image
+        SWUPDATE_IMAGES = "core-image-full-cmdline uImage"
+
+        # a deployable image can have multiple format, choose one
+        SWUPDATE_IMAGES_FSTYPES[core-image-full-cmdline] = ".ubifs"
+        SWUPDATE_IMAGES_FSTYPES[uImage] = ".bin"
+
+        inherit swupdate
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2f74c7d..f7c4b85 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -32,6 +32,7 @@ SWUpdate Documentation
    suricatta.rst
    swupdate-ipc.rst
    progress.rst
+   building-with-yocto.rst
 
 ############################################
 Help and support
