https://github.com/quantsini/pymoof
Connect to your Vanmoof SX3 using python
https://github.com/quantsini/pymoof
python python-library vanmoof
Last synced: 10 months ago
JSON representation
Connect to your Vanmoof SX3 using python
- Host: GitHub
- URL: https://github.com/quantsini/pymoof
- Owner: quantsini
- License: mit
- Created: 2022-01-22T19:48:47.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-02-21T17:43:42.000Z (over 4 years ago)
- Last Synced: 2024-07-06T18:04:48.385Z (almost 2 years ago)
- Topics: python, python-library, vanmoof
- Language: Python
- Homepage:
- Size: 57.6 KB
- Stars: 37
- Watchers: 5
- Forks: 6
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pymoof
[](https://pymoof.readthedocs.io/en/latest/) [](https://badge.fury.io/py/pymoof) [](https://github.com/quantsini/pymoof/actions/workflows/test.yml)
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.
```python
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](https://bleak.readthedocs.io/en/latest/) 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](https://www.wireshark.org) 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](https://python-poetry.org/docs/master/#installing-with-the-official-installer) for package and dependency management and [tox](https://www.tox.wiki/) for tests.
1. Create a fork of the _pymoof_ github repo.
2. Clone it locally:
```
git clone git@github.com:/pymoof.git
```
3. Get the [latest version of poetry](https://python-poetry.org), a package and dependency management tool.
4. Install dependencies
```
poetry install
```
5. Activate your shell. This should put you in a virtualenv that allows you to run tests.
```
poetry shell
```
6. You should now be able to run tests and make modifications. You can run tests by running tox under poetry
```
poetry run tox
```
7. Go forth and make great changes!