morgan/UxPlay
1
0
Fork 0
mirror of https://github.com/morgan9e/UxPlay synced 2026-04-13 15:54:09 +09:00
Code Issues Packages Projects Releases Wiki Activity

README updates for beacon

Browse Source
This commit is contained in:
F. Duncanh
2026-03-22 00:44:23 -04:00
parent f54d561389
commit 3b4a15f461
3 changed files with 222 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
README.html
View File

@@ -1548,44 +1548,42 @@ messages, set GST_DEBUG=4; for DEBUG messages, GST_DEBUG=5; increase
this to see even more of the GStreamer inner workings.</p>
<h1 id="bluetooth-le-beacon-setup">Bluetooth LE beacon setup</h1>
<p>The python&gt;=3.6 script for running a Bluetooth LE Service
Discovery beacon is uxplay-beacon.py. It provides four possible
Bluetooth LE implementations (loaded as modules):</p>
Discovery beacon is uxplay-beacon.py. Besides the standard python
libraries, it requires python3-psutils.</p>
<p>It provides four possible Bluetooth LE implementations (loaded as
modules <code>uxplay_beacon_module_*.py</code>), which may need
additional libraries:</p>
<ul>
<li><p><strong>BlueZ</strong> for Linux systems with D-Bus;</p></li>
<li><p><strong>winrt</strong> for Windows;</p></li>
<li><p><strong>BleuIO</strong> for the <a
href="https://www.bleuio.com">BleuIO (or BleuIO Pro) USB dongle</a> with
its own on-board Bluetooth-LE Stack that does not use the host operating
system Bluetooth (the host sees the device as a USB serial modem). This
is needed for macOS where the native operating system Bluetooth stack
does not allow users to send Bluetooth-LE advertising data of the
“manufacturer-specific” type <code>AdvData=0xFF</code>. If a BleuIO
dongle (currently costs about USD25) is available, the BleuIO version of
the python script can be used on many operating systems including macOS,
Windows, Linux, FreeBSD, and probably other BSD variants (not tested):
it requires python library <code>python3-pyserial</code> to be
installed. On Linux, users must be members of group <code>dialout</code>
or sometimes <code>uucp</code> (<code>dialer</code> on
FreeBSD).</p></li>
<li><p><strong>HCI</strong> for Linux without D-Bus (uses utiities
<code>hcitool</code> and <code>hciconfig</code>) or FreeBSD (uses
<code>hccontrol</code>) and requires elevated privileges to access the
Host Controller Interface. These privileges can be granted by adding
users to a new group “hciusers” that are given permission to call
“<code>sudo -n hci*</code>” (<code>hci*</code> = hcitool, hciconfig or
hccontrol) without entering a password: this can be configured by the
system administrator using <code>visudo</code> (<em>security
implications should be considered</em>). Use visudo to create a file
<code>hciusers</code> in <code>/etc/sudoers.d/</code> (Linux) or
<code>/usr/local/etc/sudoers.d</code> (FreeBSD), containing the line
“<code>%hciusers ALL=(ALL) NOPASSWD: &lt;hcitools&gt;</code>” (where
<code>&lt;hcitools&gt;</code> is replaced by
“<code>/usr/bin/hcitool, /usr/bin/hciconfig</code>” (Linux) or
“<code>/usr/sbin/hccontrol</code>” (FreeBSD). In addition, FreeBSD’s
<li><p><strong>BlueZ</strong> for Linux systems with D-Bus: needs
<strong>GLib</strong> (from python3-gi or PyGObject) and
<strong>python-dbus</strong>.</p></li>
<li><p><strong>winrt</strong> for Windows: requires some
<strong>winrt-Windows-*</strong> libraries.</p></li>
<li><p><strong>BleuIO</strong> for all operating systems: requires
<strong>pyserial</strong>. This also requires the <a
href="https://www.bleuio.com">BleuIO (or BleuIO Pro) USB dongle</a>
which is a USB serial device with its own on-board Bluetooth LE Stack
that does not use the host operating system’s stack (the host sees the
device as a USB serial modem). This works on all operating systems that
provide access to serial devices, including macOS and *BSD. On some
Linux, users need to be added to the <code>dialout</code> group, on
others <code>uucp</code>; on FreeBSD this is the <code>dialer</code>
group, on other *BSD, it may be <code>uucp</code>.</p></li>
<li><p><strong>HCI</strong> For Linux and FreeBSD: no extra libraries,
but requires root access to the HCI (Host Controller Interface) for
Bluetooth devices, using utilities <code>hcitool</code> and
<code>hciconfig</code> (Linux) or <code>hccontrol</code> (FreeBSD). See
below on how to provide such access. In addition, FreeBSD’s
<code>hccontrol</code> needs a patch to allow generic LE Advertising
Data to be input. We have submitted it to FreeBSD as a Pull Request, and
you can find it on the [UxPlay Wiki]
(https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0)</p></li>
you can find it on the <a
href="https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0">UxPlay
Wiki</a>. <em>Note that macOS has a utility
<code>/usr/sbin/bluetool</code> that is similar to <code>hcitool</code>,
and might allow the HCI module to be extended to support macOS, but
since the BleuIO module is a working solution for macOS, this has not
been attempted (Pull Requests with working implementations are
welcome!).</em></p></li>
</ul>
<p>On Linux, Bluetooth support (using the official Linux Bluetooth stack
BlueZ, and D-Bus) must be installed (on Debian-based systems:
@@ -1594,18 +1592,18 @@ provide bluez as a snap package). BlueZ tools ‘hcitool’ and ‘hciconfig’
(needed if you use the HCI module on Linux) are declared “deprecated” by
the BlueZ developers: some Linux distributions have removed them from
the default BleuZ packages, into “extra” packages with names like
“bluez-deprecated”.</p>
<p>In addition to standard Python3 libraries, you may need to install
the gi, dbus, and psutil Python libraries used by uxplay-beacon.py. On
Debian-based systems:</p>
<pre><code>sudo apt install python3-gi python3-dbus python3-psutil</code></pre>
<p>If a python3-gi package is available in your Linux distribution,
install the python3-gobject package which provides it.</p>
<p>For Windows support in the MSYS2 UCRT64 environment, use pacman -S to
install <code>mingw-w64-ucrt-x86_64-python</code>,
<code>*-python-gobject</code>, <code>*-python-psutil</code>, and
<code>*-python-pip</code>. Then install <strong>winrt</strong> bindings
using pip (or pip3):</p>
“bluez-deprecated”. Also install psutil Python libraries used by
uxplay-beacon.py. On Debian-based systems:</p>
<pre><code>sudo apt install python3-psutil</code></pre>
<p>For the <strong>BlueZ</strong> module (Linux), install python3-gi
(from which GLib is imported) and python3-dbus. If a python3-gi package
is not available in your Linux distribution, use <code>pip</code> to
install PyGObject instead.</p>
<p>For the <strong>winrt</strong> module, with Windows support in the
MSYS2 UCRT64 environment, use pacman -S to install
<code>mingw-w64-ucrt-x86_64-python</code>,<code>*-python-psutil</code>,
and <code>*-python-pip</code>. Then install <strong>winrt</strong>
bindings using pip (or pip3):</p>
<pre><code>pip install winrt-Windows.Foundation
pip install winrt-Windows.Foundation.Collections
pip install winrt-Windows.Devices.Bluetooth.Advertisement
@@ -1617,15 +1615,33 @@ python installations (such as the one provided in MSYS2) should be</p>
requirement to make users hesitate before adding packages not provided
by the “external management”: <em>this is unnecessarily scary, as in the
case of the winrt packages, no breakage can occur</em>.</p>
<p>UxPlay must be run with option “<code>uxplay -ble</code>” (so it
writes data for the Bluetooth beacon in the default BLE data file
<code>~/.uxplay.ble</code>), just run <code>uxplay-beacon.py</code> in a
separate terminal. The python script will start Bluetooth LE
Service-Discovery advertising when it detects that UxPlay is running by
checking if the BLE data file exists, and stop when it no longer detects
a running UxPlay plus this file (it will restart advertising if UxPlay
later reappears). The script will remain active until stopped with
Ctrl+C in its terminal window (or its terminal window is closed).</p>
<p>For the <strong>BleuIO</strong> module, install pyserial.</p>
<p>For the <strong>HCI</strong> module, create a group
<code>hciusers</code> to give group members the privilege of using
passwordless <code>sudo -n hci*</code> (<code>hci*</code> is
<code>hcitool</code> and <code>hciconfig</code> (Linux), or
<code>hccontrol</code> (FreeBSD), and add users of the module to this
group (<em>security implications should be considered</em>). In Linux,
use “<code>sudo visudo /etc/sudoers.d/hciusers</code>” (in FreeBSD, file
is <code>/usr/local/etc/sudoers.d/hciusers</code>) to create a file
containing one of the lines</p>
<pre><code>%hciusers ALL=(ALL) NOPASSWD: /usr/bin/hcitool, /usr/bin/hciconfig (Linux)
%hciusers ALL=(ALL) NOPASSWD: /usr/sbin/hccontrol (FreeBSD)</code></pre>
<p>UxPlay must be run with option
“<code>uxplay -ble [path_to_file]</code>” (so it writes data for the
Bluetooth beacon to the default BLE data file
<code>~/.uxplay.ble</code>, or optionally to the file specifed by its
path), then run
<code>uxplay-beacon.py [HCI, BleuIO] [--path path_to_file]</code> in a
separate terminal. If options HCI or BleuIO are not given, the default
module for the operating system will be used (BlueZ for Linux, winrt for
Windows, BleuIO for all others).</p>
<p>The python script will start Bluetooth LE Service-Discovery
advertising when it detects that UxPlay is running by checking if the
BLE data file exists, and stop when it no longer detects a running
UxPlay (it will restart advertising if UxPlay later reappears). The
script will remain active until stopped with Ctrl+C in its terminal
window (or its terminal window is closed).</p>
<p>The beacon script can be more finely controlled using certain
options: these can be given on the command line, or read from a
configuration file <code>~/.uxplay.beacon</code>, if it exists.
@@ -1637,7 +1653,7 @@ or <code>uxplay-beacon.py --help</code>.</p>
<p>Options are</p>
<ul>
<li><p><code>&lt;module&gt;</code> where “module” is BleuIO or HCI (no
intital <code>--</code>) . Without this option, the default module used
initial <code>--</code>) . Without this option, the default module used
will be <strong>BlueZ</strong> (Linux), <strong>winrt</strong>
(Windows), <strong>BleuIO</strong> (all other operating
systems).</p></li>
@@ -1666,7 +1682,7 @@ with other tasks the Bluetooth device is carrying out. The default
values are advmin = advmax = 100. The advertisement is broadcast on all
three Bluetooth LE advertising channels: 37,38,39.</li>
</ul>
<p>On a Windows system, the values of these paramaters are set by the
<p>On a Windows system, the values of these parameters are set by the
operating system, and cannot be set by users.</p>
<p>The <strong>BlueZ</strong> module (Linux) also accepts</p>
<ul>
@@ -1683,25 +1699,23 @@ needed.</em></li>
accept</p>
<ul>
<li><code>--device x</code> which allows overiding automatically-made
choices of serial ports (<strong>BleuIO</strong>) or hci device nodes
choices of serial ports (<strong>BleuIO</strong>) or hci devices
(<strong>HCI</strong>). This is probably only useful if the host system
has multiple devices that could be used.</li>
</ul>
<p>The native macOS Bluetooth stack has no documented way for users to
<p>The native macOS Bluetooth stack does not allow unprivileged users to
send “manufacturer-specific” Bluetooth LE advertisements (such that sent
for AirPlay Service Discovery), and the only support of uxplay-beacon.py
on macOS uses a BleuIO USB serial device. However macOS provides a
low-level utility BlueTool (found at <code>/usr/sbin/bluetool</code>)
that can send HCI commands, so possibly could be used to adapt the
python3 <strong>HCI</strong> module to support macOS as well
(<em>working implementations welcome!</em>). <strong>The recommended and
working method on macOS is to use a BleuIO dongle.</strong></p>
<p>If you wish to test Bluetooth LE Service Discovery on Linux/*BSD, you
can disable DNS_SD Service discovery by the avahi-daemon with</p>
for AirPlay Service Discovery), and the only current support of
uxplay-beacon.py on macOS uses a BleuIO USB serial device.</p>
<p>For testing Bluetooth LE Service Discovery you might wish to disable
DNS_SD Service discovery (although the Bluetooth LE Service seems to
work if DNS_SD is enabled). On Linux, disable the the avahi-daemon that
provides DNS_SD with</p>
<pre><code>$ sudo systemctl mask avahi-daemon.socket
$ sudo systemctl stop avahi-daemon</code></pre>
<p>To restore DNS_SD Service discovery, replace “mask” by “unmask”, and
“stop” by “start”.</p>
<p>(On FreeBSD, “<code>service avahi-daemon stop</code>”). To restore
DNS_SD Service discovery, replace “mask” by “unmask”, and “stop” by
“start”.</p>
<p>On Windows, the Bonjour Service is controlled using <strong>Services
Management</strong>: press “Windows + R” to open the Run dialog, run
<code>services.msc</code>, and click on <strong>Bonjour Service</strong>

97
README.md
View File

@@ -1559,49 +1559,47 @@ GStreamer inner workings.
# Bluetooth LE beacon setup
The python>=3.6 script for running a Bluetooth LE Service Discovery beacon is uxplay-beacon.py.
It provides four possible Bluetooth LE implementations (loaded as modules):
Besides the standard python libraries, it requires python3-psutils.
* **BlueZ** for Linux systems with D-Bus;
It provides four possible Bluetooth LE implementations (loaded as modules `uxplay_beacon_module_*.py`), which may need additional libraries:
* **winrt** for Windows;
* **BlueZ** for Linux systems with D-Bus: needs **GLib** (from python3-gi or PyGObject) and **python-dbus**.
* **BleuIO** for the [BleuIO (or BleuIO Pro) USB dongle](https://www.bleuio.com) with its own on-board Bluetooth-LE Stack that
does not use the host operating system Bluetooth (the host sees the device as a USB serial modem). This is needed for macOS where the
native operating system Bluetooth stack does not allow users to send Bluetooth-LE advertising data
of the "manufacturer-specific" type `AdvData=0xFF`. If a BleuIO dongle (currently costs about USD25) is
available, the BleuIO version of the python script can be used on many operating systems including macOS, Windows, Linux, FreeBSD,
and probably other BSD variants (not tested): it requires python library `python3-pyserial` to be installed. On Linux, users must be members of
group `dialout` or sometimes ``uucp`` (```dialer``` on FreeBSD).
* **winrt** for Windows: requires some **winrt-Windows-\*** libraries.
* **HCI** for Linux without D-Bus (uses utiities `hcitool` and ``hciconfig``) or FreeBSD (uses
`hccontrol`) and requires elevated privileges to access the Host Controller Interface. These privileges can be granted by adding users
to a new group "hciusers" that are given permission to call "`sudo -n hci*`" (``hci*`` = hcitool, hciconfig or hccontrol) without entering a password:
this can be configured by the system administrator using `visudo` (_security implications should be considered_). Use visudo to create a file `hciusers`
in `/etc/sudoers.d/` (Linux)
or `/usr/local/etc/sudoers.d` (FreeBSD), containing the
line "`%hciusers ALL=(ALL) NOPASSWD: <hcitools>`" (where ``<hcitools>`` is replaced
by "`/usr/bin/hcitool, /usr/bin/hciconfig`" (Linux) or "``/usr/sbin/hccontrol``" (FreeBSD). In
* **BleuIO** for all operating systems: requires **pyserial**. This also requires the [BleuIO (or BleuIO Pro) USB dongle](https://www.bleuio.com) which is a USB serial device
with its own on-board Bluetooth LE Stack that does not use the host operating system's stack (the host sees the device as a USB serial modem). This
works on all operating systems that provide access to serial devices, including macOS and \*BSD. On some Linux, users need to be added to the
`dialout` group, on others ``uucp``; on FreeBSD this is the ```dialer``` group, on other \*BSD, it
may be `uucp`.
* **HCI** For Linux and FreeBSD: no extra libraries, but requires root access to the HCI (Host Controller Interface) for Bluetooth devices, using utilities
`hcitool` and ``hciconfig`` (Linux) or ```hccontrol``` (FreeBSD). See below on how to provide such access. In
addition, FreeBSD's `hccontrol` needs a patch to allow generic LE Advertising Data to be input. We have submitted it to FreeBSD as a Pull Request,
and you can find it on the [UxPlay Wiki] (https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0)
and you can find it on the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0). _Note that macOS
has a utility `/usr/sbin/bluetool` that is similar to ``hcitool``, and might allow the HCI module
to be extended to support macOS, but since the BleuIO module is a working solution for macOS, this has not been attempted (Pull Requests with
working implementations are welcome!)._
On Linux, Bluetooth support (using the official Linux Bluetooth stack BlueZ, and D-Bus) must be installed (on Debian-based systems: `sudo apt install bluez bluez-tools`;
recent Ubuntu releases provide bluez as a snap package). BlueZ tools 'hcitool' and 'hciconfig' (needed if you use the HCI module
on Linux) are declared "deprecated" by the BlueZ developers: some Linux distributions
have removed them from the default BleuZ packages, into "extra" packages with names like "bluez-deprecated".
In addition to standard Python3 libraries, you may need to install the gi, dbus, and psutil Python libraries used by
uxplay-beacon.py. On Debian-based systems:
Also install psutil Python libraries used by
uxplay-beacon.py.
On Debian-based systems:
```
sudo apt install python3-gi python3-dbus python3-psutil
sudo apt install python3-psutil
```
If a python3-gi package is available in your Linux distribution, install the python3-gobject package which provides it.
For Windows support in the MSYS2 UCRT64 environment, use pacman -S to
install `mingw-w64-ucrt-x86_64-python`, ``*-python-gobject``,
`*-python-psutil`, and ``*-python-pip``. Then install **winrt**
bindings using pip (or pip3):
For the **BlueZ** module (Linux), install python3-gi (from which GLib is imported) and python3-dbus.
If a python3-gi package is not available in your Linux distribution, use `pip` to install PyGObject instead.
For the **winrt** module, with Windows support in the MSYS2 UCRT64 environment, use pacman -S to
install `mingw-w64-ucrt-x86_64-python`,`*-python-psutil`, and ``*-python-pip``. Then
install **winrt** bindings using pip (or pip3):
```
pip install winrt-Windows.Foundation
@@ -1614,15 +1612,29 @@ For python >= 3.11, the pip commands on "externally-managed" python installation
```
pip install .... --break-system-packages
```
The option `--break-system-packages` was added as a requirement to make users hesitate before
adding packages not provided by the "external management":
_this is unnecessarily scary, as in the case of the winrt packages, no breakage can occur_.
UxPlay must be run with option "`uxplay -ble`" (so it writes data for the Bluetooth beacon in the default BLE
data file `~/.uxplay.ble`), just run ``uxplay-beacon.py`` in a separate terminal. The python script will start
For the **BleuIO** module, install pyserial.
For the **HCI** module, create a group `hciusers` to give group members the privilege of using passwordless ``sudo -n hci*`` (```hci*``` is
`hcitool` and ``hciconfig`` (Linux), or ```hccontrol``` (FreeBSD), and add users of the module to this group
(_security implications should be considered_). In Linux, use "`sudo visudo /etc/sudoers.d/hciusers`" (in FreeBSD,
file is `/usr/local/etc/sudoers.d/hciusers`) to create a file containing one of the lines
```
%hciusers ALL=(ALL) NOPASSWD: /usr/bin/hcitool, /usr/bin/hciconfig (Linux)
%hciusers ALL=(ALL) NOPASSWD: /usr/sbin/hccontrol (FreeBSD)
```
UxPlay must be run with option "`uxplay -ble [path_to_file]`" (so it writes data for the Bluetooth beacon to the default BLE
data file `~/.uxplay.ble`, or optionally to the file specifed by its path), then run ``uxplay-beacon.py [HCI, BleuIO] [--path path_to_file]`` in a separate terminal.
If options HCI or BleuIO are not given, the default module for the operating system will be used (BlueZ for Linux, winrt for Windows, BleuIO for all others).
The python script will start
Bluetooth LE Service-Discovery advertising when it detects that UxPlay is running by checking if the BLE data file exists, and stop when it no longer detects
a running UxPlay plus this file (it will restart advertising if UxPlay later reappears). The script will remain active until stopped with Ctrl+C in its
a running UxPlay (it will restart advertising if UxPlay later reappears). The script will remain active until stopped with Ctrl+C in its
terminal window (or its terminal window is closed).
The beacon script can be more finely controlled using certain options: these can be given on the command line, or read from
@@ -1633,7 +1645,7 @@ options. Get help with `man uxplay-beacon` or ``uxplay-beacon.py --help``.
Options are
* ```<module>``` where "module" is BleuIO or HCI (no intital ``--``) . Without this option, the default module used will be **BlueZ** (Linux), **winrt** (Windows), **BleuIO** (all other operating systems).
* ```<module>``` where "module" is BleuIO or HCI (no initial ``--``) . Without this option, the default module used will be **BlueZ** (Linux), **winrt** (Windows), **BleuIO** (all other operating systems).
* `--file <config file>` read beacon options from ``<config file>`` instead of
@@ -1652,7 +1664,7 @@ These are the only options accepted by the **winrt** module on Windows. The ot
it is chosen flexibly in this range to avoid interfering with other tasks the Bluetooth device is carrying out. The default values are
advmin = advmax = 100. The advertisement is broadcast on all three Bluetooth LE advertising channels: 37,38,39.
On a Windows system, the values of these paramaters are set by the operating system, and cannot be set by users.
On a Windows system, the values of these parameters are set by the operating system, and cannot be set by users.
The **BlueZ** module (Linux) also accepts
@@ -1663,28 +1675,27 @@ on the same host has not been tested, and this option might not be useful or nee
The **BleuIO** and **HCI** modules accept
* `--device x` which allows overiding automatically-made choices of serial ports (**BleuIO**) or hci device nodes (**HCI**). This
* `--device x` which allows overiding automatically-made choices of serial ports (**BleuIO**) or hci devices (**HCI**). This
is probably only useful if the host system has multiple devices that could be used.
The native macOS Bluetooth stack has no documented way for users to send "manufacturer-specific" Bluetooth LE advertisements (such
that sent for AirPlay Service Discovery), and the only support of uxplay-beacon.py on macOS uses a BleuIO USB serial device.
However macOS provides a low-level utility BlueTool (found at `/usr/sbin/bluetool`) that can send HCI commands, so
possibly could be used to adapt the python3 **HCI** module to support macOS as well (_working implementations welcome!_).
__The recommended and working method on macOS is to use a BleuIO dongle.__
The native macOS Bluetooth stack does not allow unprivileged users to send "manufacturer-specific" Bluetooth LE advertisements (such
that sent for AirPlay Service Discovery), and the only current support of uxplay-beacon.py on macOS uses a BleuIO USB serial device.
If you wish to test Bluetooth LE Service Discovery on Linux/*BSD, you can disable DNS_SD Service discovery by the avahi-daemon with
For testing Bluetooth LE Service Discovery you might wish to disable DNS_SD Service discovery (although the Bluetooth LE Service seems to work if DNS_SD
is enabled). On Linux, disable the the avahi-daemon that provides DNS_SD with
```
$ sudo systemctl mask avahi-daemon.socket
$ sudo systemctl stop avahi-daemon
```
(On FreeBSD, "`service avahi-daemon stop`").
To restore DNS_SD Service discovery, replace "mask" by "unmask", and "stop" by "start".
On Windows, the Bonjour Service is controlled using **Services Management**: press "Windows + R" to open the Run dialog,
run `services.msc`, and click on **Bonjour Service** in the alphabetic list. This
will show links for it to be stopped and restarted.

156
README.txt
View File

@@ -1594,44 +1594,41 @@ this to see even more of the GStreamer inner workings.
# Bluetooth LE beacon setup
The python\>=3.6 script for running a Bluetooth LE Service Discovery
beacon is uxplay-beacon.py. It provides four possible Bluetooth LE
implementations (loaded as modules):
beacon is uxplay-beacon.py. Besides the standard python libraries, it
requires python3-psutils.
- **BlueZ** for Linux systems with D-Bus;
It provides four possible Bluetooth LE implementations (loaded as
modules `uxplay_beacon_module_*.py`), which may need additional
libraries:
- **winrt** for Windows;
- **BlueZ** for Linux systems with D-Bus: needs **GLib** (from
python3-gi or PyGObject) and **python-dbus**.
- **BleuIO** for the [BleuIO (or BleuIO Pro) USB
dongle](https://www.bleuio.com) with its own on-board Bluetooth-LE
Stack that does not use the host operating system Bluetooth (the
host sees the device as a USB serial modem). This is needed for
macOS where the native operating system Bluetooth stack does not
allow users to send Bluetooth-LE advertising data of the
"manufacturer-specific" type `AdvData=0xFF`. If a BleuIO dongle
(currently costs about USD25) is available, the BleuIO version of
the python script can be used on many operating systems including
macOS, Windows, Linux, FreeBSD, and probably other BSD variants (not
tested): it requires python library `python3-pyserial` to be
installed. On Linux, users must be members of group `dialout` or
sometimes `uucp` (`dialer` on FreeBSD).
- **winrt** for Windows: requires some **winrt-Windows-\*** libraries.
- **HCI** for Linux without D-Bus (uses utiities `hcitool` and
`hciconfig`) or FreeBSD (uses `hccontrol`) and requires elevated
privileges to access the Host Controller Interface. These privileges
can be granted by adding users to a new group "hciusers" that are
given permission to call "`sudo -n hci*`" (`hci*` = hcitool,
hciconfig or hccontrol) without entering a password: this can be
configured by the system administrator using `visudo` (*security
implications should be considered*). Use visudo to create a file
`hciusers` in `/etc/sudoers.d/` (Linux) or
`/usr/local/etc/sudoers.d` (FreeBSD), containing the line
"`%hciusers ALL=(ALL) NOPASSWD: <hcitools>`" (where `<hcitools>` is
replaced by "`/usr/bin/hcitool, /usr/bin/hciconfig`" (Linux) or
"`/usr/sbin/hccontrol`" (FreeBSD). In addition, FreeBSD's
`hccontrol` needs a patch to allow generic LE Advertising Data to be
input. We have submitted it to FreeBSD as a Pull Request, and you
can find it on the \[UxPlay Wiki\]
(https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0)
- **BleuIO** for all operating systems: requires **pyserial**. This
also requires the [BleuIO (or BleuIO Pro) USB
dongle](https://www.bleuio.com) which is a USB serial device with
its own on-board Bluetooth LE Stack that does not use the host
operating system's stack (the host sees the device as a USB serial
modem). This works on all operating systems that provide access to
serial devices, including macOS and \*BSD. On some Linux, users need
to be added to the `dialout` group, on others `uucp`; on FreeBSD
this is the `dialer` group, on other \*BSD, it may be `uucp`.
- **HCI** For Linux and FreeBSD: no extra libraries, but requires root
access to the HCI (Host Controller Interface) for Bluetooth devices,
using utilities `hcitool` and `hciconfig` (Linux) or `hccontrol`
(FreeBSD). See below on how to provide such access. In addition,
FreeBSD's `hccontrol` needs a patch to allow generic LE Advertising
Data to be input. We have submitted it to FreeBSD as a Pull Request,
and you can find it on the [UxPlay
Wiki](https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0).
*Note that macOS has a utility `/usr/sbin/bluetool` that is similar
to `hcitool`, and might allow the HCI module to be extended to
support macOS, but since the BleuIO module is a working solution for
macOS, this has not been attempted (Pull Requests with working
implementations are welcome!).*
On Linux, Bluetooth support (using the official Linux Bluetooth stack
BlueZ, and D-Bus) must be installed (on Debian-based systems:
@@ -1640,21 +1637,19 @@ bluez as a snap package). BlueZ tools 'hcitool' and 'hciconfig' (needed
if you use the HCI module on Linux) are declared "deprecated" by the
BlueZ developers: some Linux distributions have removed them from the
default BleuZ packages, into "extra" packages with names like
"bluez-deprecated".
"bluez-deprecated". Also install psutil Python libraries used by
uxplay-beacon.py. On Debian-based systems:
In addition to standard Python3 libraries, you may need to install the
gi, dbus, and psutil Python libraries used by uxplay-beacon.py. On
Debian-based systems:
sudo apt install python3-psutil
sudo apt install python3-gi python3-dbus python3-psutil
For the **BlueZ** module (Linux), install python3-gi (from which GLib is
imported) and python3-dbus. If a python3-gi package is not available in
your Linux distribution, use `pip` to install PyGObject instead.
If a python3-gi package is available in your Linux distribution, install
the python3-gobject package which provides it.
For Windows support in the MSYS2 UCRT64 environment, use pacman -S to
install `mingw-w64-ucrt-x86_64-python`, `*-python-gobject`,
`*-python-psutil`, and `*-python-pip`. Then install **winrt** bindings
using pip (or pip3):
For the **winrt** module, with Windows support in the MSYS2 UCRT64
environment, use pacman -S to install
`mingw-w64-ucrt-x86_64-python`,`*-python-psutil`, and `*-python-pip`.
Then install **winrt** bindings using pip (or pip3):
pip install winrt-Windows.Foundation
pip install winrt-Windows.Foundation.Collections
@@ -1671,15 +1666,33 @@ users hesitate before adding packages not provided by the "external
management": *this is unnecessarily scary, as in the case of the winrt
packages, no breakage can occur*.
UxPlay must be run with option "`uxplay -ble`" (so it writes data for
the Bluetooth beacon in the default BLE data file `~/.uxplay.ble`), just
run `uxplay-beacon.py` in a separate terminal. The python script will
start Bluetooth LE Service-Discovery advertising when it detects that
UxPlay is running by checking if the BLE data file exists, and stop when
it no longer detects a running UxPlay plus this file (it will restart
advertising if UxPlay later reappears). The script will remain active
until stopped with Ctrl+C in its terminal window (or its terminal window
is closed).
For the **BleuIO** module, install pyserial.
For the **HCI** module, create a group `hciusers` to give group members
the privilege of using passwordless `sudo -n hci*` (`hci*` is `hcitool`
and `hciconfig` (Linux), or `hccontrol` (FreeBSD), and add users of the
module to this group (*security implications should be considered*). In
Linux, use "`sudo visudo /etc/sudoers.d/hciusers`" (in FreeBSD, file is
`/usr/local/etc/sudoers.d/hciusers`) to create a file containing one of
the lines
%hciusers ALL=(ALL) NOPASSWD: /usr/bin/hcitool, /usr/bin/hciconfig (Linux)
%hciusers ALL=(ALL) NOPASSWD: /usr/sbin/hccontrol (FreeBSD)
UxPlay must be run with option "`uxplay -ble [path_to_file]`" (so it
writes data for the Bluetooth beacon to the default BLE data file
`~/.uxplay.ble`, or optionally to the file specifed by its path), then
run `uxplay-beacon.py [HCI, BleuIO] [--path path_to_file]` in a separate
terminal. If options HCI or BleuIO are not given, the default module for
the operating system will be used (BlueZ for Linux, winrt for Windows,
BleuIO for all others).
The python script will start Bluetooth LE Service-Discovery advertising
when it detects that UxPlay is running by checking if the BLE data file
exists, and stop when it no longer detects a running UxPlay (it will
restart advertising if UxPlay later reappears). The script will remain
active until stopped with Ctrl+C in its terminal window (or its terminal
window is closed).
The beacon script can be more finely controlled using certain options:
these can be given on the command line, or read from a configuration
@@ -1691,7 +1704,7 @@ Get help with `man uxplay-beacon` or `uxplay-beacon.py --help`.
Options are
- `<module>` where "module" is BleuIO or HCI (no intital `--`) .
- `<module>` where "module" is BleuIO or HCI (no initial `--`) .
Without this option, the default module used will be **BlueZ**
(Linux), **winrt** (Windows), **BleuIO** (all other operating
systems).
@@ -1722,7 +1735,7 @@ The other modules accept
are advmin = advmax = 100. The advertisement is broadcast on all
three Bluetooth LE advertising channels: 37,38,39.
On a Windows system, the values of these paramaters are set by the
On a Windows system, the values of these parameters are set by the
operating system, and cannot be set by users.
The **BlueZ** module (Linux) also accepts
@@ -1738,28 +1751,25 @@ The **BlueZ** module (Linux) also accepts
The **BleuIO** and **HCI** modules accept
- `--device x` which allows overiding automatically-made choices of
serial ports (**BleuIO**) or hci device nodes (**HCI**). This is
probably only useful if the host system has multiple devices that
could be used.
serial ports (**BleuIO**) or hci devices (**HCI**). This is probably
only useful if the host system has multiple devices that could be
used.
The native macOS Bluetooth stack has no documented way for users to send
"manufacturer-specific" Bluetooth LE advertisements (such that sent for
AirPlay Service Discovery), and the only support of uxplay-beacon.py on
macOS uses a BleuIO USB serial device. However macOS provides a
low-level utility BlueTool (found at `/usr/sbin/bluetool`) that can send
HCI commands, so possibly could be used to adapt the python3 **HCI**
module to support macOS as well (*working implementations welcome!*).
**The recommended and working method on macOS is to use a BleuIO
dongle.**
The native macOS Bluetooth stack does not allow unprivileged users to
send "manufacturer-specific" Bluetooth LE advertisements (such that sent
for AirPlay Service Discovery), and the only current support of
uxplay-beacon.py on macOS uses a BleuIO USB serial device.
If you wish to test Bluetooth LE Service Discovery on Linux/\*BSD, you
can disable DNS_SD Service discovery by the avahi-daemon with
For testing Bluetooth LE Service Discovery you might wish to disable
DNS_SD Service discovery (although the Bluetooth LE Service seems to
work if DNS_SD is enabled). On Linux, disable the the avahi-daemon that
provides DNS_SD with
$ sudo systemctl mask avahi-daemon.socket
$ sudo systemctl stop avahi-daemon
To restore DNS_SD Service discovery, replace "mask" by "unmask", and
"stop" by "start".
(On FreeBSD, "`service avahi-daemon stop`"). To restore DNS_SD Service
discovery, replace "mask" by "unmask", and "stop" by "start".
On Windows, the Bonjour Service is controlled using **Services
Management**: press "Windows + R" to open the Run dialog, run