Olympe API Reference Documentation¶

class olympe.Drone¶

Drone class

Use this class to send and/or receive SDK messages to a simulated or physical drone. This class can also be used to connect to a SkyController that is already paired with a drone. SkyController class is appropriate if you need to connect to an unknown drone.

Please refer to the Olympe user guide for more information.

Example:

import olympe
from olympe.messages.ardrone3.Piloting import TakeOff

drone = olympe.Drone("10.202.0.1")
drone.connect()
drone(TakeOff()).wait()
drone.disconnect()

__init__(ip_addr, name=None, dcport=44444, drone_type=0, is_skyctrl=None, video_buffer_queue_size=8, media_autoconnect=True)¶

Parameters

ip_addr (str) – the drone IP address
name (str) – (optional) the controller name (used by Olympe logs)
dcport (int) – drone control port (default to 44444)
drone_type (int) – (optional) the drone device type ID
is_sky_controller (bool) – True if Olympe needs to connect to a drone through a SkyController
video_buffer_queue_size – the video buffer pool size (defaults to 8)
media_autoconnect – autoconnect to the drone media API when the SDK connection is established (defaults to True)

connect()¶

Make all step to make the connection between the device and the pc

Return type: ReturnTuple

disconnect()¶

Disconnects current device (if any) Blocks until it is done or abandoned

Return type: ReturnTuple

connection_state()¶

Returns the state of the connection to the drone

Return type: ReturnTuple

start_video_streaming(resource_name='live', media_name='DefaultVideo')¶

Starts a video streaming session

Parameters

resource_name (str) –
video streaming resource. This parameter defaults to “live” for the live video stream from the drone front camera. Alternatively, resource_name can also point to a video file on the drone that is available for replay. In the later case, it takes the form “replay/RESOURCE_ID” where RESOURCE_ID can be obtained through the drone media REST API at http://10.202.0.1/api/v1/media/medias.

Examples:
- ”live”
- ”replay/100000010001.MP4”
- ”replay/200000020002.MP4”
- …
media_name (str) –
video stream media name. A video stream resource (e.g. “live” or “replay/..”) may provide multiple media tracks. Use the media_name parameter to select the source from the available media. This parameter defaults to “DefaultVideo”. If the requested media is unavailable, the default media will be selected instead without reporting any error.

Possible values:
- ”DefaultVideo”
- ”ParrotThermalVideo” (available with an ANAFI Thermal when replaying a thermal video).

See:

set_streaming_output_files()
set_streaming_callbacks()

Return type: ReturnTuple

stop_video_streaming()¶

Stops the live video stream from the drone front camera

Return type: ReturnTuple

set_streaming_output_files(h264_data_file=None, h264_meta_file=None, h264_info_file=None, raw_data_file=None, raw_meta_file=None, raw_info_file=None)¶

Records the video streams from the drone

xxx_meta_file: video stream metadata output files
xxx_data_file: video stream frames output files
xxx_info_file: video stream frames info files
h264_***_file: files associated to the H264 encoded video stream
raw_***_file: files associated to the decoded video stream

This function MUST NOT be called when the video streaming is active. Otherwise raises a RuntimeError exception. Setting a file parameter to None disables the recording for the related stream part.

set_streaming_callbacks(h264_cb=None, raw_cb=None, start_cb=None, end_cb=None, flush_h264_cb=None, flush_raw_cb=None)¶

Set the callback functions that will be called when a new video stream frame is available, when the video stream starts/ends or when the video buffer needs to get flushed.

Video frame callbacks

h264_cb is associated to the H264 encoded video stream
raw_cb is associated to the decoded video stream

Each video frame callback function takes an VideoFrame() parameter whose lifetime ends after the callback execution. If this video frame is passed to another thread, its internal reference count need to be incremented first by calling ref(). In this case, once the frame is no longer needed, its reference count needs to be decremented so that this video frame can be returned to memory pool.

Video flush callbacks

flush_h264_cb is associated to the H264 encoded video stream
flush_raw_cb is associated to the decoded video stream

Video flush callback functions are called when a video stream reclaim all its associated video buffer. Every frame that has been referenced

Start/End callbacks

The start_cb/end_cb callback functions are called when the video stream start/ends. They don’t accept any parameter.

The return value of all these callback functions are ignored. If a callback is not desired, leave the parameter to its default value or set it to None explicitly.

__call__(expectations, **kwds)¶

This method can be used to:

send command messages and waiting for their associated expectations

monitor spontaneous drone event messages

check the state of the drone

It asynchronously process arsdk command and event message and expectations.

Please refer to the Olympe User Guide for more information.

Parameters: expectations – An SDK message expectation expression
Return type: ArsdkExpectationBase

Please refer to the Olympe user guide for more information.

help(pattern='')¶

Returns the list of all commands available in olympe or the docstring of a specific command

type pattern

string

param pattern

a string that should be part of a command’s name

rtype

list or string

return

if no pattern is given, a list of all commands available

if the pattern is not exactly a command name, a list of commands containing the pattern

if pattern is the name of a command, the docstring of the command as a string (use print to display it)

get_state(message)¶

Returns the drone current state for the event message given in parameter

Parameters: message (ArsdkMessage) – an event message type
Returns: an ordered dictionary containing the arguments of the last received event message that matches the message ID provided in parameter

check_state(message, *args, **kwds)¶: Returns True if the drone state associated to the given message is already reached. Otherwise, returns False

query_state(query)¶: Query the drone current state return a dictionary of every drone state whose message name contains the query string :return: dictionary of drone state :param: query, the string to search for in the message received from the drone.

subscribe(*args, **kwds)¶: See: subscribe()

unsubscribe(subscriber)¶

Unsubscribe a previously registered subscriber

Parameters: subscriber (Subscriber) – the subscriber previously returned by subscribe()

start_piloting()¶

Start interface to send piloting commands

Return type: ReturnTuple

piloting_pcmd(roll, pitch, yaw, gaz, piloting_time)¶

Send command to the drone to move it. This function is a non-blocking function.

Parameters

roll (int) – roll consign for the drone (must be in [-100:100])
pitch (int) – pitch consign for the drone (must be in [-100:100])
yaw (int) – yaw consign for the drone (must be in [-100:100])
gaz (int) – gaz consign for the drone (must be in [-100:100])
piloting_time (float) – The time of the piloting command

Return type

ReturnTuple

stop_piloting()¶

Stop interface to send piloting commands

Return type: ReturnTuple

class olympe.EventListener¶

EventListener base class

This class implements the visitor pattern and is meant to be overridden to dispatch drone event messages to the correct class method.

To start/stop listening to event messages EventListener.subscribe() EventListener.unsubscribe() methods should be called. Alternatively, this class can be used as a context manager.

Example:

import olympe
from olympe.messages.ardrone3.Piloting import TakeOff, Landing, moveBy
from olympe.messages.ardrone3.PilotingState import (
    PositionChanged,
    AlertStateChanged,
    FlyingStateChanged,
    NavigateHomeStateChanged,
)

class FlightListener(olympe.EventListener):

    @olympe.listen_event(FlyingStateChanged() | AlertStateChanged() | NavigateHomeStateChanged())
    def onStateChanged(self, event, scheduler):
        print("{} = {}".format(event.message.name, event.args["state"]))

    @olympe.listen_event(PositionChanged())
    def onPositionChanged(self, event, scheduler):
        print(
            "latitude = {latitude} longitude = {longitude} altitude = {altitude}".format(
                **event.args
            )
        )


drone = olympe.Drone("10.202.0.1")
with FlightListener(drone):
    drone.connect()
    drone(
        FlyingStateChanged(state="hovering")
        | (TakeOff() & FlyingStateChanged(state="hovering"))
    ).wait()
    drone(moveBy(10, 0, 0, 0)).wait()
    drone(Landing()).wait()
    drone(FlyingStateChanged(state="landed")).wait()
    drone.disconnect()

__init__(*contexts, timeout=10)¶

Parameters

scheduler – an olympe.Drone or an olympe.expectations.Scheduler object for which this listener will subscribe to event messages.
timeout – the listener callbacks timeout in seconds

subscribe()¶: Start to listen to the scheduler event messages

unsubscribe()¶: Stop from listening scheduler event messages

class olympe.Pdraw¶

__init__(name=None, device_name=None, buffer_queue_size=8, legacy=False, pdraw_thread_loop=None)¶

Parameters

name (str) – (optional) pdraw client name (used by Olympe logs)
device_name (str) – (optional) the drone device name (used by Olympe logs)
buffer_queue_size (int) – (optional) video buffer queue size (defaults to 8)
legacy (bool) – Defaults to False, set this parameter to True for legacy drones (Bebop, Disco, …) streaming support

play(url=None, media_name='DefaultVideo', server_addr=None, resource_name='live')¶

Play a video

By default, open and play a live video streaming session available from rtsp://192.168.42.1/live where “192.168.42.1” is the default IP address of a physical (Anafi) drone. The default is equivalent to Pdraw.play(url=”rtsp://192.168.42.1/live”)

For a the live video streaming from a simulated drone, you have to specify the default simulated drone IP address (10.202.0.1) instead: Pdraw.play(url=”rtsp://10.202.0.1/live”).

The url parameter can also point to a local file example: Pdraw.play(url=”file://~/Videos/100000010001.MP4”).

Parameters

url (str) – rtsp or local file video URL
media_name (str) – name of the media/track (defaults to “DefaultVideo”). If the provided media name is not available from the requested video stream, the default media is selected instead.

pause()¶: Pause the currently playing video

close()¶: Close a playing or paused video stream session

set_output_files(h264_data_file, h264_meta_file, h264_info_file, raw_data_file, raw_meta_file, raw_info_file)¶

Records the video stream session to the disk

xxx_meta_file: video stream metadata output files
xxx_data_file: video stream frames output files
xxx_info_file: video stream frames info files
h264_***_file: files associated to the H264 encoded video stream
raw_***_file: files associated to the decoded video stream

This function MUST NOT be called when a video streaming session is active. Setting a file parameter to None disables the recording for the related stream part.

set_callbacks(h264_cb=None, raw_cb=None, start_cb=None, end_cb=None, flush_h264_cb=None, flush_raw_cb=None)¶

Set the callback functions that will be called when a new video stream frame is available, when the video stream starts/ends or when the video buffer needs to get flushed.

Video frame callbacks

h264_cb is associated to the H264 encoded video stream
raw_cb is associated to the decoded video stream

Video flush callbacks

flush_h264_cb is associated to the H264 encoded video stream
flush_raw_cb is associated to the decoded video stream

Video flush callback functions are called when a video stream reclaim all its associated video buffer. Every frame that has been referenced

Start/End callbacks

The start_cb/end_cb callback functions are called when the video stream start/ends. They don’t accept any parameter.

The return value of all these callback functions are ignored. If a callback is not desired, leave the parameter to its default value or set it to None explicitly.

get_session_metadata()¶: Returns a dictionary of video stream session metadata

state¶

Return the current Pdraw state

Return type: PdrawState

wait(state, timeout=None)¶

Wait for the provided Pdraw state

This function returns True when the requested state is reached or False if the timeout duration is reached.

If the requested state is already reached, this function returns True immediately.

This function may block indefinitely when called without a timeout value.

Parameters: timeout (float) – the timeout duration in seconds or None (the default)
Return type: bool

class olympe.Media¶

Drone Media API class

This class automatically connects to the drone web media interface (REST and websocket API) and synchronizes the drone media information in a background thread.

Media info:

media_info(),
resource_info(),
list_media(),
list_resources(),
indexing_state())

Media monitoring with the Subscriber/listener API:

subscribe()
unsubscribe()

See usage example in doc/examples/media.py

__init__(hostname, version=1, name=None, device_name=None, scheduler=None, download_dir=None, integrity_check=None)¶: Initialize self. See help(type(self)) for accurate signature.

connect(timeout=5)¶

disconnect(timeout=5)¶

shutdown()¶: Properly close and stop the websocket connection and the media API background thread

media_info(media_id=None)¶

Returns a media info object if media_id is None or a list of all available media info otherwise.

Return type: list(MediaInfo) or MediaInfo

resource_info(media_id=None, resource_id=None, with_md5=False)¶

Returns a list resources info associated to a media_id or a specific resource info associated to a resource_id. This function raises a ValueError if media_id and resource_id are both left to None.

Return type: list(ResourceInfo) or ResourceInfo

list_media()¶: Returns a list of all available media id

list_resources(media_id=None)¶: Returns a list of all available resource id if media_id is None or a list of resource id associated to the given media_id otherwise.

indexing_state()¶: Returns the current media indexing state :rtype IndexingState:

__call__(expectations)¶: Olympe expectation DSL handler

subscribe(*args, **kwds)¶: See: subscribe()

unsubscribe(subscriber)¶

Unsubscribe a previously registered subscriber

Parameters: subscriber (Subscriber) – the subscriber previously returned by subscribe()

class olympe.MediaInfo¶

Namedtuple class MediaInfo(media_id, type, datetime, size, run_id, resources, duration, thumbnail, gps, video_mode, photo_mode, panorama_type, expected_count, replay_url, thermal)

media_id (str): unique id of the media
type ( MediaType): type of the media
datetime (str) :iso8601 datetime of the media
size (int): size (in bytes) of the media (total size of all its resources)
duration (int): duration (in milliseconds) of the video media (total duration of all its resources)
run_id (str): run id of the media
thumbnail (str): relative url to be used in a GET request to download the media thumbnail (if available)
gps (GPS): gps coordinates of the media (if available)
photo_mode (PhotoMode): photo mode of the media (if available and media is a photo)
panorama_type (panorama_type enum): panorama type of the media (if available, media is a photo and photo_mode is panorama)
expected_count (int): expected number of resources in the media ( if available, media is a photo and photo_mode is panorama)
replay_url (str): media rtsp replay url (prefixed by rtsp://drone.ip.address:rtsp_port/)
resources (list( ResourceInfo )): resource list of the media
thermal (bool): media includes resources with thermal metadata (if value is true)

class olympe.ResourceInfo¶: Namedtuple class ResourceInfo(media_id, resource_id, type, format, datetime, size, url, width, height, duration, thumbnail, gps, video_mode, replay_url, thermal, md5, storage, download_path, thumbnail_download_path)

class olympe.media.MediaType¶

photo = 'PHOTO'¶

video = 'VIDEO'¶

class olympe.media.PhotoMode¶

bracketing = 'BRACKETING'¶

burst = 'BURST'¶

gpslapse = 'GPSLAPSE'¶

panorama = 'PANORAMA'¶

single = 'SINGLE'¶

timelapse = 'TIMELAPSE'¶

class olympe.media.IndexingState¶

indexed = 'INDEXED'¶

indexing = 'INDEXING'¶

not_indexed = 'NOT_INDEXED'¶

class olympe.media.GPS¶

Namedtuple class GPS(latitude, longitude, altitude)

property altitude¶: Alias for field number 2

property latitude¶: Alias for field number 0

property longitude¶: Alias for field number 1

class olympe.VideoFrame¶

ref()¶: This function increments the reference counter of the underlying buffer(s)

unref()¶: This function decrements the reference counter of the underlying buffer(s)

info()¶: Returns a dictionary of video frame info

vmeta()¶: Returns a 2-tuple (VMetaFrameType, dictionary of video frame metadata)

as_ctypes_pointer()¶

This function return a 2-tuple (frame_pointer, frame_size) where frame_pointer is a ctypes pointer and frame_size the frame size in bytes.

See: https://docs.python.org/3/library/ctypes.html

as_ndarray()¶: This function returns an non-owning numpy 1D (h264) or 2D (YUV) array on this video frame

class olympe.PdrawState¶

Created = 1¶

Closing = 2¶

Closed = 3¶

Opening = 4¶

Opened = 5¶

Playing = 6¶

Paused = 7¶

Error = 8¶

class olympe.ReturnTuple¶

A namedtuple used as a return type

This namedtuple class definition is roughly equivalent to:

typing.namedtuple(
    'ReturnTuple',
    [('OK', bool), ('message', str), ('value', typing.Any), ('error_code', int)]
)

A ReturnTuple is implicitly convertible to bool and evaluates to OK.

olympe.Expectation¶: alias of olympe.arsdkng.expectations.ArsdkExpectationBase

olympe.log.get_config(config)¶

Returns the current logging configuration dictionary as previously set or updated by set_config() or update_config() respectively.

See: Logging config dictionary schema

olympe.log.set_config(config)¶

Set the current logging configuration dictionary

See: Logging config dictionary schema

olympe.log.update_config(update)¶

Update (recursively) the current logging condiguration dictionary.

See: Logging config dictionary schema