samples: Add tutorial

Signed-off-by: Gerson Fernando Budke <[email protected]>

README.rst

@@ -7,7 +7,7 @@
 Zephyr Behaviour Tree
 #####################
 
-This repository is the Zephyr Behavior Tree module.
+This repository is the Zephyr Behaviour Tree module.
 
 Preparation
 ***********
@@ -86,27 +86,29 @@ Make sure that all requirements are meet:
 Examples
 ********
 
+* The `Tutorial`_ guide you step by step on ZephyrBT (comming soon).
+
 * The `Minimal`_ is an example how to use the ZephyrBT without any IDE.
+
 * The `Dynamic`_ uses their own thread and generate data and stubs from `Groot2`_ IDE.
-* The ``Tutorial`` guide you step by step on ZephyrBT (comming soon).
+
+.. _Tutorial:
+  samples/subsys/zephyrbt/tutorial/README.rst
 
 .. _Minimal:
-  https://github.com/OSSystems/ZephyrBT/blob/master/samples/subsys/zephyrbt/minimal/README.rst
+  samples/subsys/zephyrbt/minimal/README.rst
 
 .. _Dynamic:
-  https://github.com/OSSystems/ZephyrBT/blob/master/samples/subsys/zephyrbt/dynamic/README.rst
-
-.. _Tutorial:
-  https://github.com/OSSystems/ZephyrBT/blob/master/samples/subsys/zephyrbt/tutorial/README.rst
+  samples/subsys/zephyrbt/dynamic/README.rst
 
 .. _Groot2:
   https://www.behaviortree.dev/groot/
 
 Tests
 *****
 
-To execute the tests just run twister pointing the TESTSUITE_ROOT to your $HOME/zephyrbt
-folder.
+To execute the tests just run twister pointing the TESTSUITE_ROOT to your
+$HOME/zephyrbt folder.
 
 .. code-block:: console
 

include/zephyr/zephyrbt/zephyrbt.h

@@ -2,7 +2,7 @@
  * Copyright (c) 2024 O.S. Systems Software LTDA.
  * Copyright (c) 2024 Freedom Veiculos Eletricos
  *
- * SPDX-License-Identifier: UNLICENSED
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 #ifndef ZEPHYR_INCLUDE_ZEPHYRBT_ZEPHYRBT_H_

samples/subsys/zephyrbt/tutorial/CMakeLists.txt

@@ -0,0 +1,26 @@
+# Copyright (c) 2024 O.S. Systems Software LTDA.
+# Copyright (c) 2024 Freedom Veiculos Eletricos
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+include(${ZEPHYR_ZEPHYRBT_MODULE_DIR}/cmake/zephyrbt-from-behaviourtreecpp-xml.cmake)
+
+project(zephyrbt_tutorial)
+
+zephyr_include_directories(
+	${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+target_sources(app PRIVATE
+	src/main.c
+)
+
+zephyrbt_define_from_behaviourtreecpp_xml(app
+	models/tutorial.xml
+	${CMAKE_BINARY_DIR}/include
+	${CMAKE_BINARY_DIR}/src
+	1024
+	0
+)

samples/subsys/zephyrbt/tutorial/README.rst

@@ -0,0 +1,63 @@
+.. Copyright (c) 2024 O.S. Systems Software LTDA.
+.. Copyright (c) 2024 Freedom Veiculos Eletricos
+.. SPDX-License-Identifier: Apache-2.0
+.. _zephyrbt_tutorial:
+
+Zephyr Behaviour Tree - Tutorial
+################################
+
+Overview
+********
+
+The Let's Drink tutorial was implemented to promote the ZephyrBT at
+first Zephyr Zurich meetup on 21 Nov 2024. The application is simpler
+and the documentation was written to guide in the basics of Behaviour
+Tree using the Groot2 IDE and demonstrate the flexibility of the
+technology.
+
+.. image:: lessons/img/Zephyr-meetup-general-Zurich-Switzerland-November-21-2024.webp
+  :scale: 50 %
+  :alt: Zephyr meetup Zurich Switzerland November 21-2024
+
+Pre-requirements
+================
+
+Make sure you executed the steps from `zephyrbt git hub page`_.
+
+.. _zephyrbt git hub page:
+  https://github.com/OSSystems/ZephyrBT
+
+Building and Running
+====================
+
+This application can be built and executed on ``native_posix_64`` as follows:
+
+.. code-block:: console
+
+   west build -p -b native_posix_64 samples/subsys/zephyrbt/tutorial -t run
+
+Check the application running on the console.
+
+Lessons
+*******
+
+* `lesson 1 - Implement the First Action`_
+* `lesson 2 - The Action initialization function`_
+* `lesson 3 - Share data between nodes`_
+* `lesson 4 - The Behaviour Tree user data holder`_
+* `lesson 5 - Using ZBUS`_
+
+.. _lesson 1 - Implement the First Action:
+  lessons/lesson-1/lesson-1.rst
+
+.. _lesson 2 - The Action initialization function:
+  lessons/lesson-2/lesson-2.rst
+
+.. _lesson 3 - Share data between nodes:
+  lessons/lesson-3/lesson-3.rst
+
+.. _lesson 4 - The Behaviour Tree user data holder:
+  lessons/lesson-4/lesson-4.rst
+
+.. _lesson 5 - Using ZBUS:
+  lessons/lesson-5/lesson-5.rst

samples/subsys/zephyrbt/tutorial/lessons/lesson-1/lesson-1.rst

@@ -0,0 +1,71 @@
+.. Copyright (c) 2024 O.S. Systems Software LTDA.
+.. Copyright (c) 2024 Freedom Veiculos Eletricos
+.. SPDX-License-Identifier: Apache-2.0
+.. _zephyrbt_tutorial_lesson_1:
+
+Zephyr Behaviour Tree - Tutorial - Lesson 1
+###########################################
+
+Implement the First Action
+**************************
+
+The first example how to implement the Grab Beer Action. The change is add a
+counter to make the action fail after some iterations. This simpler example can
+be easier translated to check some hardware condition like ADC's, actuators etc.
+
+.. image:: ../img/bt-lesson-1.png
+  :scale: 50 %
+  :alt: Initial Behaviour Tree
+
+1- Add a new file at <project>/src/grab_beer.c
+
+2- Add the following content
+
+.. code-block:: c
+
+   #include <stdint.h>
+   #include <zephyr/zephyrbt/zephyrbt.h>
+   #include <zephyr/sys/util.h>
+
+   #include <zephyr/logging/log.h>
+   LOG_MODULE_REGISTER(grab_beer, CONFIG_ZEPHYR_BEHAVIOUR_TREE_LOG_LEVEL);
+
+   enum zephyrbt_child_status
+   zephyrbt_action_grab_beer(struct zephyrbt_context *ctx,
+            struct zephyrbt_node *self)
+   {
+      static int count = 0;
+
+      ++count;
+
+      LOG_DBG("\nGrab Beer try: %d\n", count);
+
+      if (count < 3) {
+         return ZEPHYRBT_CHILD_SUCCESS_STATUS;
+      }
+
+      return ZEPHYRBT_CHILD_FAILURE_STATUS;
+   }
+
+3- Update the CMakeLists.c
+
+.. code-block:: cmake
+
+   target_sources(app PRIVATE
+      src/main.c
+      src/grab_beer.c
+   )
+
+4- Run the program again
+
+.. code-block:: console
+
+   $> west build - run
+
+5- Compare the execution
+
+At this time the initial output will be the same but after 3 iterations the
+system will grab the water as a fallback action.
+
+You can explore more ideas and try to implement other actions to play with the
+application.

samples/subsys/zephyrbt/tutorial/lessons/lesson-1/resources/CMakeLists.txt

@@ -0,0 +1,27 @@
+# Copyright (c) 2024 O.S. Systems Software LTDA.
+# Copyright (c) 2024 Freedom Veiculos Eletricos
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+include(${ZEPHYR_ZEPHYRBT_MODULE_DIR}/cmake/zephyrbt-from-behaviourtreecpp-xml.cmake)
+
+project(zephyrbt_tutorial)
+
+zephyr_include_directories(
+	${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+target_sources(app PRIVATE
+	src/main.c
+	src/grab_beer.c
+)
+
+zephyrbt_define_from_behaviourtreecpp_xml(app
+	models/tutorial.xml
+	${CMAKE_BINARY_DIR}/include
+	${CMAKE_BINARY_DIR}/src
+	1024
+	0
+)

samples/subsys/zephyrbt/tutorial/lessons/lesson-1/resources/src/grab_beer.c

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2024 O.S. Systems Software LTDA.
+ * Copyright (c) 2024 Freedom Veiculos Eletricos
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdint.h>
+#include <zephyr/sys/util.h>
+#include <zephyr/zephyrbt/zephyrbt.h>
+
+#include <zephyr/logging/log.h>
+LOG_MODULE_REGISTER(grab_beer, CONFIG_ZEPHYR_BEHAVIOUR_TREE_LOG_LEVEL);
+
+enum zephyrbt_child_status
+zephyrbt_action_grab_beer(struct zephyrbt_context *ctx,
+			  struct zephyrbt_node *self)
+{
+	static int count = 0;
+
+	++count;
+
+	LOG_DBG("\nGrab Beer try: %d\n", count);
+
+	if (count < 3) {
+		return ZEPHYRBT_CHILD_SUCCESS_STATUS;
+	}
+
+	return ZEPHYRBT_CHILD_FAILURE_STATUS;
+}