From 8119ed111cd5c7106a293085e4a0b57469ce3a02 Mon Sep 17 00:00:00 2001
From: Karl Schwabe <ksschwabe@gmail.com>
Date: Wed, 14 Mar 2018 10:30:53 +0100
Subject: [PATCH 1/2] Adds description for using out-of-tree message definition

---
 en/advanced/out_of_tree_modules.md | 36 +++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/en/advanced/out_of_tree_modules.md b/en/advanced/out_of_tree_modules.md
index e419ba92e91..525ac2d0519 100644
--- a/en/advanced/out_of_tree_modules.md
+++ b/en/advanced/out_of_tree_modules.md
@@ -38,9 +38,43 @@ px4_add_module(
 	)
 
 ```
+
+
+# Out-of-tree uORB Message Definitions
+
+uORB messages can also be defined out-of-tree. For this, the
+`$EXTERNAL_MODULES_LOCATION/msg` needs to exist.
+
+- Place all new message definitions within the `$EXTERNAL_MODULES_LOCATION/msg`
+  directory. The format of these new out-of-tree message definitions are the same
+  as for any other [uORB message definition](../middleware/uorb.md#adding-a-new-topic).
+- Add a file `$EXTERNAL_MODULES_LOCATION/msg/CMakeLists.txt` with content:
+
+```
+set(config_msg_list_external
+    <message1>.msg
+    <message2>.msg
+    <message3>.msg
+    PARENT_SCOPE
+    )
+
+```
+where `<message#>.msg` is the name of the uORB message definition file to be processed 
+and used for uORB message generation.
+
+The out-of-tree uORB messages will be generated in the same locations as the normal uORB messages.
+The uORB topic headers are generated in `<build_dir>/uORB/topics/`, and the message source files are
+generated in `<build_dir>/msg/topics_sources/`.
+
+The new uORB messages can be used like any other uORB message as described [here](../middleware/uorb.md#adding-a-new-topic).
+
+> **Warning** The out-of-tree uORB message definitions cannot have the same name as any of the normal uORB
+messages.
+
+# Building Out-of-tree modules and uORB Messages
+
 - Execute `make posix EXTERNAL_MODULES_LOCATION=<path>`. Any other build target
   can be used, but the build directory must not yet exist. If it already exists,
   you can also just set the cmake variable in the build folder.
   For the following incremental builds `EXTERNAL_MODULES_LOCATION` does not need
   to be specified anymore.
-

From b6243ad40e0ac563148d2923c85dc765b3b4933f Mon Sep 17 00:00:00 2001
From: Karl Schwabe <ksschwabe@gmail.com>
Date: Thu, 15 Mar 2018 10:19:51 +0100
Subject: [PATCH 2/2] uORB: adds link to section on out-of-tree uORB message
 definitions

---
 en/middleware/uorb.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/en/middleware/uorb.md b/en/middleware/uorb.md
index 53e854c4a13..2c6cfc5a0f1 100644
--- a/en/middleware/uorb.md
+++ b/en/middleware/uorb.md
@@ -12,6 +12,10 @@ It is started with `uorb start`. Unit tests can be started with `uorb_tests`.
 
 ## Adding a new topic
 
+New uORB topics can be added either within the main PX4/Firmware repository, or can be added
+in an out-of-tree message definitions. For information on adding out-of-tree uORB message 
+definitions, please see [this section](../advanced/out_of_tree_modules.md#out-of-tree-uorb-message-definitions).
+
 To add a new topic, you need to create a new `.msg` file in the `msg/`
 directory and add the file name to the `msg/CMakeLists.txt` list. From this,
 the needed C/C++ code is automatically generated.