Skip to content

Commit

Permalink
Merge pull request IMRCLab#83 from IMRCLab/doc-improvements
Browse files Browse the repository at this point in the history 
updated docs
  • Loading branch information
@knmcguire
knmcguire committed Oct 5, 2022
2 parents a52cfca + 0ba7c07 commit 07c6d71
Show file tree
Hide file tree
Showing 3 changed files with 178 additions and 72 deletions.
14 changes: 7 additions & 7 deletions docs2/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@ Installation

Crazyswarm2 runs on **Ubuntu Linux** in one of the following configurations:

====== ====== ========
Ubuntu Python ROS2
------ ------ --------
20.04 3.7 Galactic
====== ====== ========
====== ======== ========
Ubuntu Python ROS2
------ -------- --------
20.04 3.7, 3.8 Galactic
====== ======== ========

.. warning::
The `Windows Subsystem for Linux (WSL) <https://docs.microsoft.com/en-us/windows/wsl/about>`_ is not supported.
You must install Ubuntu either directly on the computer (recommended) or in a VM.
The `Windows Subsystem for Linux (WSL) <https://docs.microsoft.com/en-us/windows/wsl/about>`_ is experimentally supported but you'll have to use `usbipd-win <https://github.com/dorssel/usbipd-win/>`_.
This program will link the crazyradio directly with WS, but beware of bugs. Check out their `WSL connect guide <https://github.com/dorssel/usbipd-win/wiki/WSL-support/>`_.

.. warning::
Avoid using a virtual machine if possible: they add additional latency and might cause issues with the visualization tools.
Expand Down
73 changes: 72 additions & 1 deletion docs2/tutorials.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,77 @@ ROS2 Tutorials

This page shows tutorials that connects the Crazyflie through Crazyswarm2 to with external packages like RVIZ2, teleop_twist_keyboard, SLAM toolbox and NAV2 bringup. Have fun!


Teleoperation keyboard
----------------------

We have an example of the telop_twist_keyboard package working together with the crazyflie

First make sure that the crazyflies.yaml has the right URI and if you are using the `Flow deck <https://www.bitcraze.io/products/flow-deck-v2/>`_ or `any other position system available <https://www.bitcraze.io/documentation/system/positioning//>`_ to the crazyflie.
set the controller to 1 (PID)

Then, run the following launch file to start up the crazyflie server (CFlib):

.. code-block:: bash
ros2 launch crazyflie_examples keyboard_velmux_launch.py
in another terminal run:

.. code-block:: bash
ros2 run teleop_twist_keyboard telop_twist_keyboard
Use 't' to take off, and 'b' to land. For the rest, use the instructions of the telop package.


Vizualization with RVIZ2
------------------------


Make sure your crazyflie knows it's position, either by a `flow deck <https://www.bitcraze.io/products/flow-deck-v2/>`_ or `any other position system available <https://www.bitcraze.io/documentation/system/positioning//>`_ to the crazyflie.

In crazyflie.yaml, make sure that this following is added or uncommented

.. code-block:: bash
all:
...
firmware_logging:
enabled: true
default_topics:
pose:
frequency: 10 # Hz
In the first terminal, launch the server (CFlib backend only for now)

.. code-block:: bash
ros2 launch crazyflie launch.py backend:=cflib
In the second terminal

.. code-block:: bash
rviz2
Then set 'fixed frame' to 'world' and add the TF plugin. Then in 'TF', check the 'show names' checkbox.
The crazyflie names should appear with their estimated position.

This RVIZ2 visualization can be done for the default topics:

* 'pose': '/cf1/pose/' Transforms and Pose
* 'odom': '/cf1/odom/' Odometry
* 'scan': '/cf1/scan' Scan

Here you can see an example of 5 crazyflies with the Pose default topic enabled, while taking off and landing

.. raw:: html

<div style="position: relative; padding-bottom: 56.25%; margin-bottom: 20pt; height: 0; overflow: hidden; max-width: 100%; height: auto;">
<iframe src="https://www.youtube.com/embed/w99hLldcSp4" frameborder="0" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
</div>

Mapping with the SLAM toolbox
-----------------------------

Expand Down Expand Up @@ -56,6 +127,7 @@ Also make sure that that the standard controller is set to 1 (PID) for the flowd
estimator: 2 # 1: complementary, 2: kalman
controller: 1 # 1: PID, 2: mellinger
Connecting with the Crazyflie
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -106,7 +178,6 @@ Here is an explanation of the nodes:
* The second node is a velocity command handler, which takes an incoming twist message, makes the Crazyflie take off to a fixed height and enables velocity control of external packages (you'll see why soon enough).
* The third node is the slam toolbox node. You noted that we gave it some different parameters, where we upped the speed of the map generation, descreased the resolution and turn of ray matching as mentioned in the warning above.


Turn on your crazyflie and put it in the middle of the room you would like to map. Make sure to mark the starting position for later.

Now startup the crazyflie server with the following example launch file, after sourcing the setup.bash ofcourse:
Expand Down
163 changes: 99 additions & 64 deletions docs2/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,101 @@ Usage
. install/local_setup.bash
Configuration
-------------

All configuration files are in crazyswarm2/config.
All configuration files are in crazyflie/config.

* crazyflies.yaml : Setting up everything related to the crazyflie connection server
* motion_capture.yaml : configs for the motion capture package
* teleop\_\*.yaml : configs for remote controls

crazyflies.yaml
~~~~~~~~~~~~~~~

Each crazyflie should have an unique URI which can `be changed in Bitcraze's CFclient <https://www.bitcraze.io/documentation/repository/crazyflie-clients-python/master/userguides/userguide_client/#firmware-configuration/>`_.
They can also be enabled in case you don't want the server to connect with it.

.. code-block:: bash
robots:
cf231:
enabled: true
uri: radio:https://0/80/2M/E7E7E7E7E7
initial_position: [0, 0, 0]
type: cf21 # see robot_types
cf5:
enabled: false
uri: radio:https://0/80/2M/E7E7E7E705
initial_position: [0, -0.5, 0]
type: cf21 # see robot_types
The yaml file also contains different robot_types, to indicate differences between each crazyflie :

.. code-block:: bash
robot_types:
cf21:
motion_capture:
enabled: true
# only if enabled; see motion_capture.yaml
marker: default_single_marker
dynamics: default
big_quad: false
battery:
voltage_warning: 3.8 # V
voltage_critical: 3.7 # V
cf21_mocap_deck:
motion_capture:
enabled: true
# only if enabled; see motion_capture.yaml
marker: mocap_deck
dynamics: default
big_quad: false
battery:
voltage_warning: 3.8 # V
voltage_critical: 3.7 # V
The yaml file also contain an 'all' field, in case you have parameters or logging that you want enabled for all the connected crazyflies.


.. code-block:: bash
all:
firmware_logging:
enabled: false
default_topics:
pose:
frequency: 10 # Hz
#custom_topics:
# topic_name1:
# frequency: 10 # Hz
# vars: ["stateEstimateZ.x", "stateEstimateZ.y", "stateEstimateZ.z", "pm.vbat"]
# topic_name2:
# frequency: 1 # Hz
# vars: ["stabilizer.roll", "stabilizer.pitch", "stabilizer.yaw"]
firmware_params:
commander:
enHighLevel: 1
stabilizer:
estimator: 2 # 1: complementary, 2: kalman
controller: 2 # 1: PID, 2: mellinger
The above also contains an example of the firmware_logging field, where default topics can be enabled or custom topics based on the `existing log toc of the crazyflie <https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/api/logs//>`_.
Moreover, it also contains the firmware_params field, where parameters can be set at startup.
Also see the `parameter list of the crazyflie <https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/api/params//>`_ for that.


Mind that you can also place the firmware_params and firmware_logging fields per crazyflie in 'robots' or the 'robot_types' field.
The server node will upon initialization, first look at the params/logs from the individual crazyflie's settings, then the robot_types, and then anything in 'all' which has lowest priority.


.. warning::
The logging is currently only supported in the CFLIB backend of the server, while Parameters is available in both the cpp backend

Simulation
----------
Expand All @@ -28,24 +119,27 @@ Example:
ros2 run crazyflie_examples hello_world --sim
Physical Experiments
--------------------

ROS2 terminal
~~~~~~~~~~~~~

The following shows an simple take off and land example without any launch files or yaml files

.. code-block:: bash
ros2 run crazyflie reboot --uri radio:https://0/80/2M/E7E7E7E706 --mode sysoff
ros2 param set crazyflie cf1/params/commander/enHighLevel 1
ros2 param set crazyflie cf1/params/stabilizer/estimator 2
ros2 service call cf1/takeoff crazyflie_interfaces/srv/Takeoff "{height: 0.5, duration: {sec: 2}}"
ros2 service call cf1/land crazyflie_interfaces/srv/Land "{height: 0.0, duration: {sec: 2}}"
Enabling Logblocks
~~~~~~~~~~~~~~~~~~
Enabling Logblocks in runtime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Above we explained how to enable log blocks at startup, but what if you would like to enable or disable logging blocks in runtime?
This section will show how to do that by using services

In one terminal run

Expand Down Expand Up @@ -80,27 +174,6 @@ We currently assume an XBox controller (the button mapping can be changed in tel
ros2 launch crazyflie launch.py
Teleoperation keyboard
~~~~~~~~~~~~~~~~~~~~~~
We have an example of the telop_twist_keyboard package working together with the crazyflie
First make sure that the crazyflies.yaml has the right URI and if you are using the flowdeck,
set the controller to 1 (PID)
Then, run the following launch file to start up the crazyflie server (CFlib):
.. code-block:: bash
ros2 launch crazyflie_examples keyboard_velmux_launch.py
in another terminal run:
.. code-block:: bash
ros2 run teleop_twist_keyboard telop_twist_keyboard
Use 't' to take off, and 'b' to land. For the rest, use the instructions of the telop package.
Python scripts
~~~~~~~~~~~~~~
Expand All @@ -116,44 +189,6 @@ In the second terminal
ros2 run crazyflie_examples hello_world
Vizualization
-------------
RVIZ2 default topics
~~~~~~~~~~~~~~~~~~~~
Make sure your crazyflie knows it's position, either by a flowdeck or another global positioning system
In crazyflie.yaml, make sure that this following is added or uncommented
.. code-block:: bash
all:
...
firmware_logging:
enabled: true
default_topics:
pose:
frequency: 10 # Hz
In the first terminal, launch the server (CFlib backend only for now)
.. code-block:: bash
ros2 launch crazyflie launch.py backend:=cflib
In the second terminal
.. code-block:: bash
rviz2
Then set 'fixed frame' to 'world' and add the TF plugin. Then in 'TF', check the 'show names' checkbox.
The crazyflie names should appear with their estimated position.
This RVIZ2 visualization can be done for the default topics:
* 'pose': '/cf1/pose/' Transforms and Pose
* 'odom': '/cf1/odom/' Odometry
* 'scan': '/cf1/scan' Scan

0 comments on commit 07c6d71

Please sign in to comment.