Quick Start

Installation

The SDK requires Python 3.7 or higher. Since many operating systems do not package the newest version of Python we recommend using pyenv or something similar for configuring multiple python versions on the same system. Pyenv also has the added benefit of managing your virtual environments for you, though you are of course free to use other tools for that as well.

The instructions below show the necessary steps to get started with the SDK on a fresh install:

Windows

Install Python

Install Python 3.7 or higher, you can find the latest python versions here. Remember to check the option "Add Python to path" when installing.

Install virtualenv for managing Python versions (optional)

Using a virtual environment is not strictly necessary, but it greatly simplifies the development of Python packages.

# Upgrade pip version
python -m pip install --upgrade pip
pip install virtualenv

Next, we create a virtual environment

cd .\Desktop
mkdir pioneer_project
cd .\pioneer_project
# Replace "C:\Program Files\Python37\python.exe" with the path
# to the python version you want to use in the line below
virtualenv blueye_sdk_env -p "C:\Program Files\Python37\python.exe"
activate the virtual environment
.\blueye_sdk_env\Scripts\activate.bat
if you are not allowed to activate the virtual environment, you might have to allow running unsigned scripts, see this link for instructions.

Install the SDK

Now we're ready to install the SDK, which should be as simple as

pip install blueye.sdk

or, if you want to include the dependencies required for running the examples shown in this documentation you should run

pip install "blueye.sdk[examples]"
Mac OS

Install the necessary Python version

Install pyenv, for more instructions see the pyenv-installer

curl https://pyenv.run | bash
pyenv update

If you want pyenv to be loaded each time you open a new terminal you can add this to your .zshrc or the equivalent for your terminal

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

The Pyenv wiki recommends installing some additional dependencies before building Python.

# optional, but recommended:
brew install openssl readline sqlite3 xz zlib

When running Mojave or higher (10.14+) you will also need to install the additional SDK headers:

sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /
Then build Python with pyenv

pyenv install 3.8.0

Create a virtual environment

Using a virtual environment is not strictly necessary, but it greatly simplifies the development of Python packages.

Since we already have pyenv installed we'll use it to create a virtual environment,

pyenv virtualenv 3.8.0 blueye.sdk
pyenv activate blueye.sdk

Install the SDK

Now we're ready to install the SDK, which should be as simple as.

pip install blueye.sdk

or, if you want to include the dependencies required for running the examples shown in this documentation you should run

pip install "blueye.sdk[examples]"
Linux

These instructions are directed at Ubuntu, but the process should be similar for other distributions.

Install the necessary Python version

Install pyenv, for more instructions see the pyenv-installer

curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
pyenv update

Install the needed dependencies for building python 3.8.0

apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev python-openssl
Then build python with pyenv
pyenv install 3.8.0

Create a virtual environment

Using a virtual environment is not strictly necessary, but it greatly simplifies the development of Python packages.

Since we already have pyenv installed we'll use it to create a virtual environment,

pyenv virtualenv 3.8.0 blueye.sdk
pyenv activate blueye.sdk

Install the SDK

Now we're ready to install the SDK, which should be as simple as

pip install blueye.sdk

or, if you want to include the dependencies required for running the examples shown in this documentation you should run

pip install "blueye.sdk[examples]"

Connect to the Pioneer

To use the SDK your computer must be connected to the Pioneer via the surface unit WiFi. Turn on the drone and connect to the surface unit WiFi. For a how to on turning on the Pioneer and surface unit you can watch the quick start video.

Control the Pioneer

Most of the pioneers functionality is controlled using python properties, we can illustrate the use of properties by showing how to control the lights through the lights property of the Pioneer.

import time
from blueye.sdk import Pioneer
# when the pioneer object is instantiatied a connection to the drone is established
p = Pioneer()
# setting the lights property of the Pioneer object to 10
p.lights = 10
time.sleep(2)
# we can also get the current brightness of the lights through the lights property
print(f"Current light intensity: {p.lights}")
p.lights = 0

# properties can also be used for reading telemetry data from the drone
print(f"Current depth in millimeters: {p.depth}")
For a overview of the properties that are availabe for controlling and reading data from the Pioneer, go to the Reference section of the documentation. The valid input ranges and descriptions of the different properties can also be found there.

Tip

You can explore the properties of the Pioneer interactively using an interactive python interpreter like iPython, install it with:

pip install ipython
By instantiating a Pioneer object and using the completion key (normally the tab-key ↹) you can get a interactive list of the available properties on the Pioneer, it is then easy to try setting and getting the different properties. iPython

Watching the video stream

The easiest way to open the RTSP video stream is using VLC media player. Once VLC is downloaded you can start the stream like this, the RTSP URL is: rtsp://192.168.1.101:8554/test text

For lower latency streaming (on a PC) you can see the instructions on using Gstreamer, or if you just want to watch a low latency stream you can download the Blueye Dive Buddy (iOS / Android)

The normal Blueye app can not be used to spectate when controlling the drone from the SDK because it will interfere with the commands sent from the SDK. The dive buddy app, however, is only a spectator and can be used together with the SDK.

Explore the examples

For further examples on how to use the SDK to control the Pioneer have a look at the motion examples.

Remember to install the example dependencies before running the examples.

pip install "blueye.sdk[examples]"

Local documentation

Since the drone surface unit (usually) does not have internet access it can be a bit tricky to reference this documentation while developing on the drone. Luckily when you install the SDK from PyPI it includes a pre-built, local copy of this documentation. This documentation can be viewed by executing the following Python snippet:

import blueye.sdk

blueye.sdk.open_local_documentation()