Able stands for Allthenticate's Bluetooth Low Energy (Library) and serves to be a platform agnostic python library for communication with centrals as a BLE Peripheral.
Project description
Able
Able stands for Allthenticate's BLE Peripheral Library, created to be a companion to the hit bluetooth repository Bless. It serves the purpose of enabling the abstraction of using a BLE Peripheral on Ubuntu, MacOs and Windows based systems without having to adapt your software to have platform specific support.
Quick Start
To get started just run get_started.sh
. This will install poetry and all of the project's dependencies, and drop you into the projects virtual environment.
bash get_started.sh
How To's
Getting started
To get started the only thing you should have to install is poetry, our chosen package manager. To install on linux/macos all you need to run is:
python3 scripts/install-poetry.py
Make sure that you can run poetry --version
before proceeding on to the next step, you may need to source a directory as specified
by the poetry installation. From there you need to install Able and it's dependencies, let's do it in a virtualenv!
git clone git@gitlab.com:allthenticate/software/able.git
cd able
poetry install
After that you should be good to go, poetry will automatically download any dependencies needed and set up a virtual environment ready to go for developing with able. If you want to activate said virtual environment, just run:
poetry shell
Whenever you pull new updates we recommend running a quick poetry install
to get any updates.
Upgrading Poetry Installer
It may be the case that the current version of your Poetry package is outdated. Run scripts/check_poetry.sh
to check if there is a newer version of the poetry installer.
bash scripts/check_poetry.sh
Documentation
Writing Docs
We follow the Sphinx docstring format for our docstrings, see the following site on the complete specification, but the general docstring will look like:
"""
[Summary]
:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""
Generating Docs
To generate the docs for local use you should just have to run the following inside of the poetry shell:
make html
Then open the html produced by Sphinx.
Auto-Generating Docs
If you want to have docs magically update as you are writing them, run the following command:
sphinx-autobuild source/ build/html/
Testing Able
How To Test?
Running tests are easy, you need to only do a few things as a developer. First track down the IP of the companion you plan to be using, we recommend a raspberry pi. Once you have that IP, export it as an environment variable as so:
export ABLE_CENTRAL_IP="<IP>"
Now, we can run the tests with the following command:
poetry install && poetry run pytest tests
Rigorous Testing
If you want to do more rigorous testing over a long period of time and check for flaky tests, you will
have to modify the pyproject.toml
. We already have the dependencies you need to run tests multiple times
to detect flakiness, all you need to do is modify the following line:
addopts = "--flake-finder --flake-runs=1 --reruns 5 --reruns-delay 5"
Into:
addopts = "--flake-finder --flake-runs=10 --reruns 5 --reruns-delay 5"
This will run each test 10 times, you can even modify it to be greater should you choose. You can also
modify the reruns
and reruns-delay
parameters to change how much time you should wait between failed tests,
maybe to let things simmer and how many reruns you will accept.
Speedy Tests
Our dependencies include pytest-fast-first
which will locally track which tests are quicker and will use AI and
deep learning (a json dictionary of times) to track and run tests that go faster first! Neat!
Coming Soon
We are hoping to have unit tests coming soon for Able but right now are relying solely on hardware in the loop tests to get things off the ground. Eventually we will detect if you have a companion set and if not, we will only run the unit tests.
Support
If you have any questions on the use of this library feel free to reach out the head maintainer bernie@allthenticate.net or submit an issue on the repository.
Contributing
Contributing is not currently enabled but once the repository is licensed we will be opening the project up for public contributions.
Changelog
See the changelog doc for the changelog. WIP
Common Problems
Permission denied trying to start the examples
If you see something like this:
dbus_next.errors.DBusError: Connection ":1.155" is not allowed to own the service "org.bluez.ABle" due to security policies in the configuration file'
Double check /etc/dbus-1/system.d/bluetooth.conf
and either add a policy group that has the requisite perms or duplicate the root policy for your username,
and feel free to reach out to Bernie if this doesn't resolve the problem.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.