cognifly 0.0.2

Control the CogniFly open-source drone from python

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:

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:

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 (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:

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:

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:

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()