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