1GETTING STARTED WITH BUMBLE 2=========================== 3 4# Prerequisites 5 6You need Python 3.8 or above. Python >= 3.9 is recommended, but 3.8 should be sufficient if 7necessary (there may be some optional functionality that will not work on some platforms with 8python 3.8). 9Visit the [Python site](https://www.python.org/) for instructions on how to install Python 10for your platform. 11Throughout the documentation, when shell commands are shown, it is assumed that you can 12invoke Python as 13``` 14$ python 15``` 16If invoking python is different on your platform (it may be `python3` for example, or just `py` or `py.exe`), 17adjust accordingly. 18 19You may be simply using Bumble as a module for your own application or as a dependency to your own 20module, or you may be working on modifying or contributing to the Bumble module or example code 21itself. 22 23# Using Bumble As A Python Module 24 25## Installing 26 27You may choose to install the Bumble module from an online package repository, with a package 28manager, or from source. 29 30!!! tip "Python Virtual Environments" 31 When you install Bumble, you have the option to install it as part of your default 32 python environment, or in a virtual environment, such as a `venv`, `pyenv` or `conda` environment. 33 See the [Python Environments page](development/python_environments.md) page for details. 34 35### Install From Source 36 37Install with `pip`. Run in a command shell in the directory where you downloaded the source 38distribution 39``` 40$ python -m pip install -e . 41``` 42 43### Install from GitHub 44 45You can install directly from GitHub without first downloading the repo. 46 47Install the latest commit from the main branch with `pip`: 48``` 49$ python -m pip install git+https://github.com/google/bumble.git 50``` 51 52You can specify a specific tag. 53 54Install tag `v0.0.1` with `pip`: 55``` 56$ python -m pip install git+https://github.com/google/bumble.git@v0.0.1 57``` 58 59You can also specify a specific commit. 60 61Install commit `27c0551` with `pip`: 62``` 63$ python -m pip install git+https://github.com/google/bumble.git@27c0551 64``` 65 66# Working On The Bumble Code 67When you work on the Bumble code itself, and run some of the tests or example apps, or import the 68module 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. 69 70If you plan on contributing to the project, please read the [contributing](development/contributing.md) section. 71 72## Without Installing 73If you prefer not to install the package (even in development mode), you can load the module directly from its location in the project. 74A simple way to do that is to set your `PYTHONPATH` to 75point to the root project directory, where the `bumble` subdirectory is located. You may set 76`PYTHONPATH` globally, or locally with each command line execution (on Unix-like systems). 77 78Example with a global `PYTHONPATH`, from a unix shell, when the working directory is the root 79directory of the project. 80 81```bash 82$ export PYTHONPATH=. 83$ python apps/console.py serial:/dev/tty.usbmodem0006839912171 84``` 85 86or running an example, with the working directory set to the `examples` subdirectory 87```bash 88$ cd examples 89$ export PYTHONPATH=.. 90$ python run_scanner.py usb:0 91``` 92 93Or course, `export PYTHONPATH` only needs to be invoked once, not before each app/script execution. 94 95Setting `PYTHONPATH` locally with each command would look something like: 96``` 97$ PYTHONPATH=. python examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171 98``` 99 100# Where To Go Next 101Once you've installed or downloaded Bumble, you can either start using some of the 102[Bundled apps and tools](apps_and_tools/index.md), or look at the [examples](examples/index.md) 103to get a feel for how to use the APIs, and start writing your own applications. 104 105Depending on the use case you're interested in exploring, you may need to use a physical Bluetooth 106controller, like a USB dongle or a board with a Bluetooth radio. Visit the [Hardware page](hardware/index.md) 107for more information on using a physical radio, and/or the [Transports page](transports/index.md) for more 108details on interfacing with either hardware modules or virtual controllers over various transports. 109