Metadata-Version: 2.1
Name: cognifly
Version: 0.0.2
Summary: Control the CogniFly open-source drone from python
Home-page: https://github.com/thecognifly/cognifly-python
Author: Yann Bouteiller
License: MIT
Download-URL: https://github.com/thecognifly/cognifly-python/archive/refs/tags/v0.0.2.tar.gz
Description: # cognifly-python
        Control the CogniFly open-source drone remotely from your python script.
        
        ## Prerequisite
        - The CogniFly drone must be set in "EST_POS" debug mode for this library to work.
        To ensure this, connect CogniFly to `inav-configurator`, go to the CLI tab, and execute the following:
        
        ```bash
        set debug_mode = EST_POS
        save
        ```
        
        - The `cognifly` library requires python >= 3.7 
        
        ## Installation
        
        Execute the following on both the CogniFly raspberry pi and the remote-controlling computer:
        
        ```bash
        pip3 install --upgrade pip
        pip3 install cognifly
        ```
        
        ## Precautions and usage
        
        In order to use the installed library, the `cognifly_controller.py` script must first be running on Cognifly.
        At the moment, this can be done by SSH-ing the drone, and executing the `cognifly-controller` command.
        
        ### Precautions and manual control
        
        In the future, we may set a service to launch this script automatically on the drone at startup, so that the user doesn't need to SSH the drone.
        HOWEVER, this will require us to build a GUI that you can use to remotely disarm the drone with a mouse click in the event of an emergency or unexpected behavior (these do happen!).
        
        For now, in the event of an emergency, the SSH window in which the `cognifly_controller.py` script is running must be focused and the `D` key must be pressed to disarm the drone.
        
        Note that other keys are available if you wish to manually control the drone with your keyboard through SSH:
        
        - `A`: arm
        - `D`: disarm
        - `T`: take off
        - `L`: land
        - `8`: forward
        - `5`: backward
        - `7`: left
        - `9`: right
        - `4`: left yaw
        - `6`: right yaw
        - `R`: reset the board and exit the script
        
        ### Remote control
        
        The remote control API is defined in [cognifly_remote.py](https://github.com/thecognifly/cognifly-python/blob/main/cognifly/cognifly_remote/cognifly_remote.py) (please read the docstrings for documentation).
        It is divided into a "pro" and a "school" API.
        
        #### Pro API
        
        The "pro" API is fairly simple and is what you should use for serious purpose.
        It enables the user to control Cognifly either by velocity or by position, in the world frame (X and Y relative to the starting point of the drone, Yaw relative to the starting orientation of the drone, and Z relative to the ground),
        or in the drone frame (X, Y and Yaw relative to the current position and orientation of the drone, and Z relative to the ground).
        
        A script example using the "pro" API for control is:
        
        ```python
        import time
        from cognifly import Cognifly
        
        # create a Cognifly object (resets the controller):
        cf = Cognifly(drone_hostname="my_drone_name.local")
        
        # arm the drone:
        cf.arm()
        time.sleep(1.0)
        
        # take off to default altitude :
        cf.takeoff_nonblocking()
        time.sleep(10.0)
        
        # go 0.2 m/s frontward for 1.0 second:
        cf.set_velocity_nonblocking(v_x=0.2, v_y=0.0, v_z=0.0, w=0.0, duration=1.0, drone_frame=True)
        time.sleep(2.0)
        
        # go rightward and upward while rotating for 1.0 second:
        cf.set_velocity_nonblocking(v_x=0.0, v_y=0.2, v_z=0.1, w=0.5, duration=1.0, drone_frame=True)
        time.sleep(2.0)
        
        # retrieve battery, pose, speed and health flags:
        telemetry = cf.get_telemetry()
        print(f"telemetry:\n{telemetry}")
        
        # go to (-0.5, -0.5, 0.5) and back to the initial yaw (0.0) at a max speed of 0.25 m/s, 0.5 rad/s:
        cf.set_position_nonblocking(x=-0.5, y=-0.5, z=0.5, yaw=0.0,
                                    max_velocity=0.25, max_yaw_rate=0.5, max_duration=10.0, relative=False)
        time.sleep(5.0)
        
        # go frontward for 0.5 m at 0.25 m/s, statying at an altitude of 0.5 m:
        cf.set_position_nonblocking(x=0.5, y=0.0, z=0.5, yaw=0.0,
                                    max_velocity=0.25, max_yaw_rate=0.5, max_duration=10.0, relative=True)
        time.sleep(5.0)
        
        # go back home:
        cf.set_position_nonblocking(x=0.0, y=0.0, z=0.5, yaw=0.0,
                                    max_velocity=0.25, max_yaw_rate=0.5, max_duration=10.0, relative=False)
        time.sleep(5.0)
        
        # land:
        cf.land_nonblocking()
        time.sleep(2.0)
        
        # disarm the drone
        cf.disarm()
        
        # reset the drone (reinitialize coordinate system):
        cf.reset()
        ```
        
        Note that this API is non-blocking, a new call will override the previous call
        (position and velocity are controlled by PIDs, so violent changes WILL make the drone unstable).
        
        #### School API
        
        The "school" API is an overlay of the "pro" API, built for students who need an easy and relatively safe API for class purpose.
        It is vastly inspired from the `easytello` library, from which it reproduces most of the interface, adapted to Cognifly.
        Contrary to the "pro" API, calls to the "school" API are blocking and return only when the command has been fully performed (or when it times out).
        It mostly consists of hidden calls to the position control "pro" API with an additional hidden callback through the `sleep_until_done` method (see the code to reproduce similar behavior with the "pro" API).
        
        Whereas the units of the "pro" API are meters and radians, the units of the "school" API are centimeters and degrees.
        
        Example using the "school" API for control:
        ```python
        from cognifly import Cognifly
        
        # create a Cognifly object (resets the controller):
        cf = Cognifly(drone_hostname="my_drone_name.local")
        
        # take off (resets the drone)
        cf.takeoff()
        
        # go forward for 50 cm:
        cf.forward(50)
        
        # turn clockwise by 90 degrees:
        cf.cw(90)
        
        # turn counter-clockwise by 45 degrees:
        cf.ccw(45)
        
        # other movements:
        cf.backward(20)
        cf.up(30)
        cf.down(20)
        cf.right(20)
        cf.left(10)
        
        # go to (0, 0, 0.5) (cm) with a yaw of 90° counter-clockwise compoared to the initial orientation
        cf.go(0, 0, 0.5, -90)
        
        # sequence of position targets (when 4 items, the last is yaw):
        cf.position_sequence([[0.2, 0.2, 0.5, 0.0],
                              [0.0, 0.1, 0.5],
                              [0.0, 0.0, 0.5]])
        
        # get telemetry:
        battery = cf.get_battery()
        height = cf.get_height()
        speed = cf.get_speed()
        x, y, z = cf.get_position()
        vx, vy, vz = cf.get_velocity()
        
        # land (disarms the drone):
        cf.land()
        ```
        
        #### Streaming
        
        Cognifly can stream from the raspberry pi camera.
        For this, first make sure that the camera is enabled in the raspberry pi, and that is works correctly.
        It is then possible to display the video or to retrieve frames for processing:
        
        ```python
        from cognifly import Cognifly
        
        # create a Cognifly object (resets the controller):
        cf = Cognifly(drone_hostname="my_drone_name.local")
        
        # take off:
        cf.takeoff()
        
        # display the stream:
        cf.stream()
        time.sleep(10.0)
        
        # stop the stream:
        cf.streamoff()
        time.sleep(5.0)
        
        # turn the stream on with no display:
        cf.streamon()
        
        # retrieve a frame for processing:
        numpy_image = cf.get_frame()
        
        # turn the stream off:
        cf.streamon()
        
        # land:
        cf.land()
        ```
Keywords: cognifly,drone,remote,control
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Framework :: Robot Framework :: Library
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Description-Content-Type: text/markdown
