Merge pull request #360 from bitcraze/update-doc-2022.9

krichardsson · web-flow · commit cb1d830cb982 · 2022-09-07T15:54:16.000+02:00
Update doc 2022.9
diff --git a/docs/_data/menu.yml b/docs/_data/menu.yml
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,9 @@
+---
+title: Auto-generated API Documentation
+page_id: api_index
+sort_order: 5
+---
+
+This section contains auto-generated documentation of the classes and functions of the Crazyflie python library.
+
+{% sub_page_menu %}
diff --git a/docs/development/index.md b/docs/development/index.md
@@ -0,0 +1,9 @@
+---
+title: Development
+page_id: development_index
+sort_order: 4
+---
+
+In this section you will find information about development of the Crazyflie python library
+
+{% sub_page_menu %}
diff --git a/docs/development/wireshark.md b/docs/development/wireshark.md
@@ -1,6 +1,7 @@
 ---
 title: Debugging CRTP using Wireshark
 page_id: wireshark_debugging
+redirect:  /wireshark/wireshark/
 ---
 
 Wireshark is a free and open-source packet analyzer. It is used for network troubleshooting, analysis, software and communications protocol development, and education. It makes analyzing what is going on with packet based protocols easier.
diff --git a/docs/functional-areas/crazyradio_lib.md b/docs/functional-areas/crazyradio_lib.md
diff --git a/docs/functional-areas/index.md b/docs/functional-areas/index.md
@@ -0,0 +1,9 @@
+---
+title: Functional Areas
+page_id: functional_areas_index
+sort_order: 3
+---
+
+In this section you will find information about functional areas
+
+{% sub_page_menu %}
diff --git a/docs/installation/index.md b/docs/installation/index.md
@@ -0,0 +1,9 @@
+---
+title: installation
+page_id: installation_index
+sort_order: 1
+---
+
+In this section you will find installation instructions
+
+{% sub_page_menu %}
diff --git a/docs/installation/install.md b/docs/installation/install.md
@@ -42,15 +42,15 @@ you can skip this section.
 
 * To deactivate the virtualenv when you are done using it `deactivate`
 
-#### Install cflib dependencies
-Install dependencies required by the lib: `pip install -r requirements.txt`. If you are planning on developing on the lib you should also run: `pip install -r requirements-dev.txt`.
-
-To verify the installation, connect the crazyflie and run an example: `python3 examples/logging/basiclog.py`
-
-### Pre commit hooks
+### Pre commit hooks (Ubuntu)
 If you want some extra help with keeping to the mandated python coding style you can install hooks that verify your style at commit time. This is done by running:
 ```
+$ pip3 install pre-commit
+```
+go to crazyflie-lib-python root folder and run
+```
 $ pre-commit install
+$ pre-commit run --all-files
 ```
 This will run the lint checkers defined in `.pre-commit-config-yaml` on your proposed changes and alert you if you need to change anything.
 
diff --git a/docs/user-guides/index.md b/docs/user-guides/index.md
@@ -0,0 +1,9 @@
+---
+title: User guides
+page_id: user_guides_index
+sort_order: 2
+---
+
+In this section you will find user guides
+
+{% sub_page_menu %}
diff --git a/docs/user-guides/python_api.md b/docs/user-guides/python_api.md
@@ -34,13 +34,14 @@ a synchronous API by wrapping the asynchronous classes, see the
 All communication links are identified using an URI build up of the
 following: InterfaceType://InterfaceId/InterfaceChannel/InterfaceSpeed
 
-Currently only *radio* and *debug* interfaces are used but there\'s
-ideas for more like *udp*, *serial*, *usb*, etc\...Here are some
-examples:
+Currently we have *radio*, *serial*, *usb*, *debug*, *udp* interfaces are used. Here are some examples:
 
 -   _radio://0/10/2M : Radio interface, USB dongle number 0, radio channel 10 and radio
     speed 2 Mbit/s: radio://0/10/2M
 -   _debug://0/1_ : Debug interface, id 0, channel 1
+- _usb://0_ : USB cable to microusb port, id 0
+- _serial://ttyAMA0_ : Serial port, id ttyAMA0
+- _tcp://aideck-AABBCCDD.local:5000_ : TCP network connection, Name: aideck-AABBCCDD.local, port 5000
 
 ### Variables and logging
 
@@ -76,12 +77,14 @@ The library supports reading and writing parameters at run-time to the
 firmware. This is intended to be used for data that is not continuously
 being changed by the firmware, like setting regulation parameters and
 reading out if the power-on self-tests passed. Parameters should only
-change in the firmware when being set from the host or during start-up.
+change in the firmware when being set from the host (cfclient or a cflib script) or during start-up.
+
 The library doesn\'t continuously update the parameter values, this
 should only be done once after connecting. After each write to a
 parameter the firmware will send back the updated value and this will be
-forwarded to callbacks registered for reading this parameter. The
-parameters should be used in the following way:
+forwarded to callbacks registered for reading this parameter.
+
+The parameters should be used in the following way:
 
 -   Register parameter updated callbacks at any time in your application
 -   Connect to your Crazyflie (this will download the parameter TOC)
@@ -92,6 +95,8 @@ parameters should be used in the following way:
 -   For each write all the callbacks registered for this parameter will
     be called back
 
+There is an exception for experimental support to change the parameter from within [firmware's app layer](https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/userguides/app_layer/#internal-log-and-param-system). However do mind that this functionality is not according to the design of the parameters framework so that the host might not be updated correctly on the parameter change.
+
 ### Variable and parameter names
 
 All names of parameters and log variables use the same structure:
@@ -200,7 +205,7 @@ object:
 ``` python
     crazyflie = Crazyflie()
     crazyflie.connected.add_callback(crazyflie_connected)
-    crazyflie.open_link("radio://0/10/250K")
+    crazyflie.open_link("radio://0/10/2M")
 ```
 
 Then you can use the following to close the link again:
@@ -209,11 +214,13 @@ Then you can use the following to close the link again:
     crazyflie.close_link()
 ```
 
-## Sending control setpoints
+## Sending control setpoints with the commander framework
 
 The control setpoints are not implemented as parameters, instead they
 have a special API.
 
+### Attitude Setpoints
+
 ``` python
     def send_setpoint(self, roll, pitch, yawrate, thrust):
 ```
@@ -246,6 +253,16 @@ one command with thrust = 0 in order to unlock the command. This
 unlock procedure needs to be repeated if the watchdog describe above
 kicks-in.
 
+### Other commander setpoints sending
+
+If your Crazyflie has a positioning system (Loco, flowdeck, MoCap, Lighthouse), you can also send velocity or position setpoints, like for instance:
+
+```
+send_hover_setpoint(self, vx, vy, yawrate, zdistance)
+```
+
+Check out the [automated API documentation](/docs/api/cflib/crazyflie/commander.md) for the Crazyflie cflib's commander frame work to find out what other functions you can use.
+
 ## Parameters
 
 The parameter framework is used to read and set parameters. This
@@ -301,12 +318,12 @@ It is also possible to get the current value of a parameter (when connected) wit
     value = get_value(complete_name)
 ```
 
-Note 1: If you call `set_value()` and then directly call `get_value()` for a parameter, you might not read back the new
+>**Note 1** If you call `set_value()` and then directly call `get_value()` for a parameter, you might not read back the new
 value, but get the old one instead. The process is asynchronous and `get_value()` will not return the new value until
 the parameter value has propagated to the Crazyflie and back. Use the callback method if you need to be certain
 that you get the correct value after an update.
 
-Note 2: `get_value()` and `set_value()` can not be called from callbacks until the Crazyflie is fully connected.
+>**Note 2**: `get_value()` and `set_value()` can not be called from callbacks until the Crazyflie is fully connected.
 Most notably they can not be called from the `connected` callback as the parameter values have not been
 downloaded yet. Use the `fully_connected` callback to make sure the system is ready for parameter use. It is OK to
 call `get_value()` and `set_value()` from the `fully_connected` callback.
@@ -491,7 +508,7 @@ and SyncCrazyflie instances. To get the log values, iterate the instance.
 
 ### MotionCommander
 
-The MotionCommander is intended to simplify basic autonomous flight. The Crazyflie takes off
+The MotionCommander class is intended to simplify basic autonomous flight, where the motion control is done from the host computer. The Crazyflie takes off
 when entering the "with" section, and lands when exiting. It has functions for basic
 movements that are blocking until the motion is finished.
 
@@ -512,13 +529,13 @@ system, all positions are relative. It is mainly intended to be used with a Flow
 
 ### PositionHlCommander
 
-The PositionHlCommander is intended to simplify basic autonomous flight. The Crazyflie takes off
+The PositionHlCommander is intended to simplify basic autonomous flight, where all the high level commands exists inside the Crazyflie firmware. The Crazyflie takes off
 when entering the "with" section, and lands when exiting. It has functions for basic
 movements that are blocking until the motion is finished.
 
 The PositionHlCommander uses the high level commander in the Crazyflie and is
-based on a global coordinate system and absolute positoinins. It is inteneded
-to be used with a positioning system such as LPS, the lighthouse or a mocap system.
+based on a global coordinate system and absolute positions. It is intended
+to be used with a positioning system such as Loco, the lighthouse or a mocap system.
 
 ``` python
     with SyncCrazyflie(URI) as scf:
diff --git a/docs/user-guides/sbs_swarm_interface.md b/docs/user-guides/sbs_swarm_interface.md
@@ -3,14 +3,14 @@ title: "Step-by-Step: Swarm Interface"
 page_id: sbs_swarm_interface
 ---
 
-Here we will go through step-by-step how to interface with a swarm of crazyflies and make all the copters of the swarm hover and fly simultaneously in a square shape using the `Swarm()` class of the cflib.For this tutorial you will need a swarm (2 or more) of crazyflies with the latest firmware version installed and a global positioning system (Lighthouse,LPS or MoCap) that is able to provide data for the position estimation of the crazyflies. You can also use the Flowdeck but keep in mind that you should command relative movements of each Crazyflie and due to its nature it may lead to accumulative errors and unexpected behavior over time.
+Here we will go through step-by-step how to interface with a swarm of crazyflies and make all the copters of the swarm hover and fly simultaneously in a square shape using the `Swarm()` class of the cflib.For this tutorial you will need a swarm (2 or more) of crazyflies with the latest firmware version installed and a global positioning system (Lighthouse, Loco or MoCap) that is able to provide data for the position estimation of the crazyflies. You can also use the Flowdeck but keep in mind that you should command relative movements of each Crazyflie and due to its nature it may lead to accumulative errors and unexpected behavior over time.
 
 # Prerequisites
 
 We will assume that you already know this before you start with the tutorial:
 
 * Some basic experience with python
-* Followed the [crazyflie getting started guide](https://www.bitcraze.io/documentation/tutorials/getting-started-with-crazyflie-2-x/) 
+* Followed the [crazyflie getting started guide](https://www.bitcraze.io/documentation/tutorials/getting-started-with-crazyflie-2-x/)
 * Read the [high level commander](https://www.bitcraze.io/documentation/repository/crazyflie-lib-python/master/api/cflib/crazyflie/high_level_commander/), [swarm](https://www.bitcraze.io/documentation/repository/crazyflie-lib-python/master/api/cflib/crazyflie/swarm/) and [SyncCrazyflie](https://www.bitcraze.io/documentation/repository/crazyflie-lib-python/master/api/cflib/crazyflie/syncCrazyflie/) documentation .
 
 
@@ -109,7 +109,7 @@ if __name__ == '__main__':
 If everything is working properly, you can move to the next step .
 
 # Step 2: Security Before Flying
-Before executing any take off and flight maneuvers, the copters need to make sure that they have a precise enough position estimation. Otherwise it will take off anyway and it is very likely to crash. This is done through `reset_estimators()` by resetting the internal position estimator of each copter and waiting until the variance of the position estimation drops below a certain threshold. 
+Before executing any take off and flight maneuvers, the copters need to make sure that they have a precise enough position estimation. Otherwise it will take off anyway and it is very likely to crash. This is done through `reset_estimators()` by resetting the internal position estimator of each copter and waiting until the variance of the position estimation drops below a certain threshold.
 ```python
 with Swarm(uris, factory=factory) as swarm:
         swarm.parallel_safe(lightCheck)
@@ -118,7 +118,7 @@ with Swarm(uris, factory=factory) as swarm:
 
 # Step 3: Taking off and Landing Sequentially
 Now we are going to execute the fist take off and landing using the high level commander. The high level commander (more information [here](https://www.bitcraze.io/documentation/repository/crazyflie-firmware/master/functional-areas/sensor-to-control/commanders_setpoints/#high-level-commander)) is a class that handles all the high level commands like takeoff, landing, hover, go to position and others. The high level commander is usually preferred since it needs less communication and provides more autonomy on the Crazyflie. It is always on, but just in a lower priority so you just need to execute the take off and land commands through the below functions:
-```python  
+```python
 def take_off(scf):
     commander= scf.cf.high_level_commander
 
@@ -198,10 +198,10 @@ if __name__ == '__main__':
         print('Connected to  Crazyflies')
         swarm.parallel_safe(lightCheck)
         swarm.reset_estimators()
-        
+
         swarm.sequential(hover_sequence)
 ```
-After executing it you will see all copters performing the light check and then each copter take off , hover and land. This process is repeated for all copters in the swarm. 
+After executing it you will see all copters performing the light check and then each copter take off , hover and land. This process is repeated for all copters in the swarm.
 
 # Step 4: Taking off and Landing in Sync
 If you want to take off and land in sync, you can use the `parallel_safe()` method of the `Swarm` class.
@@ -215,7 +215,7 @@ Now the same action is happening but for all the copters in parallel.
 # Step 5: Performing a square shape flight
 To make the swarm fly in a square shape, we will use the go_to method of the high level commander. Each copter executes 4 relative movements to its current position covering a square shape.
 
-```python 
+```python
 def run_square_sequence(scf):
     box_size = 1
     flight_time = 2
@@ -237,7 +237,7 @@ def run_square_sequence(scf):
 Keep in mind that the `go_to()` command does not block the code so you have to wait as long as the flight time of each movement to continue to the next one.
 
 Since we want these maneuvers to be synchronized, the `parallel_safe()` method is chosen to execute the sequence, in similar fashion with the above steps. You can include the sequence execution in the main code of the swarm in the following way:
-    
+
 ```python
     swarm.parallel_safe(take_off)
     swarm.parallel_safe(run_square_sequence)
@@ -270,7 +270,7 @@ def land(scf):
 
 def run_square_sequence(scf: SyncCrazyflie):
     ...
-    
+
 uris = {
     'radio://0/20/2M/E7E7E7E701',
     'radio://0/20/2M/E7E7E7E702',
@@ -286,7 +286,7 @@ if __name__ == '__main__':
         print('Connected to  Crazyflies')
         swarm.parallel_safe(light_check)
         swarm.reset_estimators()
-        
+
         swarm.parallel_safe(take_off)
         swarm.parallel_safe(run_square_sequence)
         swarm.parallel_safe(land)
@@ -379,7 +379,7 @@ swarm.parallel_safe(run_sequence, args_dict=seq_args)
 ```
 
 The final script is going to look like this :
-    
+
 ```python
 import time
 
@@ -439,7 +439,7 @@ seq_args = ...
 
 def run_sequence(scf: syncCrazyflie.SyncCrazyflie, sequence):
     ...
-    
+
 
 if __name__ == '__main__':
     cflib.crtp.init_drivers()
@@ -449,7 +449,7 @@ if __name__ == '__main__':
         swarm.parallel_safe(light_check)
 
         swarm.reset_estimators()
-        
+
         swarm.parallel_safe(take_off)
         swarm.parallel_safe(run_square_sequence)
         swarm.parallel_safe(run_sequence, args_dict=seq_args)
diff --git a/requirements-dev.txt b/requirements-dev.txt
diff --git a/requirements.txt b/requirements.txt
