diff --git a/docs/_data/menu.yml b/docs/_data/menu.yml deleted file mode 100644 index e882b43b6..000000000 --- a/docs/_data/menu.yml +++ /dev/null @@ -1,21 +0,0 @@ -- page_id: home -- title: Installation - subs: - - {page_id: install} - - {page_id: usd_permissions} -- title: User guides - subs: - - {page_id: python_api} - - {page_id: sbs_connect_log_param} - - {page_id: sbs_motion_commander} - - {page_id: sbs_swarm_interface} -- title: Functional areas - subs: - - {page_id: crazyradio_lib} -- title: Development - subs: - - {page_id: api_reference} - - {page_id: wireshark_debugging} - - {page_id: matlab} - - {page_id: eeprom} - - {page_id: uart_communication} diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 000000000..c934bc138 --- /dev/null +++ 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 new file mode 100644 index 000000000..c51c3de8c --- /dev/null +++ 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/wireshark/wireshark.md b/docs/development/wireshark.md similarity index 99% rename from docs/wireshark/wireshark.md rename to docs/development/wireshark.md index cf18c8ead..a4c64c2fe 100644 --- a/docs/wireshark/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/functonal-areas/crazyradio_lib.md b/docs/functional-areas/crazyradio_lib.md similarity index 100% rename from docs/functonal-areas/crazyradio_lib.md rename to docs/functional-areas/crazyradio_lib.md diff --git a/docs/functional-areas/index.md b/docs/functional-areas/index.md new file mode 100644 index 000000000..651eecc6d --- /dev/null +++ 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 new file mode 100644 index 000000000..b308ff986 --- /dev/null +++ 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 index 2303ec6c2..30933d905 100644 --- 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 new file mode 100644 index 000000000..643028801 --- /dev/null +++ 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 index 3c0e20374..bf5869877 100644 --- 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 index 2e09121a7..2afed5239 100644 --- 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 deleted file mode 100644 index 774c6f9fb..000000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,6 +0,0 @@ --e . - -coverage -mock -pre-commit -tox diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 8ba626a4e..000000000 --- a/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -pyusb>=1.0.0b2