1# What is this?
2
3Rust wrappers around the [Bumble](https://github.com/google/bumble) Python API.
4
5Method calls are mapped to the equivalent Python, and return types adapted where
6relevant.
7
8See the CLI in `src/main.rs` or the `examples` directory for how to use the
9Bumble API.
10
11# Usage
12
13Set up a virtualenv for Bumble, or otherwise have an isolated Python environment
14for Bumble and its dependencies.
15
16Due to Python being
17[picky about how its sys path is set up](https://github.com/PyO3/pyo3/issues/1741,
18it's necessary to explicitly point to the virtualenv's `site-packages`. Use
19suitable virtualenv paths as appropriate for your OS, as seen here running
20the `battery_client` example:
21
22```
23PYTHONPATH=..:~/.virtualenvs/bumble/lib/python3.10/site-packages/ \
24    cargo run --example battery_client -- \
25    --transport android-netsim --target-addr F0:F1:F2:F3:F4:F5
26```
27
28Run the corresponding `battery_server` Python example, and launch an emulator in
29Android Studio (currently, Canary is required) to run netsim.
30
31# CLI
32
33Explore the available subcommands:
34
35```
36PYTHONPATH=..:[virtualenv site-packages] \
37    cargo run --features bumble-tools --bin bumble -- --help
38```
39
40Notable subcommands:
41
42- `firmware realtek download`: download Realtek firmware for various chipsets so that it can be automatically loaded when needed
43- `usb probe`: show USB devices, highlighting the ones usable for Bluetooth
44
45# Development
46
47Run the tests:
48
49```
50PYTHONPATH=.. cargo test
51```
52
53Check lints:
54
55```
56cargo clippy --all-targets
57```
58
59## Code gen
60
61To have the fastest startup while keeping the build simple, code gen for
62assigned numbers is done with the `gen_assigned_numbers` tool. It should
63be re-run whenever the Python assigned numbers are changed. To ensure that the
64generated code is kept up to date, the Rust data is compared to the Python
65in tests at `pytests/assigned_numbers.rs`.
66
67To regenerate the assigned number tables based on the Python codebase:
68
69```
70PYTHONPATH=.. cargo run --bin gen-assigned-numbers --features dev-tools
71```
72