Merge pull request #44 from bitcraze/add-repo-docs

Add repo docs

README.md

@@ -2,123 +2,17 @@
 
 Hi! Welkom to the crazyflie simulation repo. This repo is still at the early stages and still in development so just ask if you are looking for anything in particular.
 
-Currently it contains low resolution meshes based on the design of the actual [crazyflie 2.1](https://www.bitcraze.io/products/crazyflie-2-1/) but heavily simplified to contain as little vertices as possible, so it can be used to simulate a lot of them!
+Currently it contains low resolution meshes based on the design of the actual [crazyflie 2.1](https://www.bitcraze.io/products/crazyflie-2-1/) but heavily simplified to contain as little vertices as possible, so it can be used to simulate a lot of them.
 
-## Content
 
-Currently contains:
-* Meshes
-    * Blender files
-    * STL files
-* [Webots](https://cyberbotics.com/) simulation files
-    * Currently with velocity control fixed height and firmware python bindings
-    * Camera and multiranger sensors
-* [Gazebo](https://gazebosim.org/)
-    * sdf files
-    * no control yet
+## Installation
 
-So the mesh files looks a bit like this:
+see the  [installation instructions](/docs/installing/) in the Github docs folder.
 
+## Official documentation
 
-<img src="/meshes/blender_files/cf2_render.png" width="400" />
+https://www.bitcraze.io/documentation/repository/crazyflie-simulation/main/
 
-And the webots simulation looks like this:
+## Contribute
 
-![webots](crazyflie_webots.gif)
-
-Near future plans:
-
-Wish list (?):
-* SITL and or HITL
-* Simple physics model
-* Deck models
-* Intergration with Crazyflie-lib
-* ?? (let us know in the issue tracker for any feature requests)
-
-# Webots
-
-Install webots from the [cyberbotics' website](https://cyberbotics.com/). We use version 2023a version.
-
-Then just run the following
-
-    webots webots/worlds/crazyflie_world.wbt
-
-## Change controller
-
-In webots, change controller to either `crazyflie_controller_c` or `crazyflie_controller_py` to try out a simple controller in different languages
-
-## Try wallfollowing
-
-Run the following world
-
-    webots webots/worlds/crazyflie_appartement.wbt
-
-Go to the `webots/controller/crazyflie_controller_py_wallfollowing/` and look into crazyflie_controller_py_wallfollowing.py.
-
-Make sure this line is pointing to the cflib's wallfollowing script (make sure to update the [crazyflie-lib-python repository](https://github.com/bitcraze/crazyflie-lib-python))
-
-    sys.path.append('../../../../../python/crazyflie-lib-python/examples/multiranger/wall_following')
-
-
-You can toggle wallfollowing with with the 'a' key on your keyboard.
-
-
-## Firmware python bindings
-As of this [Pull request in the Crazyflie firmware repo](https://github.com/bitcraze/crazyflie-firmware/pull/1021) it is possible to use the python bindings of the controllers of the actual crazyflie controller directly in webots.
-
-Go the crazyflie-firmware directory in a terminal and write:
-
-    make bindings_python
-
-Change the controller in the crazyflie robot model in webots to crazyflie_controller_py_firmware_pid, and adjust the following line to point to your crazyflie-firmware repo:
-
-    sys.path.append('../../../../../C/crazyflie-firmware')
-
-Press play with the simulator and use your keyboard to  control it
-
-## External socket control
-
-There is also an example that shows controlling the crazyflie with an socket connection.
-
-Change the controller to `crazyflie_controller_py_socket` and start the simulation. Then in a seperate terminal outside of the webots simulator run:
-
-    python3 webots/controllers/crazyflie_controller_py_socket/socket_control.py
-
-You can use the arrow keys and q e w s to control the drone in velocity mode.
-
-# Gazebo
-
-*Just mind that this model does not fly properly yet.*
-
-1- First install gazebo garden: https://ignitionrobotics.org/docs/garden/install
-
-2- Clone this repo:
-    git clone https://github.com/bitcraze/crazyflie_simulation.git
-
-3- Put this repo in your ~/.bashrc and source it in your terminal
-
-    export IGN_GAZEBO_RESOURCE_PATH="path/to/crazyflie-simulation/gazebo-ignition/"
-
-*Note that indeed this is still IGN_GAZEBO_RESOURCE_PATH, eventhough gazebo dropped the name IGN so this should be updated at one point*
-
-4- Try out the crazyflie world with:
-    gz sim crazyflie_world.sdf
-
-5- Spin motors
-
-    gz topic -t /crazyflie/gazebo/command/motor_speed --msgtype ignition.msgs.Actuators -p 'velocity:[250,250,250,250]'
-
-
-## Measurements Crazyflie Assembly
-
-The location of the parts
-
-* Propeller origin from center (0.031, 0.031, 0.022) m
-    * Mirrored in the x and y axis
-* Motor mount + motor mounts (0.031, 0.031, 0.014) m
-    * Mirrored in the x and y axis
-* Body origin height from center ( 0, 0, 0.015) m
-* Battery holder height ( 0, 0,0.025) m
-* Battery height (0,0,0.02) m
-* Pin headers (0, 0.011, 0.014) m
-    * Mirrored in the y axis
+Go to the [contribute page](https://www.bitcraze.io/development/contribute/) on our website to learn more.

docs/functional_areas/controllers.md

@@ -0,0 +1,36 @@
+---
+title: Shared Controllers
+page_id: controllers
+sort_order: 3
+---
+
+This page explains about the shared control files of the different simulators to fly a simulated Crazyflie.
+
+## Simple PID controller
+
+A very simple height fixed and horizontal velocity based was build for this simulator that is written in both c and python. These can be found in the folder `/shared_controllers` and the idea is that they can be used interchangably between de Gazebo and Webots simulation. They are therefore meant to be stand alone.
+
+In webots, change controller to either `crazyflie_controller_c` or `crazyflie_controller_py` to try out a simple controller in different languages.
+
+## Firmware python bindings
+As of this [Pull request in the Crazyflie firmware repo](https://github.com/bitcraze/crazyflie-firmware/pull/1021) it is possible to use the python bindings of the controllers of the actual crazyflie controller directly in webots.
+
+> The python bindings only works in Webots for now.
+
+[Clone the crazyflie-firmware](https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/building-and-flashing/build/#cloning) in another folder, then make the python bindings [via these instructions](https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/building-and-flashing/build/#build-python-bindings).
+
+Change the controller in the crazyflie robot model in webots to crazyflie_controller_py_firmware_pid, and adjust the following line to point to your crazyflie-firmware repo:
+
+    sys.path.append('../../../../../C/crazyflie-firmware')
+
+Press play with the simulator and use your keyboard to  control it.
+
+## External socket control
+
+There is also an example that shows controlling the crazyflie with an socket connection.
+
+Change the controller to `crazyflie_controller_py_socket` and start the simulation. Then in a seperate terminal outside of the webots simulator run:
+
+    python3 webots/controllers/crazyflie_controller_py_socket/socket_control.py
+
+You can use the arrow keys and q e w s to control the drone in velocity mode.

docs/functional_areas/index.md

@@ -0,0 +1,8 @@
+---
+title: Functional Areas
+page_id: functional_areas_index
+sort_order: 3
+---
+
+{% sub_page_menu %}
+

docs/functional_areas/meshes.md

@@ -0,0 +1,33 @@
+---
+title: Meshes
+page_id: meshes
+sort_order: 1
+---
+
+The model of the Crazyflie has been made in Blender 3.0 in such a way that has as little polygons as possible.
+
+These files can be find in the `meshes/` folder:
+*  `/meshes/blender_flies/` *.blend Blender 3.0 source files
+*  `/meshes/collada_files/` *.dea Collada mesh exports of assembly with seperate props
+*  `/meshes/stl_files/` *.stl STL mesh exports of the individual partts, the CF2 body and the full assembly
+* `/meshes/textures/` Any additional texture files necessary for simulation.
+
+So the mesh files assembled looks a bit like this as a render in blender:
+
+![crazyflie render](/docs/images/cf2_render.png)
+
+
+## Measurements Crazyflie Assembly
+
+If you'd like to use the mesh files to assemble a full crazyflie, these are the location the individual parts in meters:
+
+* Propeller origin from center (0.031, 0.031, 0.022) m
+    * Mirrored in the x and y axis
+* Motor mount + motor mounts (0.031, 0.031, 0.014) m
+    * Mirrored in the x and y axis
+* Body origin height from center ( 0, 0, 0.015) m
+* Battery holder height ( 0, 0,0.025) m
+* Battery height (0,0,0.02) m
+* Pin headers (0, 0.011, 0.014) m
+    * Mirrored in the y axis
+

docs/functional_areas/simulators.md

@@ -0,0 +1,44 @@
+---
+title: Simulators
+page_id: simulators
+sort_order: 2
+---
+
+The folder `/simulator_files/`contain files that enables the simulators to fly a crazyflie in a particular simulator.
+
+## Webots
+
+In the folder `/simulator_files/webots` there are the following folders:
+
+* `/protos/`
+* `/worlds/` 
+* `/controllers/` 
+
+See each section for the explanation
+
+### protos
+
+`/protos/`This contains the source file of the [PROTO](https://cyberbotics.com/doc/reference/proto) of the crazyflie in Webots. A PROTO node (fileformat is *.proto) is a description framework for objects in that simulator. This contains the Crazyflie basics, like propperor actuation and IMU, as well as a ground truth position, camera and multiranger.
+
+### worlds
+`/worlds/` This contains world files in the format *.wbt and it an file that describes the webots world with all objects in it with certain initalization variables for the physics. 
+
+* `crazyflie_world.wbt` only contains a floor with one Crazyflie. 
+* `crazyflie_apartement.jpg` contains a Crazyflie initialized in an apartement with interactable walls and objects. 
+
+### controllers
+
+`/controllers/` contain all the controller files of the webots simulator for the Crazyflie, which acts likes wrappers around the files of `/controllers_shared/`, such that only webots specific functions exist in that wrapper.
+
+  * crazyflie_controller_c: wraps around `/controllers_shared/c_based` with simple keybased velocity reference input.
+  * crazyflie_controller_py: wraps around `/controllers_shared/python_based` with simple keybased velocity reference input.
+  * crazyflie_controller_py_firmware_pid: wraps around crazyflie-firmware pythonbindings. Check out the [controller](/docs/functional_areas/controllers.md) page.
+  * crazyflie_controller_py: wraps around `/controllers_shared/python_based` with an wall following state machine giving the reference velocity based on multiranger data.
+
+## Gazebo
+
+This folder contains crazyflie controllers, source and world files for Gazebo (not gazebo classic). This simulator is still underdeveloped so the controllers can only rotate the propellers for now. 
+
+* `crazyflie` This folder contains the .sdf file that describes the crazyflie. This relies on the collada files in `\meshes`.
+* `worlds` This contains only an empty world with a floor and a Crazyflie model.
+* `controllers` This contains the source files and cmake file for the Crazyflie to rotate the propellers based on an ign transport message.

docs/index.md

@@ -0,0 +1,8 @@
+---
+title: Home
+page_id: home
+---
+
+This repository contains several simulation options for the Crazyflie. 
+
+The original repository for this documentation is [https://github.com/bitcraze/crazyflie-simulation](https://github.com/bitcraze/crazyflie-simulation).

docs/installing/index.md

@@ -0,0 +1,9 @@
+---
+title: Installation
+page_id: installation_index
+sort_order: 1
+---
+
+This section contains on how to install the simulators
+
+{% sub_page_menu %}

docs/installing/install_gazebo.md

@@ -0,0 +1,11 @@
+---
+title: Installation Instructions Gazebo
+page_id: install_gazebo
+sort_order: 2
+---
+
+> The gazebo model is still work in progress. 
+
+Go to the [Gazebo installation instructions](https://gazebosim.org/docs/fortress/install). 
+
+Then go to the [gazebo spin motors example](/docs/user_guides/gazebo_spin_motors.md) to test it out.

docs/installing/install_webots.md

@@ -0,0 +1,11 @@
+---
+title: Installation Instructions Webots
+page_id: install_webots
+sort_order: 1
+---
+
+Go to the [cyberbotics website](https://cyberbotics.com/) and install the latest Webots simulator. Make sure to read their [installation instructions](https://cyberbotics.com/doc/guide/installing-webots).
+
+To verify, start webots by searching for 'Webots' in your program seeker or typing 'webots' in the terminal.
+
+If that all works fine, go and try out the [keyboard control example](/docs/user_guides/webots_keyboard_control.md)

docs/user_guides/gazebo_spin_motors.md

@@ -0,0 +1,25 @@
+---
+title: Gazebo Spin Motors
+page_id: gazebo_spin_motors
+sort_order: 3
+---
+
+*Just mind that this model does not fly properly yet.* 
+
+1- First install gazebo garden: https://ignitionrobotics.org/docs/garden/install
+
+2- Clone this repo: 
+    git clone https://github.com/bitcraze/crazyflie_simulation.git
+
+3- Put this repo in your ~/.bashrc and source it in your terminal
+
+    export IGN_GAZEBO_RESOURCE_PATH="path/to/crazyflie-simulation/gazebo-ignition/"
+
+*Note that indeed this is still IGN_GAZEBO_RESOURCE_PATH, eventhough gazebo dropped the name IGN so this should be updated at one point*
+
+4- Try out the crazyflie world with: 
+    gz sim crazyflie_world.sdf
+
+5- Spin motors 
+
+    gz topic -t /crazyflie/gazebo/command/motor_speed --msgtype ignition.msgs.Actuators -p 'velocity:[250,250,250,250]'

docs/user_guides/index.md

@@ -0,0 +1,7 @@
+---
+title: User Guides
+page_id: user_guides_index
+sort_order: 2
+---
+
+{% sub_page_menu %}

docs/user_guides/webots_keyboard_control.md

@@ -0,0 +1,22 @@
+---
+title: Webots keyboard control
+page_id: webots_keyboard_control
+sort_order: 1
+---
+
+>This example runs in Webots 2023b.
+
+Then just run the following
+
+    webots webots/worlds/crazyflie_world.wbt
+
+
+Or open up the world by the menu item `file`>`open world...`.
+
+
+You'll see a crazyflie take off. You can now click the 3d world to make sure it is active, and use the arrow keys on your keyboard to control it.
+The script in the console should provide further instructions. 
+
+
+If you want something more fun, try out the [webots wall following example](/docs/user_guides/webots_wall_following.md)
+

docs/user_guides/webots_wall_following.md

@@ -0,0 +1,25 @@
+---
+title: Webots Wall following
+page_id: webots_wall_following
+sort_order: 2
+---
+
+>This example runs in Webots 2023b.
+
+Run the following world
+
+    webots webots/worlds/crazyflie_appartement.wbt
+
+Or open up the world by the menu item `file`>`open world...`.
+
+
+Go to the `webots/controller/crazyflie_controller_py_wallfollowing/` and look into crazyflie_controller_py_wallfollowing.py. 
+
+Make sure this line is pointing to the cflib's wallfollowing script (make sure to update the [crazyflie-lib-python repository](https://github.com/bitcraze/crazyflie-lib-python))
+
+    sys.path.append('../../../../../python/crazyflie-lib-python/examples/multiranger/wall_following')
+
+
+You can toggle wallfollowing with with the 'a' key on your keyboard. 
+
+You will now see the Crazyflie following the wall in the apartement by means of the simulated multiranger.

module.json

@@ -0,0 +1,4 @@
+{
+    "version": "2.0",
+    "environmentReqs": {"build":["python3"]}
+  }