1Bumble For Web Browsers
2=======================
3
4Early prototype the consists of running the Bumble stack in a web browser
5environment, using [pyodide](https://pyodide.org/)
6
7Two examples are included here:
8
9  * scanner - a simple scanner
10  * speaker - a pure-web-based version of the Speaker app
11
12Both examples rely on the shared code in `bumble.js`.
13
14Running The Examples
15--------------------
16
17To run the examples, you will need an HTTP server to serve the HTML and JS files, and
18and a WebSocket server serving an HCI transport.
19
20For HCI over WebSocket, recent versions of the `netsim` virtual controller support it,
21or you may use the Bumble HCI Bridge app to bridge a WebSocket server to a virtual
22controller using some other transport (ex: `python apps/hci_bridge.py ws-server:_:9999 usb:0`).
23
24For HTTP, start an HTTP server with the `web` directory as its
25root. You can use the invoke task `inv web.serve` for convenience.
26
27`inv web.build` will build the local copy of bumble and automatically copy the `.whl` file
28to the web directory. To use this build, include the param `?packageFile=true` to the URL.
29
30In a browser, open either `scanner/scanner.html` or `speaker/speaker.html`.
31You can pass optional query parameters:
32
33  * `packageFile=true` will automatically use the bumble package built via the
34    `inv web.build` command.
35  * `package` may be set to point to a local build of Bumble (`.whl` files).
36     The filename must be URL-encoded of course, and must be located under
37     the `web` directory (the HTTP server won't serve files not under its
38     root directory).
39  * `hci` may be set to specify a non-default WebSocket URL to use as the HCI
40     transport (the default is: `"ws://localhost:9922/hci`). This also needs
41     to be URL-encoded.
42
43Example:
44    With a local HTTP server running on port 8000, to run the `scanner` example
45    with a locally-built Bumble package `../bumble-0.0.163.dev5+g6f832b6.d20230812-py3-none-any.whl`
46    (assuming that `bumble-0.0.163.dev5+g6f832b6.d20230812-py3-none-any.whl` exists under the `web`
47    directory and the HCI WebSocket transport at `ws://localhost:9999/hci`, the URL with the
48    URL-encoded query parameters would be:
49    `http://localhost:8000/scanner/scanner.html?hci=ws%3A%2F%2Flocalhost%3A9999%2Fhci&package=..%2Fbumble-0.0.163.dev5%2Bg6f832b6.d20230812-py3-none-any.whl`
50
51
52NOTE: to get a local build of the Bumble package, use `inv build`, the built `.whl` file can be found in the `dist` directory.
53Make a copy of the built `.whl` file in the `web` directory.
54
55Tip: During web developement, disable caching. [Chrome](https://stackoverflow.com/a/7000899]) / [Firefiox](https://stackoverflow.com/a/289771)