GETTING STARTED WITH BUMBLE

Prerequisites

You need Python 3.8 or above. Python >= 3.9 is recommended, but 3.8 should be sufficient if necessary (there may be some optional functionality that will not work on some platforms with python 3.8).
Visit the Python site for instructions on how to install Python for your platform.
Throughout the documentation, when shell commands are shown, it is assumed that you can invoke Python as

$ python

If invoking python is different on your platform (it may be python3 for example, or just py or py.exe), adjust accordingly.

You may be simply using Bumble as a module for your own application or as a dependency to your own module, or you may be working on modifying or contributing to the Bumble module or example code itself.

Working With Bumble As A Module

Installing

You may choose to install the Bumble module from an online package repository, with a package manager, or from source.

Python Virtual Environments

When you install Bumble, you have the option to install it as part of your default python environment, or in a virtual environment, such as a venv, pyenv or conda environment

venv

venv is a standard module that is included with python. Visit the venv documentation page for details.

Pyenv

pyenv lets you easily switch between multiple versions of Python. It's simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well.
Visit the pyenv site for instructions on how to install and use pyenv

Conda

Conda is a convenient package manager and virtual environment. The file environment.yml is a Conda environment file that you can use to create a new Conda environment. Once created, you can simply activate this environment when working with Bumble.
Visit the Conda side for instructions on how to install and use Conda. A few useful commands:

Create a new bumble Conda environment

$ conda env create -f environment.yml

This will create a new environment, named bumble, which you can then activate with:

$ conda activate bumble

Update an existing bumble environment

$ conda env update -f environment.yml

Install From Source

The instructions for working with virtual Python environments above also apply in this case.

Install with pip

$ python -m pip install -e .

Working On The Bumble Code

When you work on the Bumble code itself, and run some of the tests or example apps, or import the module in your own code, you typically either install the package from source in "development mode" as described above, or you may choose to skip the install phase.

Without Installing

If you prefer not to install the package (even in development mode), you can load the module directly from its location in the project. A simple way to do that is to set your PYTHONPATH to point to the root project directory, where the bumble subdirectory is located. You may set PYTHONPATH globally, or locally with each command line execution (on Unix-like systems).

Example with a global PYTHONPATH, from a unix shell, when the working directory is the root directory of the project.

$ export PYTHONPATH=.
$ python apps/console.py serial:/dev/tty.usbmodem0006839912171

or running an example, with the working directory set to the examples subdirectory

$ cd examples
$ export PYTHONPATH=..
$ python run_scanner.py usb:0

Or course, export PYTHONPATH only needs to be invoked once, not before each app/script execution.

Setting PYTHONPATH locally with each command would look something like:

$ PYTHONPATH=. python examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171