pymoof

Connect to your Vanmoof S3 and X3 through bluetooth.

Installation

Install python 3.7+, then use pip to install pymoof. pip install pymoof

Usage

pymoof was tested to work on MacOS 12.1, Ubuntu 20.04.3 LTS, and a Raspberry Pi 3 b+ running Raspberry Pi OS (32-bit) / 2021-10-30.

from pymoof.clients.sx3 import SX3Client
import bleak

...

device = ...
encryption_key = ...
user_key_id = ...

async with bleak.BleakClient(device) as bleak_client:
	client = SX3Client(bleak_client, encryption_key, user_key_id)
	await client.authenticate()

You must have an instantiated bleak client that is connected to the bike. See pymoof.tools.discover_bike to determine which device is your bike and pymoof.tools.retrieve_encryption_key to connect to Vanmoof servers to get your encryption key.

See example.py for additional usage.

Contributing

Contributions are welcome and encouraged! Every bit helps and credit will be given.

Ways you can help:

Reporting Bugs

You can report bugs through the github issue tracker: https://github.com/quantsini/pymoof/issues

Useful information to include when reporting bugs:

Version of pymoof
The operating system where pymoof was used
What Vanmoof bike was used
Detailed steps on reproducing an issue

Help with reverse engineering

Vanmoof bikes communicate through Bluetooth Low Energy. I've tried my best to get all the BLE GATT UUIDs, however, some reverse engineering is needed to figure out what the payloads represent. I suggest using a packet sniffer like wireshark to analyze data from the official Vanmoof app and the bike.

Writing Documentation

Good documentation is always good!

Getting Started with Development

You want to contribute? Awesome! Here are some steps to get you up and running. This project uses Poetry for package and dependency management and tox for tests.

Create a fork of the pymoof github repo.
Clone it locally:

git clone git@github.com:<your username>/pymoof.git

Get the latest version of poetry, a package and dependency management tool.
Install dependencies

poetry install

Activate your shell. This should put you in a virtualenv that allows you to run tests.

poetry shell

You should now be able to run tests and make modifications. You can run tests by running tox under poetry

poetry run tox

Go forth and make great changes!

devmarcstorm/pymoof