Foxy update documentation

README.md

@@ -2,120 +2,100 @@
 
 ## Disclaimer
 
-This is work in progress and should be considered just as a proof of concept on how to leverage ROS 2 features to use in real-time applications. Any feedback and help to improve the project is appreciated.
+This is work in progress and should be considered just as a proof of concept on how to leverage ROS
+ 2 features to use in real-time applications. Any feedback and help to improve the project is
+  appreciated.
 
-**Foxy branch is under active development. The instructions are no longer up-to-date and have to be updated. The current status can be checked here: https://github.com/ros2-realtime-demo/pendulum/issues/35**
+**Foxy branch is under active development. The current status can be checked here: 
+https://github.com/ros2-realtime-demo/pendulum/issues/35**
 
-### Build status
+## Build status
 
-| foxy | eloquent |  dashing |
-|--------- | -------- | ------- |
-| ![Build Status](https://github.com/ros2-realtime-demo/pendulum/workflows/build/badge.svg?branch=foxy) | ![Build Status](https://github.com/ros2-realtime-demo/pendulum/workflows/build/badge.svg?branch=eloquent) | ![Build Status](https://github.com/ros2-realtime-demo/pendulum/workflows/build/badge.svg?branch=dashing) |
+![Build Status](https://github.com/ros2-realtime-demo/pendulum/workflows/build/badge.svg?branch=foxy) [![License](https://img.shields.io/badge/license-Apache%202-blue)]() ![GitHub issues](https://img.shields.io/github/issues/ros2-realtime-demo/pendulum)
 
-[![License](https://img.shields.io/badge/license-Apache%202-blue)]() ![GitHub issues](https://img.shields.io/github/issues/ros2-realtime-demo/pendulum)
-
-# Table of content
+## Table of content
 
 * [Inverted pendulum demo](#inverted-pendulum-demo)
     * [Project description](#project-description)
     * [Install instructions](#install-instructions)
     * [How to run the demo](#how-to-run-the-demo)
-    * [Managed nodes](#managed-nodes)
-    * [Real-time demo](#rtdemo)
+    * [How to configure real-time settings](#rtdemo)
+    * [How to measure real-time performance metrics](#rtmetrics)
     * [How to contribute](#how-to-contribute)
     * [Issues and feature request](#issues-and-feature-request)
 
-### Project description
+## Project description
 
-The aim of this project is to show the real-time capabilities using the ROS2 framework. This project is based on the [previous](https://index.ros.org/doc/ros2/Tutorials/Real-Time-Programming/) work made by the Open Robotics. The project uses these packages as a base.
+The aim of this project is to show the real-time capabilities using the ROS2 framework. This
+ project is based on the [previous](https://index.ros.org/doc/ros2/Tutorials/Real-Time-Programming/)
+  work made by the Open Robotics. The project uses these packages as a base.
 
 This is the motivation of using an inverted pendulum for a real-time demo:
 
 >A classic example of a controls problem commonly solved by real-time computing is balancing an inverted pendulum. If the controller blocked for an unexpectedly long amount of time, the pendulum would fall down or go unstable. But if the controller reliably updates at a rate faster than the motor controlling the pendulum can operate, the pendulum will successfully adapt react to sensor data to balance the pendulum.
 
-For a more detailed description of demo the project design be found here: [Design Article](docs/design.md)
+A more detailed description of demo the project design be found here: [Design Article](docs/design.md)
 
-#### Install instructions
+## Install instructions
 
-In order to get the project ready, first you need to install [ROS2](https://index.ros.org/doc/ros2/Installation/Eloquent/) and [rosdep](http://wiki.ros.org/rosdep).
+ Several ways to install the pendulum demo project are provided depending on the user needs. 
+
+- [ADE based installation](docs/installation.md#ade#based#installation): This provides a 
+pre-configured Docker image with everything ready to be used. This is the recommended option to
+ quickly test the demo. It is also useful to have development environment to add new features.
+- [Installation from source](docs/installation.md#installation#from#source): provides instructions
+ to build all the required ROS 2 packages from source.
+- [Crosscompilation](docs/installation.md#crosscompile): provides instructions to
+ crosscompile the demo for an embedded device.
+- [Pre-configured Raspberry PI image](docs/installation.md#raspberry#pi#image): provides a
+ Raspberry PI with everything configured in a Linux Real-time (RT-PREEMPT patch).
 
+## How to run the demo
 
-```bash
-source /opt/ros/eloquent/setup.bash
-mkdir -p ~/pendulum_ws/src
-cd ~/pendulum_ws/src
-git clone https://github.com/ros2-realtime-demo/pendulum
-cd ~/pendulum_ws
-sudo rosdep init
-rosdep update
-rosdep install -q -y --from-paths src --ignore-src --rosdistro eloquent
-colcon build --merge-install # OR colcon build --symlink-install
-```
+### Source your workspace
 
-#### How to run the demo
+If installed as an ADE image:
 
-Terminal 1:
 ```bash
-ros2 launch pendulum_bringup pendulum_bringup.launch.py
+source /opt/ros/foxy/setup.bash
 ```
 
-Terminal 2. Activate nodes. Put '0' to activate all nodes:
-```bash
-ros2 run pendulum_manager pendulum_manager
-```
+If installed from source:
 
-Terminal 3. Launch rviz:
 ```bash
-export LC_NUMERIC="en_US.UTF-8" # Make sure that your locales are correctly setup.
-ros2 run rviz2 rviz2 -d `ros2 pkg prefix pendulum_bringup --share`/config/pendulum.rviz
-```
-
-If everything went well we should see now the inverted pendulum being controlled in rviz:
-
-![pendulum_rviz](docs/images/pendulum_rviz.gif)
-
-Now we can try to move the cart by sending a setpoint command.
-
-
-In a new terminal. Move the cart to x=5:
-```bash
-ros2 topic pub -1 /pendulum_setpoint pendulum2_msgs/msg/PendulumCommand "cart_position: 5.0"
+cd ~/pendulum_ws
+source ./install/setup.bash
 ```
 
-![pendulum_rviz](docs/images/pendulum_rviz_setpoint.gif)
+### Launch the demo
 
-Now let's try to push the cart by sending a disturbance force:
+Launch the demo with rviz enabled:
 
 ```bash
-ros2 topic pub -1 /pendulum_disturbance pendulum2_msgs/msg/PendulumCommand "cart_force: 100"
+ros2 launch pendulum_bringup pendulum_bringup.launch.py rviz:=True
 ```
-![pendulum_rviz](docs/images/pendulum_rviz_disturbance.gif)
 
-Note the force is applied continuously until a different disturbance force is sent again. We may change this in the future.
+If everything went well you should see the inverted pendulum being controlled in rviz:
 
-#### Managed nodes
-
-The main nodes used in the demo `/pendulum_controller` and `/pendulum_driver` are [managed nodes](https://design.ros2.org/articles/node_lifecycle.html). That is, they inherit from a Lifecycle node and it is posible to control the node state.
-
-![lifecycle_rt](docs/images/node_lifecycle_rt.png)
-
-The image above was taken from [Jackie Kay's Roscon keynote in 2015](https://roscon.ros.org/2015/presentations/RealtimeROS2.pdf).
+![pendulum_rviz](docs/images/pendulum_rviz.gif)
 
-All the configurations and memory allocation must be done in the `onConfigure` transition. In active state all the computations should be real-time compliant. This may be not completely true for the moment but it's that's the goal.
 
-The package `pendulum_manager` was created in order to control the state of the nodes easier. This package is in a very early stage, the idea is this package to become a rqt plugin with a control panel.
+## How to configure real-time settings<a name="rtdemo"></a>
 
-Just for fun you can try to deactivate the controller node while the simulation is active to see the pendulum falling down.
+Instructions to configure the demo real-time settings can be found [here](docs/real_time_tutorial.md).
 
-#### Realtime demo <a name="rtdemo"></a>
+## How to measure real-time performance metrics<a name="rtmetrics"></a>
 
-A detailed tutorial for real-time testing can be found [here](docs/real_time_tutorial.md).
+TODO
 
-#### How to contribute
+## How to contribute
 
-Make a fork using github, and make your changes. This project uses the same guidelines as all the officials ROS2 packages, make sure that your code is compliant with cppcheck, uncrustify...
+Make a fork using github, and make your changes. This project uses the same guidelines as all the
+ officials ROS2 packages, make sure that your code is compliant with cppcheck, uncrustify...
 After this, submit a PR and we will review as soon as possible.
 
-#### Issues and feature request
+## Issues and feature request
 
-Please, use the [templates](https://github.com/ros2-realtime-demo/pendulum/issues/new/choose) and make sure that you labeled them properly. Also, consider to open a PR to fix the issue or to implement a feature.
+Please, use the [templates](https://github.com/ros2-realtime-demo/pendulum/issues/new/choose) and
+ make sure that you labeled them properly. Also, consider to open a PR to fix the issue or to
+  implement a feature.

docs/design.md

@@ -2,36 +2,35 @@
 
 ### Purpose
 
-This is a rework of the existing pendulum demo in ros2/demos. In this project we want to create a new version that updates some the new features of ROS 2 such as compositions, lifecycle, new QoS and real-time support.
+This is a rework of the existing pendulum demo in ros2/demos. The aim of this project is to
+ create a complete use case to show ROS 2 real-time capabilities. The goal is not measure ROS 2
+  real-time performance but to show how ROS 2 could be used for a real-time application. Ideally
+   this project could help ROS developers to understand how to program a ROS 2 application in C
+   ++, which ROS 2 features could be used, how to configure the process and how to instrument
+    the application to verify the real-time capabilities.    
+
+### Managed nodes
 
-The project is structured in a modular way so each node component can be tested and extended individually. We also decouple the actual controller implementation of the controller node so it is easy to implement new kind of controllers. This is the same approach that `ros_control` uses. In the same way we decouple the actual driver implementation so it is possible to simulate the robot or to communicate with a real one.  
+The main nodes used in the demo `/pendulum_controller` and `/pendulum_driver` are 
+[managed nodes](https://design.ros2.org/articles/node_lifecycle.html). They inherit from a 
+Lifecycle node and it is possible to control the node state. All the configurations and dynamic 
+memory allocation must be done before entering to the Active tate, for example in the
+ `onConfigure` transition.
 
-![rosgraph](images/rosgraph.png)
+![lifecycle_rt](images/node_lifecycle_rt.png)
 
-### Real-time
-
-One of the main goals of this demo is to show a representative example of a real-time capable ROS 2 based application. In order to demonstrate these capabilities we can start with the following points:
-
-* Show no memory page faults when nodes are active. Make use of lifecycle activate/deactivate to show the stats.
-* Add a dynamic analyzer to measure additional statistics (latencies, context switches, etc). For example the [ROS 2 Bosch lttng](https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing) package.
-* Think about using experimental executors more suitable for real-time (waitset, polling).
-* Add liveliness QoS and other real-time friendly DDS QoS.
-* Explore the use of callback groups.
-
-### Pendulum control
-
-Another goal of the demo is to provide a simple use case to develop and test with different controllers. For this reason, it would be interesing to add more controllers to the existing projects. For example a PID controller or a [LQG controller](https://en.wikipedia.org/wiki/Linear%E2%80%93quadratic%E2%80%93Gaussian_control) by adding a [kalman filter](https://en.wikipedia.org/wiki/Kalman_filter). It would interesting also to add new capabilities such as a [swing-up](https://youtu.be/hQK_3C6S4Ak?t=285) capable controller.
+The image above was taken from [Jackie Kay's Roscon keynote in 2015](https://roscon.ros.org/2015/presentations/RealtimeROS2.pdf).
 
 ### Component overview
 
-The first version of the demo contains the following components:
-
-* `PendulumControllerNode`: Class derived from `LifecycleNode` that implements the ROS 2 interface for the pendulum controller.
-* `PendulumController`: Abstract class used by `PendulumControllerNode` to call the specific controller implementation.
-* `FullStateFeedbackController`: A controller implementation derived from `Controller` based on a [full state feedback controller](https://en.wikipedia.org/wiki/Full_state_feedback).
-* `PendulumDriverNode`: Class derived from `LifecycleNode` that implements the ROS 2 interface for the real or simulated pendulum.
-* `PendulumDriverInterface`: Abstract class used by `PendulumDriverNode` to call the specific driver base implementation.
-* `PendulumSimulation`: A class derived from PendulumDriverInterface that implements a simulation of a cart based pendulum.
-* `pendulum_demo`: Program that creates and executor, adds a `PendulumControllerNode` and a `PendulumDriverNode` nodes with a `FullStateFeedbackController` and a `PendulumSimulation` instances and spins all the nodes. It provides also options to test different publishing periods, parameters and real-time settings.
-* `pendulum_manager` An executable to manage the lifecycle node transitions. In the future this would be a rqt plugin with a control panel showing the status of the nodes and with buttons to transit the nodes between states.
-* `pendulum_teleop` An executable to send setpoints to the controller using a joystick or a keyboard. (Not implemented yet).
+* `PendulumControllerNode`: Class derived from `LifecycleNode` that implements the ROS 2 interface 
+for the pendulum controller.
+* `PendulumController`: A controller implementation based on a
+ [full state feedback controller](https://en.wikipedia.org/wiki/Full_state_feedback).
+* `PendulumDriverNode`: Class derived from `LifecycleNode` that implements the ROS 2 interface for
+ a simulated pendulum.
+* `PendulumDriver`: A class which implements a simulation of a cart-pole based pendulum.
+* `pendulum_demo`: The main program which configures the process settings, creates and executor
+, adds a `PendulumControllerNode` and a `PendulumDriverNode`  using manual composition and spins
+ all the nodes.
+

docs/installation.md

@@ -0,0 +1,98 @@
+# Install instructions
+
+## ADE based installation
+
+TODO: describe how the ADE image is structured and which features already includes (ROS 2traces
+ enabled, real-time limits configured, etc)  
+
+Instructions taken from: https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/installation.html
+
+[ADE](https://ade-cli.readthedocs.io/en/latest/index.html) is a modular Docker-based tool to ensure that all developers in a project have a common,
+ consistent development environment.
+
+Follow the install instructions, which are reproduced here for convenience:
+
+1. Verify that the requirements listed
+ [here](https://ade-cli.readthedocs.io/en/latest/install.html#requirements) are fulfilled
+2. Download the statically-linked binary from the
+ [Releases](https://gitlab.com/ApexAI/ade-cli/-/releases) page of the ade-cli project
+3. Name the binary ade and install it in your PATH (on Ubuntu, `/usr/local/bin` is recommended)
+4. Make the binary executable: `chmod +x ade`
+5. Check that it is installed:
+
+```bash
+$ which ade
+/path/to/ade
+$ ade --version
+<version>
+```
+
+### Setup ADE home and project checkout
+ADE needs a directory on the host machine which is mounted as the user's home directory within
+ the container. The directory is populated with dotfiles, and must be different than the
+  user's home directory outside of the container. In the event ADE is used for multiple,
+   projects it is recommended to use dedicated adehome directories for each project.
+
+ADE looks for a directory containing a file named `.adehome` starting with the current
+ working directory and continuing with the parent directories to identify the ADE home
+  directory to be mounted.
+
+```bash
+$ mkdir adehome
+$ cd adehome
+$ touch .adehome
+```
+
+For ADE to function, it must be properly configured. The pendulum demo provides an `.aderc` file
+ which is expected to exist in the current working directory, or in any parent directory.
+
+```
+$ cd adehome
+$ git clone [email protected]:ros2-realtime-demo/pendulum.git
+```
+
+How to build
+```
+$ ade start --update --enter
+ade$ source /opt/ros/foxy/setup.bash
+ade$ cd pendulum
+ade$ colcon build
+ade$ colcon test
+ade$ colcon test-result
+```
+
+## Installation from source
+
+TODO
+
+## Cross compile
+
+In order to cross compile the project to use it on aarch64 CPU architecture, here the needed steps.
+
+### Prerequisites
+
+* [Docker](https://docs.docker.com/engine/install/ubuntu/), add current user to docker group to execute it as non-root user.
+* Python >= 3.5
+
+```bash
+sudo apt-get install qemu-user-static
+pip3 install ros_cross_compile
+```
+
+For more information, checkout: https://github.com/ros-tooling/cross_compile#installation
+
+```bash
+mkdir -p ~/xcompile_ws/src
+cd ~/xcompile_ws/src
+export ROS_DISTRO=foxy
+git clone https://github.com/ros2-realtime-demo/pendulum -b "${ROS_DISTRO}"
+cd ~
+ros_cross_compile xcompile_ws/ --arch aarch64 --os ubuntu --rosdistro  "${ROS_DISTRO}"
+```
+
+Folder that contains the project compiled is `~/xcompile_ws/install_aarch64`, the folder need to be copied to target board.
+
+
+## Raspberry PI image
+
+TODO