bumble/examples/README.md

Bumble Examples
===============

NOTE:
To run python scripts from this directory when the Bumble package isn't installed in your environment,
put .. in your PYTHONPATH: `export PYTHONPATH=..`

# `run_controller.py`
Run two virtual controllers, one connected to a soft device written in python with a simple GATT server, and the other connected to an external host.

## Running `run_controller.py` with a BlueZ host running on Linux.

In this configuration, a BlueZ stack running on a Linux host is connected to a Bumble virtual
controller, attached to a local link bus to a second, in-process, virtual controller, itself
used by a virtual device with a GATT server.

### Running with two separate hosts (ex: a mac laptop and a Linux VM)
In this setup, the virtual controllers and host run on a mac desktop, and the BlueZ stack on a Linux VM. A UDP socket communicates HCI packets between the macOS host and the Linux guest.

#### Linux setup
In a terminal, run `socat` to bridge a UDP socket to a local PTY.
The PTY is used a virtual HCI UART.
(in this example, the mac's IP address seen from the Linux VM is `172.16.104.1`, replace it with
the appropriate address for your environment. (you may also use a port number other than `22333` used here)
```
socat -d -d -x PTY,link=./hci_pty,rawer UDP-SENDTO:172.16.104.1:22333,bind=:22333
```

In the local directory, `socat` creates a symbolic link named `hci_pty` that points to the PTY.

In a second terminal, run
```
sudo btattach -P h4 -B hci_pty
```

This tells BlueZ to use the PTY as an HCI UART controller.

(optional) In a third terminal, run `sudo btmon`. This monitors the HCI traffic with BlueZ, which is great to see what's going on.

In a fourth terminal, run `sudo bluetoothctl` to interact with BlueZ as a client. From there, you can scan, advertise, connect, etc.

#### Mac setup
In a macOS terminal, run
```
python run_controller.py device1.json udp:0.0.0.0:22333,172.16.104.161:22333
```

This configures one of the virtual controllers to use a UDP socket as its HCI transport. In this example, the ip address of the Linux VM is `172.16.104.161`, replace it with the appropriate
address for your environment.

Once both the Linux and macOS processes are started, you should be able to interact with the
`bluetoothctl` tool on the Linux side and scan/connect/discover the virtual device running on
the macOS side. Relevant log output in each of the terminal consoles should show what it going on.

### Running with a single Linux host
In setup, both the BlueZ stack and tools as well as the Bumble virtual stack are running on the same
host.

In a terminal, run the example as
```
python run_controller.py device1.json pty:hci_pty
```

In the local directory, a symbolic link named `hci_pty` that points to the PTY is created.

From this point, run the same steps as in the previous example to attach the PTY to BlueZ and use
`bluetoothctl` to interact with the virtual controller.


# `run_gatt_client.py`
Run a host application connected to a 'real' BLE controller over a UART HCI to a dev board running Zephyr in HCI mode (could be any other UART BLE controller, or BlueZ over a virtual UART). The application connects to a Bluetooth peer specified as an argument.
Once connected, the application hosts a GATT client that discovers all services and all attributes of the peer and displays them.

# `run_gatt_server.py`
Run a host application connected to a 'real' BLE controller over a UART HCI to a dev board running Zephyr in HCI mode (could be any other UART BLE controller, or BlueZ over a virtual UART). The application connects to a Bluetooth peer specified as an argument.
The application hosts a simple GATT server with basic
services and characteristics.

# `run_gatt_client_and_server.py`

# `run_advertiser.py`

# `run_scanner.py`
Run a host application connected to a 'real' BLE controller over a UART HCI to a dev board running Zephyr in HCI mode (could be any other UART BLE controller, or BlueZ over a virtual UART), that starts scanning and prints out the scan results.